{"skill":{"slug":"zoho-books","displayName":"Zoho Books","summary":"Zoho Books API integration with managed OAuth. Manage invoices, contacts, bills, expenses, and other accounting data. Use this skill when users want to read,...","description":"---\nname: zoho-books\ndescription: |\n  Zoho Books API integration with managed OAuth. Manage invoices, contacts, bills, expenses, and other accounting data.\n  Use this skill when users want to read, create, update, or delete invoices, contacts, bills, expenses, or other financial records in Zoho Books.\n  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\n  Requires network access and valid Maton API key.\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# Zoho Books\n\nAccess the Zoho Books API with managed OAuth authentication. Manage invoices, contacts, bills, expenses, sales orders, purchase orders, and other accounting data with full CRUD operations.\n\n## Quick Start\n\n```bash\n# List contacts\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://api.maton.ai/zoho-books/books/v3/{endpoint}\n```\n\nMaton proxies requests to `www.zohoapis.com/books/v3` and automatically injects your OAuth token.\n\n## Authentication\n\nAll requests require the Maton API key in the Authorization header:\n\n```\nAuthorization: Bearer $MATON_API_KEY\n```\n\n**Environment Variable:** Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n### Getting Your API Key\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n\n## Connection Management\n\nManage your Zoho Books OAuth connections at `https://api.maton.ai`.\n\n### List Connections\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections?app=zoho-books&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'zoho-books'}).encode()\nreq = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"{connection_id}\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"zoho-books\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple Zoho Books connections, specify which one to use with the `Maton-Connection` header:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '{connection_id}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf you have multiple connections, always include this header to ensure requests go to the intended account.\n\n## Security & Permissions\n\n- Access is scoped to invoices, contacts, bills, expenses, and other accounting data within the connected Zoho Books account.\n- **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.\n\n## API Reference\n\n### Available Modules\n\nZoho Books organizes data into modules. Key modules include:\n\n| Module | Endpoint | Description |\n|--------|----------|-------------|\n| Contacts | `/contacts` | Customers and vendors |\n| Invoices | `/invoices` | Sales invoices |\n| Bills | `/bills` | Vendor bills |\n| Expenses | `/expenses` | Business expenses |\n| Sales Orders | `/salesorders` | Sales orders |\n| Purchase Orders | `/purchaseorders` | Purchase orders |\n| Credit Notes | `/creditnotes` | Customer credit notes |\n| Recurring Invoices | `/recurringinvoices` | Automated recurring invoices |\n| Recurring Bills | `/recurringbills` | Automated recurring bills |\n\n### Contacts\n\n#### List Contacts\n\n```bash\nGET /zoho-books/books/v3/contacts\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"code\": 0,\n  \"message\": \"success\",\n  \"contacts\": [...],\n  \"page_context\": {\n    \"page\": 1,\n    \"per_page\": 200,\n    \"has_more_page\": false,\n    \"sort_column\": \"contact_name\",\n    \"sort_order\": \"A\"\n  }\n}\n```\n\n#### Get Contact\n\n```bash\nGET /zoho-books/books/v3/contacts/{contact_id}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Create Contact\n\n```bash\nPOST /zoho-books/books/v3/contacts\nContent-Type: application/json\n\n{\n  \"contact_name\": \"Customer Name\",\n  \"contact_type\": \"customer\"\n}\n```\n\n**Required Fields:**\n- `contact_name` - Display name for the contact\n- `contact_type` - Either `customer` or `vendor`\n\n**Optional Fields:**\n- `company_name` - Legal entity name\n- `email` - Email address\n- `phone` - Phone number\n- `billing_address` - Address object\n- `payment_terms` - Days for payment\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({\n    \"contact_name\": \"Acme Corporation\",\n    \"contact_type\": \"customer\",\n    \"company_name\": \"Acme Corp\",\n    \"email\": \"billing@acme.com\",\n    \"phone\": \"+1-555-1234\"\n}).encode()\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"code\": 0,\n  \"message\": \"The contact has been added.\",\n  \"contact\": {\n    \"contact_id\": \"8527119000000099001\",\n    \"contact_name\": \"Acme Corporation\",\n    \"company_name\": \"Acme Corp\",\n    \"contact_type\": \"customer\",\n    ...\n  }\n}\n```\n\n#### Update Contact\n\n```bash\nPUT /zoho-books/books/v3/contacts/{contact_id}\nContent-Type: application/json\n\n{\n  \"contact_name\": \"Updated Name\",\n  \"phone\": \"+1-555-9999\"\n}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({\n    \"contact_name\": \"Acme Corporation Updated\",\n    \"phone\": \"+1-555-9999\"\n}).encode()\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', data=data, method='PUT')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Delete Contact\n\n```bash\nDELETE /zoho-books/books/v3/contacts/{contact_id}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"code\": 0,\n  \"message\": \"The customer has been deleted.\"\n}\n```\n\n### Invoices\n\n#### List Invoices\n\n```bash\nGET /zoho-books/books/v3/invoices\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/invoices')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Get Invoice\n\n```bash\nGET /zoho-books/books/v3/invoices/{invoice_id}\n```\n\n#### Create Invoice\n\n```bash\nPOST /zoho-books/books/v3/invoices\nContent-Type: application/json\n\n{\n  \"customer_id\": \"8527119000000099001\",\n  \"line_items\": [\n    {\n      \"item_id\": \"8527119000000100001\",\n      \"quantity\": 1,\n      \"rate\": 100.00\n    }\n  ]\n}\n```\n\n**Required Fields:**\n- `customer_id` - Customer identifier\n- `line_items` - Array of items with `item_id` or manual entry\n\n**Optional Fields:**\n- `invoice_number` - Auto-generated if not specified\n- `date` - Invoice date (yyyy-mm-dd format)\n- `due_date` - Payment due date\n- `discount` - Percentage or fixed amount\n- `payment_terms` - Days until due\n\n#### Update Invoice\n\n```bash\nPUT /zoho-books/books/v3/invoices/{invoice_id}\n```\n\n#### Delete Invoice\n\n```bash\nDELETE /zoho-books/books/v3/invoices/{invoice_id}\n```\n\n#### Invoice Actions\n\n```bash\n# Mark as sent\nPOST /zoho-books/books/v3/invoices/{invoice_id}/status/sent\n\n# Void invoice\nPOST /zoho-books/books/v3/invoices/{invoice_id}/status/void\n\n# Email invoice\nPOST /zoho-books/books/v3/invoices/{invoice_id}/email\n```\n\n### Bills\n\n#### List Bills\n\n```bash\nGET /zoho-books/books/v3/bills\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/bills')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Create Bill\n\n```bash\nPOST /zoho-books/books/v3/bills\nContent-Type: application/json\n\n{\n  \"vendor_id\": \"8527119000000099002\",\n  \"bill_number\": \"BILL-001\",\n  \"date\": \"2026-02-06\",\n  \"line_items\": [\n    {\n      \"account_id\": \"8527119000000100002\",\n      \"description\": \"Office Supplies\",\n      \"amount\": 150.00\n    }\n  ]\n}\n```\n\n**Required Fields:**\n- `vendor_id` - Vendor identifier\n- `bill_number` - Unique bill number\n- `date` - Bill date (yyyy-mm-dd)\n\n#### Update Bill\n\n```bash\nPUT /zoho-books/books/v3/bills/{bill_id}\n```\n\n#### Delete Bill\n\n```bash\nDELETE /zoho-books/books/v3/bills/{bill_id}\n```\n\n### Expenses\n\n#### List Expenses\n\n```bash\nGET /zoho-books/books/v3/expenses\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/expenses')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Create Expense\n\n```bash\nPOST /zoho-books/books/v3/expenses\nContent-Type: application/json\n\n{\n  \"account_id\": \"8527119000000100003\",\n  \"date\": \"2026-02-06\",\n  \"amount\": 75.50,\n  \"paid_through_account_id\": \"8527119000000100004\",\n  \"description\": \"Business lunch\"\n}\n```\n\n**Required Fields:**\n- `account_id` - Expense account ID\n- `date` - Expense date (yyyy-mm-dd)\n- `amount` - Expense amount\n- `paid_through_account_id` - Payment account ID\n\n**Optional Fields:**\n- `description` - Expense details\n- `customer_id` - Billable customer ID\n- `is_billable` - Boolean for billable expenses\n- `project_id` - Associated project\n\n#### Update Expense\n\n```bash\nPUT /zoho-books/books/v3/expenses/{expense_id}\n```\n\n#### Delete Expense\n\n```bash\nDELETE /zoho-books/books/v3/expenses/{expense_id}\n```\n\n### Sales Orders\n\n#### List Sales Orders\n\n```bash\nGET /zoho-books/books/v3/salesorders\n```\n\n#### Create Sales Order\n\n```bash\nPOST /zoho-books/books/v3/salesorders\n```\n\n### Purchase Orders\n\n#### List Purchase Orders\n\n```bash\nGET /zoho-books/books/v3/purchaseorders\n```\n\n#### Create Purchase Order\n\n```bash\nPOST /zoho-books/books/v3/purchaseorders\n```\n\n### Credit Notes\n\n#### List Credit Notes\n\n```bash\nGET /zoho-books/books/v3/creditnotes\n```\n\n### Recurring Invoices\n\n#### List Recurring Invoices\n\n```bash\nGET /zoho-books/books/v3/recurringinvoices\n```\n\n### Recurring Bills\n\n#### List Recurring Bills\n\n```bash\nGET /zoho-books/books/v3/recurringbills\n```\n\n## Pagination\n\nZoho Books uses page-based pagination:\n\n```bash\nGET /zoho-books/books/v3/contacts?page=1&per_page=50\n```\n\nResponse includes pagination info in `page_context`:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"success\",\n  \"contacts\": [...],\n  \"page_context\": {\n    \"page\": 1,\n    \"per_page\": 50,\n    \"has_more_page\": true,\n    \"sort_column\": \"contact_name\",\n    \"sort_order\": \"A\"\n  }\n}\n```\n\nContinue fetching while `has_more_page` is `true`, incrementing `page` each time.\n\n## Code Examples\n\n### JavaScript\n\n```javascript\nconst response = await fetch(\n  'https://api.maton.ai/zoho-books/books/v3/contacts',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`\n    }\n  }\n);\nconst data = await response.json();\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\nresponse = requests.get(\n    'https://api.maton.ai/zoho-books/books/v3/contacts',\n    headers={'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'}\n)\ndata = response.json()\n```\n\n## Notes\n\n- All successful responses have `code: 0` and a `message` field\n- Dates should be in `yyyy-mm-dd` format\n- Contact types are `customer` or `vendor`\n- Some modules (items, chart of accounts, bank accounts, projects) may require additional OAuth scopes. If you receive a scope error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case\n- Rate limits: 100 requests/minute per organization\n- Daily limits vary by plan: Free (1,000), Standard (2,000), Professional (5,000), Paid (10,000)\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Missing Zoho Books connection or invalid request |\n| 401 | Invalid or missing Maton API key, or OAuth scope mismatch |\n| 404 | Resource not found |\n| 429 | Rate limited |\n| 4xx/5xx | Passthrough error from Zoho Books API |\n\n### Common Error Codes\n\n| Code | Description |\n|------|-------------|\n| 0 | Success |\n| 57 | Not authorized (OAuth scope mismatch) |\n| 1 | Invalid value |\n| 2 | Mandatory field missing |\n| 3 | Resource does not exist |\n| 5 | Invalid URL |\n\n### Troubleshooting: API Key Issues\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `zoho-books`. For example:\n\n- Correct: `https://api.maton.ai/zoho-books/books/v3/contacts`\n- Incorrect: `https://api.maton.ai/books/v3/contacts`\n\n## Resources\n\n- [Zoho Books API v3 Introduction](https://www.zoho.com/books/api/v3/introduction/)\n- [Zoho Books Invoices API](https://www.zoho.com/books/api/v3/invoices/)\n- [Zoho Books Contacts API](https://www.zoho.com/books/api/v3/contacts/)\n- [Zoho Books Bills API](https://www.zoho.com/books/api/v3/bills/)\n- [Zoho Books Expenses API](https://www.zoho.com/books/api/v3/expenses/)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","tags":{"latest":"1.0.3"},"stats":{"comments":0,"downloads":4494,"installsAllTime":2,"installsCurrent":2,"stars":3,"versions":4},"createdAt":1770496834336,"updatedAt":1781739755927},"latestVersion":{"version":"1.0.3","createdAt":1777590914086,"changelog":"- Updated all endpoint URLs from gateway.maton.ai and ctrl.maton.ai to api.maton.ai for consistency and clarity.\n- Removed LICENSE.txt file.\n- Added security guidance: explicitly note that all write operations require explicit user approval and should confirm target resource and effect with the user.\n- Improved documentation for connection management and clarified the need for the `Maton-Connection` header when using multiple connections.","license":"MIT-0"},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"byungkyu","userId":"s174c3s2kc1ehqj1ytzntezj2983e2aj","displayName":"byungkyu","image":"https://avatars.githubusercontent.com/u/16563684?v=4"},"moderation":null}