Zoho Books API Integration Guide
This guide provides a comprehensive, step-by-step framework for your development team to
integrate Zoho Books with an external system. It covers the foundational setup, including API
credential retrieval, and the complete invoice creation workflow with practical examples and
validation checks.
Part 1: Initial Setup and Authentication
This section covers the one-time setup required to establish a secure connection with the
Zoho Books API.
1. Registering Your Application and Getting Credentials
To get started, you must register your application in the Zoho Developer Console. This will
generate the unique credentials required for API calls.
App Type: Select "Self Client." This is the appropriate choice for a server-side
application that operates without user intervention for authentication after the initial
setup.
Access the Console: Navigate to the Zoho Developer Console.
Create a New Client: Click Add Client and fill in the details. The "Homepage URL" and
"Authorized Redirect URIs" are not required for a Self Client.
Retrieve Credentials: Once created, you will be provided with a Client ID and a Client
Secret. These are your primary credentials and must be stored securely.
2. Generating and Managing API Tokens
Zoho's API uses OAuth 2.0. The access_token is used for all API calls but expires every hour.
The refresh_token is a long-lived token used to generate a new access_token when needed.
Generating Tokens: Initially, you need a temporary code to get your first
access_token and refresh_token. You can generate this code in the Zoho Developer
Console under the "Self Client" tab.
Exchanging the code: Make a POST request to the token endpoint to exchange your
code for the tokens. The response will be similar to the example you provided.
{
"access_token":
"1000.4b29607a58492329738243d3bb39a4e2.861a194bf1233e685a1085461c71e9e
4",
"refresh_token":
"1000.afd80ba3c62484ff49bd5d856716e771.3fef10f75aa07924a8528efa2be4f7fd",
"scope": "ZohoBooks.invoices.CREATE",
"api_domain": "[https://www.zohoapis.in](https://www.zohoapis.in)",
"token_type": "Bearer",
"expires_in": 3600
Token Management Logic: Your server-side code must manage the tokens by storing
the refresh_token securely and implementing a refresh mechanism for the
access_token as described in Part 2.
3. Locating Your Zoho Organization ID
The organization_id is a mandatory parameter for nearly every Zoho Books API request. It's
how the API knows which business account to operate on. If you have multiple businesses
within Zoho, each will have a unique ID.
Finding the ID: To find your organization_id, log in to your Zoho Books account. It is
often visible in the URL of your dashboard or under your profile settings.
Organization Creation: An organization is your core business entity in Zoho Books.
It's not something you typically create via the API for a transactional flow. You'll
create your primary organization manually in the Zoho Books web application. If you
have a legitimate business need for creating multiple organizations, the API does
support this, but it requires a different set of scopes and is a separate process from
transactional invoicing.
Part 2: Invoice Creation Workflow
This section outlines the logical flow and specific API calls to automate invoice creation after
a payment is received.
1. Token Refresh Mechanism
Before any API call, your code must ensure the access_token is valid.
API Call: Refreshing the Access Token
o Endpoint: POST https://accounts.zoho.in/oauth/v2/token
o Request Body (as form-data):
client_id: [Your Client ID]
client_secret: [Your Client Secret]
grant_type: refresh_token
refresh_token: [Your Stored Refresh Token]
Validation: Check the response for a new access_token. Update your stored token
with the new value and the new expiration time. Handle a failed refresh gracefully.
2. Customer (Contact) Management
An invoice must be linked to a contact. You should first search for the customer by their
email and, if they don't exist, create a new one.
API Call: Search for a Contact
o Endpoint: GET https://www.zohoapis.in/books/v3/contacts?
organization_id={Your_Org_ID}&email={customer_email}
o Authorization Header: Authorization: Zoho-oauthtoken {your_access_token}
o Logic: Parse the response to get the contact_id.
API Call: Create a New Contact (if one doesn't exist)
o Endpoint: POST https://www.zohoapis.in/books/v3/contacts?
organization_id={Your_Org_ID}
o Authorization Header: Authorization: Zoho-oauthtoken {your_access_token}
o Request Body (JSON):
o {
o "contact_name": "[Customer Name from Razorpay]",
o "contact_type": "customer",
o "email": "[Customer Email from Razorpay]",
o "phone": "[Customer Phone from Razorpay]"
o }
o Validation: The response will contain the contact_id of the new customer.
3. Creating the Invoice
With the contact_id and a valid access_token, you can create the invoice.
API Call: Create an Invoice
o Endpoint: POST https://www.zohoapis.in/books/v3/invoices?
organization_id={Your_Org_ID}
o Authorization Header: Authorization: Zoho-oauthtoken {your_access_token}
o Request Body (JSON):
o {
o "customer_id": "[Contact_ID from Step 2]",
o "date": "2025-09-08",
o "line_items": [
o {
o "name": "[Service Name from your dashboard]",
o "item_id": "[Zoho_Books_Item_ID]",
o "rate": "[Payment Amount from Razorpay]",
o "quantity": 1
o }
o ],
o "invoices_number": "[Optional: Your internal invoice number]",
o "payment_options": {
o "payment_gateways": [
o {
o "gateway_name": "razorpay"
o }
o ]
o },
o "send": false
o }
Validation:
o A 201 Created or 200 OK status code indicates success.
o A 400 Bad Request or 500 Server Error indicates a failure. The response body
will contain a specific error message.
Document Version
Version: 2.0 Date: September 8, 2025 Description: Comprehensive guide for Zoho Books API
integration, including authentication setup, credential retrieval, and the full invoice creation
workflow.
