A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Zoho Books API is how an app or AI agent works with a Zoho Books organization: creating and emailing invoices, adding customers and vendors, recording bills and expenses, and applying customer payments. Access is granted through an OAuth access token whose granular scopes set which modules a call can read or write, and every request names a single organization so access stays bounded to one business at a time. Zoho Books does not mint new version numbers; it ships changes through its product release notes.
How an app or AI agent connects to Zoho Books determines what it can reach. There is a route for making calls, governed by an OAuth access token and the granular scopes behind it, and a hosted server that exposes Zoho Books tools to agents. Every call also names a single organization, so access is bounded to one business entity at a time.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a page number, at a regional host such as https://www.zohoapis.com/books/v3. A call authenticates with an OAuth access token sent as Authorization: Zoho-oauthtoken, and every request carries an organization_id query parameter naming the business entity to act on.
Zoho runs a first-party Model Context Protocol service, managed at mcp.zoho.com, that exposes Zoho Books tools to AI agents and clients like Claude. An admin enables it, a per-user server URL carrying a secret API key is generated, and the admin chooses which tools and data each agent can reach. Tools cover actions such as creating and sending invoices, recording expenses, adding customers and items, and reconciling bank transactions. Zoho Books is also a default connector in Claude.
Zoho Books does not ship a fixed catalog of webhook events. Instead, an admin creates a workflow rule in the organization, sets the condition that should trigger it, and attaches a webhook action that POSTs to a configured HTTP or HTTPS URL when the rule fires. This lets an integration learn about activity, like an invoice being created or a payment recorded, without polling.
Zoho Books authenticates every API call with OAuth 2.0. An app registers in the Zoho Developer Console, sends a user through the authorization-code flow, and exchanges the grant for an access token plus a refresh token. The access token is sent as Authorization: Zoho-oauthtoken and is restricted to the granular scopes the user consented to, such as ZohoBooks.invoices.READ or ZohoBooks.contacts.ALL. An access token lasts one hour; the refresh token does not expire until it is revoked.
A single scope, ZohoBooks.fullaccess.all, grants read and write across every Zoho Books module. It is convenient for a trusted server integration but reaches the entire organization, so a least-privilege setup requests only the per-module scopes an agent needs instead.
The Zoho Books API is split into modules an agent can act on, like invoices, contacts, estimates, bills, expenses, payments, and banking. Each module has its own methods, and a write in some of them sends documents to customers or changes the accounting record.
Methods for creating, sending, and managing customer invoices.
Methods for working with customers and vendors.
Methods for working with quotes and estimates.
Methods for working with sales orders.
Methods for working with vendor bills.
Methods for working with purchase orders.
Methods for working with recorded expenses.
Methods for recording and managing payments received from customers.
Methods for working with the products and services catalog.
Methods for working with bank accounts and the chart of accounts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
InvoicesMethods for creating, sending, and managing customer invoices.7 | ||||||
| GET | /invoices | List all invoices in the organization, with filters and pagination. | read | invoices.READ | Current | |
Full scope: ZohoBooks.invoices.READ. Acts oninvoice Permission (capability) invoices.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /invoices/{invoice_id} | Retrieve the details of a specific invoice. | read | invoices.READ | Current | |
Full scope: ZohoBooks.invoices.READ. Acts oninvoice Permission (capability) invoices.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices | Create an invoice for a customer. | write | invoices.CREATE | Current | |
Full scope: ZohoBooks.invoices.CREATE. The invoice starts as a draft unless sent. Acts oninvoice Permission (capability) invoices.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /invoices/{invoice_id} | Update an existing invoice. | write | invoices.UPDATE | Current | |
Full scope: ZohoBooks.invoices.UPDATE. Acts oninvoice Permission (capability) invoices.UPDATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /invoices/{invoice_id} | Delete an existing invoice. | write | invoices.DELETE | Current | |
Full scope: ZohoBooks.invoices.DELETE. Only invoices in certain states can be deleted. Acts oninvoice Permission (capability) invoices.DELETEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice_id}/status/sent | Mark a draft invoice as sent. | write | invoices.UPDATE | Current | |
Full scope: ZohoBooks.invoices.UPDATE. Moves the invoice out of draft. Acts oninvoice Permission (capability) invoices.UPDATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice_id}/email | Email an invoice to the customer. | write | invoices.CREATE | Current | |
Full scope: ZohoBooks.invoices.CREATE. Sends a real email to the customer's address. Acts oninvoice Permission (capability) invoices.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts (customers & vendors)Methods for working with customers and vendors.5 | ||||||
| GET | /contacts | List all contacts (customers and vendors). | read | contacts.READ | Current | |
Full scope: ZohoBooks.contacts.READ. Acts oncontact Permission (capability) contacts.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts/{contact_id} | Retrieve a specific contact's details. | read | contacts.READ | Current | |
Full scope: ZohoBooks.contacts.READ. Acts oncontact Permission (capability) contacts.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts | Create a customer or vendor contact. | write | contacts.CREATE | Current | |
Full scope: ZohoBooks.contacts.CREATE. Acts oncontact Permission (capability) contacts.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /contacts/{contact_id} | Update an existing contact. | write | contacts.UPDATE | Current | |
Full scope: ZohoBooks.contacts.UPDATE. Acts oncontact Permission (capability) contacts.UPDATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /contacts/{contact_id} | Delete an existing contact. | write | contacts.DELETE | Current | |
Full scope: ZohoBooks.contacts.DELETE. Acts oncontact Permission (capability) contacts.DELETEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EstimatesMethods for working with quotes and estimates.3 | ||||||
| GET | /estimates | List all estimates (quotes) in the organization. | read | estimates.READ | Current | |
Full scope: ZohoBooks.estimates.READ. Acts onestimate Permission (capability) estimates.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /estimates | Create an estimate (a quote or proposal) for a customer. | write | estimates.CREATE | Current | |
Full scope: ZohoBooks.estimates.CREATE. Acts onestimate Permission (capability) estimates.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /estimates/{estimate_id}/email | Email an estimate to the customer. | write | estimates.CREATE | Current | |
Full scope: ZohoBooks.estimates.CREATE. Sends a real email to the customer. Acts onestimate Permission (capability) estimates.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sales ordersMethods for working with sales orders.2 | ||||||
| POST | /salesorders | Create a sales order for a customer. | write | salesorders.CREATE | Current | |
Full scope: ZohoBooks.salesorders.CREATE. Acts onsalesorder Permission (capability) salesorders.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /salesorders | List all sales orders in the organization. | read | salesorders.READ | Current | |
Full scope: ZohoBooks.salesorders.READ. Acts onsalesorder Permission (capability) salesorders.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BillsMethods for working with vendor bills.2 | ||||||
| POST | /bills | Create a bill recording money the business owes a vendor. | write | bills.CREATE | Current | |
Full scope: ZohoBooks.bills.CREATE. Acts onbill Permission (capability) bills.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /bills | List all vendor bills in the organization. | read | bills.READ | Current | |
Full scope: ZohoBooks.bills.READ. Acts onbill Permission (capability) bills.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Purchase ordersMethods for working with purchase orders.2 | ||||||
| POST | /purchaseorders | Create a purchase order for a vendor. | write | purchaseorders.CREATE | Current | |
Full scope: ZohoBooks.purchaseorders.CREATE. Acts onpurchaseorder Permission (capability) purchaseorders.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /purchaseorders | List all purchase orders in the organization. | read | purchaseorders.READ | Current | |
Full scope: ZohoBooks.purchaseorders.READ. Acts onpurchaseorder Permission (capability) purchaseorders.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ExpensesMethods for working with recorded expenses.2 | ||||||
| POST | /expenses | Record an expense. | write | expenses.CREATE | Current | |
Full scope: ZohoBooks.expenses.CREATE. Acts onexpense Permission (capability) expenses.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /expenses | List all recorded expenses in the organization. | read | expenses.READ | Current | |
Full scope: ZohoBooks.expenses.READ. Acts onexpense Permission (capability) expenses.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Customer paymentsMethods for recording and managing payments received from customers.3 | ||||||
| POST | /customerpayments | Record a payment received from a customer. | write | customerpayments.CREATE | Current | |
Full scope: ZohoBooks.customerpayments.CREATE. Applies the payment against one or more invoices. Acts oncustomerpayment Permission (capability) customerpayments.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customerpayments | List all customer payments in the organization. | read | customerpayments.READ | Current | |
Full scope: ZohoBooks.customerpayments.READ. Acts oncustomerpayment Permission (capability) customerpayments.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /customerpayments/{payment_id} | Delete a recorded customer payment. | write | customerpayments.DELETE | Current | |
Full scope: ZohoBooks.customerpayments.DELETE. Removes the payment and unapplies it from invoices. Acts oncustomerpayment Permission (capability) customerpayments.DELETEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsMethods for working with the products and services catalog.2 | ||||||
| POST | /items | Create an item (a product or service) in the catalog. | write | settings.CREATE | Current | |
Items use the settings scope. Full scope: ZohoBooks.settings.CREATE. Acts onitem Permission (capability) settings.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /items | List all items in the products and services catalog. | read | settings.READ | Current | |
Items use the settings scope. Full scope: ZohoBooks.settings.READ. Acts onitem Permission (capability) settings.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Banking & accountsMethods for working with bank accounts and the chart of accounts.4 | ||||||
| GET | /bankaccounts | List all bank and credit card accounts in the organization. | read | banking.READ | Current | |
Full scope: ZohoBooks.banking.READ. Acts onbankaccount Permission (capability) banking.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /bankaccounts | Create a bank or credit card account. | write | banking.CREATE | Current | |
Full scope: ZohoBooks.banking.CREATE. Acts onbankaccount Permission (capability) banking.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /chartofaccounts | List all accounts in the chart of accounts. | read | accountants.READ | Current | |
Chart of accounts uses the accountants scope. Full scope: ZohoBooks.accountants.READ. Acts onchartofaccount Permission (capability) accountants.READVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /chartofaccounts | Create an account in the chart of accounts. | write | accountants.CREATE | Current | |
Chart of accounts uses the accountants scope. Full scope: ZohoBooks.accountants.CREATE. Acts onchartofaccount Permission (capability) accountants.CREATEVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Zoho Books can notify an app when something happens in an organization, like an invoice being created or a payment recorded. Notifications are set up as a workflow rule with a webhook action, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|
Zoho Books limits how often an app can call, by a per-minute rate measured per organization and by a separate daily call budget that depends on the plan.
Zoho Books meters calls per organization, not by a per-method cost. It returns HTTP 429 if more than 100 requests arrive in a minute for one organization. A separate daily budget depends on the plan, with documented ceilings of 1,000 calls on the Free plan, 2,000 on Standard, 5,000 on Professional, and 10,000 on Premium and higher tiers. A concurrency limit also caps how many calls can run at once for an organization. A 429 carries no Retry-After header, so the caller supplies its own backoff.
A list endpoint is page-based. The page parameter selects the page and per_page sets how many records come back, which defaults to 200. The response includes a page_context node describing the current page and whether more pages remain.
A list endpoint returns up to 200 records per page by default through per_page. Every call must include the organization_id query parameter to scope it to one business entity.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | code (in body) | The request was malformed or a parameter was invalid. The body carries a numeric code and a message describing the problem. | Read the message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | Authentication failed: the OAuth access token is missing, expired, or invalid. | Refresh the access token using the refresh token, then retry. Confirm the token carries the scope the call needs. |
| 404 | 1002 | The requested resource does not exist, for example an invoice id that is not found in this organization. | Verify the id and the organization_id, and confirm the record belongs to that organization. |
| 405 | Method Not Allowed | The HTTP method is not supported for this endpoint. | Use the documented method for the endpoint (for example PUT to update, not POST). |
| 429 | Rate limit exceeded | The per-minute or per-day call limit for the organization was exceeded. No Retry-After header is returned. | Back off and retry with the integration's own backoff logic, and smooth the request rate. |
| 500 | 1000 | An internal error occurred on Zoho's side. | Retry after a short delay, and contact Zoho support if it persists. |
Zoho Books runs a single dated API version in its path, v3, and ships changes through its product release notes rather than minting new version numbers.
Zoho Books serves its API under a single dated path segment, v3, and ships changes through product release notes rather than minting new version numbers. New modules and fields are added in place. Recent product updates have introduced a Developer Space with an API Usage dashboard for managing API calls and connections.
Zoho Books keeps the v3 API stable and ships dated product changes through its What's New page instead of new version numbers. These updates add or adjust behavior within v3 without breaking existing calls.
Build against v3 and track changes through the release notes.
Zoho Books What's New ↗Bollard AI sits between a team's AI agents and Zoho Books. Grant each agent exactly the access it needs, read or write, module by module, and every call is checked and logged.