• Documentation >
• Apps >
• Commerce >
• Zoho Books

Zoho Books

Getting Started with Zoho Books

The Zoho Books modules allow you to create, list, retrieve, update and delete contacts, persons, invoices, payments, expenses and bills in your Zoho Books account.

Prerequisites

• A Zoho Books account

In order to use Zoho Books with Ibexa Connect, it is necessary to have a Zoho Books account. If you do not have one, you can create a Zoho Books account at www.zoho.com/books/signup.

Note

The module dialog fields that are displayed in bold (in the Ibexa Connect scenario, not in this documentation article) are mandatory!

Connecting Zoho Books to Ibexa Connect

To connect your Zoho Books account to Ibexa Connect select your region and follow the general instructions for Connecting to services.

After you click the Continue button, Ibexa Connect will redirect you to the Zoho Books website where you will be prompted to grant Ibexa Connect access to your account.

Confirm the dialog by clicking the Accept button.

(Reference: Zoho Books API Documentation.)

Contacts

Watch Vendor

Triggers when a vendor is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Watch Customer

Triggers when a customer is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Create a Contact

Creates a new customer contact.

Required Permissions: ZohoBooks.contacts.CREATE, ZohoBooks.settings.READ

Organization	Select the organization you want to create a contact for.
Contact Name	Enter the name of the new customer.
Company Name	Enter the company name of the contact.
Website	Enter the contact's website.
Language Code	Enter the language code for the customer.
Contact Type	Enter the contact type. Enter customer or vendor. Default: customer.
Is Portal Enabled	Select the Yes option to allow client portal access for this contact.	Contact persons in the Contact Persons field must be added in order to use this function.

Currency

Select the currency for the new contact.

Payment Terms

Enter the net payment term for the contact. E.g. 15. Invoice due date will be calculated based on this.

Payment Terms Label

Enter a custom label for the payment term specified above to override the default payment term label. E.g. default value for 15 days is "Net 15 Days".

Notes

Enter remarks about the payment made by the contact.

Facebook

Enter the contact's Facebook account URL.

Twitter

Enter the contact's Twitter account URL.

Contact Persons

Here you can add the primary contact for the new contact.

Get a Contact

Retrieves contact details.

Required Permissions: ZohoBooks.contacts.READ

Organization	Select the organization you want to retrieve the contact from.
Contact ID	Map or select the Contact ID of the contact you want to retrieve information about.

List Contacts

Returns contacts based on the filter settings.

Required Permissions: ZohoBooks.contacts.READ

Organization	Select the organization you want to retrieve the contact from.
Search Criteria	Here you can define the search criteria for your search. For example, the following search returns all contacts whose email address contains "gmail.com".
Limit	Set the maximum number of contacts Ibexa Connect will return during one execution cycle.
Filter By	Select the status you want to use to filter the contacts.
Search Text	Returns only contacts that contain entered text in the contact name or in the comments fields.
Sort Column	Select the parameter you want to filter results by.

Update Contact

Updates an existing contact.

Required Permissions: ZohoBooks.contacts.UPDATE, ZohoBooks.contacts.READ, ZohoBooks.settings.READ

Organization	Select the organization that contains the contact you want to update.
Contact ID	Map or select the Contact ID of the contact you want to update.

Please find the descriptions of the fields in the Create a Contact section above.

Delete a Contact

Deletes an existing contact.

Required Permissions: ZohoBooks.contacts.DELETE, ZohoBooks.contacts.READ

Organization	Select the organization that contains the contact you want to delete.
Contact ID	Map or select the Contact ID of the contact you want to delete.

Contact Persons

Create a Contact Person

Creates and assigns a contact person to the existing contact.

Required Permissions: ZohoBooks.contacts.CREATE, ZohoBooks.settings.READ

Organization	Select the organization that contains the contact you want to delete.
Contact ID	Map or select the Contact ID of the contact you want to assign the contact person to.
First Name	Enter the person's first name.
Last Name	Enter the person's last name.
Salutation	Enter the salutation for the contact.
Email	Enter the contact's email.
Phone	Enter the contact's phone number.
Mobile	Enter the contact's mobile phone number.
Skype	Enter the contact's Skype name.
Designation	Enter the designation of the person.
Department	Enter the department to which the person belongs.
Enable Portal	Select the Yes option to enable the client portal access.

Get a Contact Person

Retrieves details for a specified contact person.

Required Permissions: ZohoBooks.contacts.READ

Organization	Select the organization that contains the contact person you want to retrieve information about.
Contact ID	Map or select the Contact ID of the contact that contains the contact person.
Contact Person ID	Enter (map) the Contact Person ID of the contact person you want to retrieve details about.

List Contact Persons

Lists all contact persons.

Required Permissions: ZohoBooks.contacts.READ

Organization	Select the organization that contains the contact persons you want to list.
Contact ID	Map or select the Contact ID you want to list contact persons from.
Limit	Set the maximum limit of contact persons Ibexa Connect will return during one execution cycle.

Update a Contact Person

Updates an existing contact person.

Required Permissions: ZohoBooks.contacts.UPDATE, ZohoBooks.contacts.READ

Organization	Select the organization that contains the contact person you want to update.
Contact ID	Map or select the Contact ID of the contact person you want to update.
Contact Person ID	Enter (map) the Contact Person ID of the contact person whose details you want to update.

Please find the descriptions of the fields in the Create a Contact Person section above.

Delete a Contact Person

Deletes an existing contact person.

Required Permissions: ZohoBooks.contacts.DELETE, ZohoBooks.contacts.READ

Organization	Select the organization that contains the contact person you want to delete.
Contact ID	Map or select the Contact ID that contains the contact person you want to delete.
Contact Person ID	Enter (map) the Contact Person ID of the contact person you want to delete.

Invoices

Watch Invoice

Triggers when an invoice is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Create an Invoice

Creates an invoice for the customer.

Required Permissions: ZohoBooks.invoices.READ, ZohoBooks.invoices.CREATE, ZohoBooks.contacts.READ, ZohoBooks.expenses.READ, ZohoBooks.projects.READ, ZohoBooks.settings.READ

Organization	Select your organization.
Customer ID	Map or select the Customer ID of the customer you want to create the invoice for.
Contact Persons	Add contact persons you want to associate with the invoice.
Ignore Auto Number Generation?	Enable this option to define the invoice number manually.	If this option is enabled, the Invoice Number field must be filled.

Send this invoice?

Enable this option to send the invoice to the contact person(s) associated with the invoice.

Invoice Date

Set the date when the invoice is issued. Please use the yyyy-mm-dd date format

Due Date

Set the due date of the invoice. Please use the yyyy-mm-dd date format

Payment Terms

Enter net payment terms in days e.g. 15, 30, 60. Invoice due date will be calculated based on this.

Payment Terms Label

Enter a custom label for the payment term specified above to override the default payment terms label. E.g. default value for 15 days is "Net 15 Days".

Discount

Discount applied to the invoice. It can be either in % or in amount. e.g. 12.5% or 190.

Is discount before tax?

Enable this option to apply the discount before the calculation of the tax.

Discount type

Select whether to provide discount on the item level or entity level.

Is inclusive tax?

Enable this option to set the line item rates as tax inclusive.

Exchange Rate

Enter the currency exchange rate.

Salesperson name

Enter the name of the salesperson.

Line items

Add the desired line items to the invoice.

Payment Gateways

Add the supported payment gateways.

Get an Invoice

Retrieves the details of an invoice.

Required Permissions: ZohoBooks.invoices.READ

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to retrieve information about.

Download an Invoice

Downloads the invoice in PDF format.

Required Permissions: ZohoBooks.invoices.READ

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to download in PDF.	You can then map the downloaded file in the other modules, e.g. Dropbox > Upload a file to copy the file to your Dropbox folder.

List Invoices

Returns invoices based on the filter settings.

Required Permissions: ZohoBooks.invoices.READ,ZohoBooks.contacts.READ, ZohoBooks.settings.READ

Organization	Select your organization.
Search Criteria	Here you can define the search criteria for your search. For example, the following search returns all invoices whose customer name is "Tesla, Inc.".
Search Text	Returns only contacts that contain entered text in the contact name or in comments fields.
Sort Column	Select the parameter you want to filter results by.
Status	Select the status of the invoices you want to return.
Email	Enter the email to filter the searched invoices by.
Limit	Set the maximum number of invoices Ibexa Connect will return during one execution cycle.

Update an Invoice

Updates an existing invoice.

Required Permissions: ZohoBooks.invoices.READ, ZohoBooks.invoices.UPDATE, ZohoBooks.expenses.READ, ZohoBooks.projects.READ, ZohoBooks.settings.READ, ZohoBooks.contacts.READ

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to update.
Customer ID	Select or map the customer associated with the invoice.

Please find the descriptions of the fields in the Create an Invoice section above.

Delete an Invoice

Deletes an existing invoice.

Required Permissions: ZohoBooksinvoices.DELETE, ZohoBooks.invoices.READ*

Note

Invoices which have payment or credits note applied cannot be deleted.

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to delete.

Email an Invoice

Send an email with the invoice to the customer's contact person associated with the selected invoice.\

Required Permissions: ZohoBooksinvoices.CREAETE, ZohoBooks.invoices.READ*

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to send to the customer.
Attach Customer Statement PDF?	Sends the Customer Statement PDF with the email.
Mail Content	Select whether you want to send an email with default mail content, or you want to define custom mail content.

Remind Customer about an Unpaid Invoice

Reminds your customer about an unpaid invoice by email.

Required Permissions: ZohoBooksinvoices.CEAETE, ZohoBooks.invoices.READ*

Note

Reminder will be sent only for the invoices which have an open or overdue status.

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to send to the customer.
Attach Customer Statement PDF?	Sends the Customer Statement PDF with the email.
Mail Content	Select whether you want to send an email with default mail content, or you want to define custom mail content.

Void an Invoice

Set the invoice status as void.

Required Permissions: ZohoBooksinvoices.CEAETE, ZohoBooks.invoices.READ

Note

Upon voiding, the payments and credits associated with the invoices will be unassociated and will be under customer credits.

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to mark as void.

Mark an Invoice as Draft

Marks a void invoice as draft.

Required Permissions: ZohoBooksinvoices.CEAETE, ZohoBooks.invoices.READ

Note

Open invoices cannot be changed to draft.

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to mark as draft.

List Invoice Payments

Retrieves the list of payments made for an invoice.

Required Permissions: ZohoBooks.invoices.READ

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice you want to list payments for.
Limit	Set the maximum number of payments Ibexa Connect will return during one cycle.

Delete an Invoice Payment

Deletes a payment made to an invoice.

Required Permissions: ZohoBooksinvoices.DELETE, ZohoBooks.invoices.READ

Organization	Select your organization.
Invoice ID	Map or select the Invoice ID of the invoice that contains the invoice payment you want to delete.
Invoice Payment ID	Map or select the Invoice Payment ID of the invoice payment you want to delete. Warning: Do not confuse Invoice Payment ID with Payment ID!

Payments

Watch Payment

Triggers when a payment is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Create a Payment

Creates a new payment.

Required Permissions: ZohoBooks.customerpayments.CREATE, ZohoBooks.accountants.READ, ZohoBooks.contacts.READ, ZohoBooks.invoices.READ

Organization	Select your organization.
Customer ID	Map or select the Customer ID of the customer involved in the payment.
Contact Persons	Add the IDs of the contact persons that the thank you mail has to be sent.
Payment mode	Select the mode through which payment is made.
Amount	Enter the amount paid in the respective payment.
Invoices	Add invoices associated with the payment.
Payment date	Enter the date when payment is made. Format: yyyy-mm-dd.
Reference Number	Enter the reference number generated for the payment. A string of your choice can also be used as the reference number. Max 100 characters.
Payment Description	Enter the payment description.

Get a Payment

Retrieves details about the specified payment.

Required Permissions: ZohoBooks.customerpayments.READ

Organization	Select your organization.
Payment ID	Map or select the Payment ID of the payment you want to retrieve details about.

List Customer Payments

Returns all the payments made by your customer.

Required Permissions: ZohoBooks.customerpayments.READ

Organization	Select your organization.
Search Criteria	Here you can define the search criteria for your search. For example, the following search returns all payments made before the 1st of January 2020.
Limit	Set the maximum number of payments Ibexa Connect will return during one execution cycle.
Filter By	Select the mode you want to filter search results by.

Update a Payment

Updates information for an existing payment.

Required Permissions: ZohoBooks.customerpayments.UPDATE, ZohoBooks.contacts.READ, ZohoBooks.invoices.READ.customerpayments.READ

Organization	Select your organization.
Payment ID	Enter (map) the Payment ID of the payment you want to update.
Invoices	Add invoices associated with the payment.

Please find the descriptions of the fields in the Create a Payment section above.

Delete a Payment

Deletes an existing payment.

Required Permissions: ZohoBook.customerpayments.READ

Organization	Select your organization.
Payment ID	Enter (map) the Payment ID of the payment you want to delete.

Expenses

Watch Expense

Triggers when an expense is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Create an Expense

Creates a billable or non-billable expense.

Required Permissions: ZohoBooks.expenses.CREATE, ZohoBooks.accountants.READ, ZohoBooks.contacts.READ, ZohoBooks.settings.READ, ZohoBooks.projects.READ

Organization	Select your organization.
Account ID	Enter (map) or select the Account ID of the expense account.
Paid through account ID	Select the Paid Through account – the account from which money is paid.
Date	Enter the date of the expense in the YYYY-MM-DD format.
Amount	Enter the amount of the expense.
Tax ID	Enter or map the Tax ID you want to apply.
Line Items	Add the expense line items in the case where there are multiple items.
Is inclusive tax	Specify whether the line item rates are inclusive or exclusive of tax.
Is billable?	Select the Yes option to set the expense as billable.
Reference Number	Enter the reference number of the invoice.
Description	Enter the description of the expense.

Get an Expense

Retrieves an expense's details.

Required Permissions: ZohoBooks.expenses.READ

Organization	Select your organization.
Expense ID	Map or select the Expense ID of the expense you want to retrieve details about.

List Expenses

Lists all the expenses.

Required Permissions: ZohoBooks.expenses.READ

Organization	Select your organization.
Search Criteria	Enter the search criteria to filter the results.
Status	Select the status of returned expenses.
Limit	Set the maximum number of expenses Ibexa Connect will return during one execution cycle.

Update an Expense

Updates an existing expense.

Required Permissions: ZohoBooks.expenses.UPDATE, ZohoBooks.expenses.READ, "ZohoBooks.accountants.READ", ZohoBooks.contacts.READ,ohoBooks.settings.READ, "ZohoBooks.projects.READ"

Organization	Select your organization.
Expense ID	Select or map the Expense ID of the expense you want to update.
Account ID	Enter (map) or select the Account ID of the expense account.
Paid through account ID	Select the Paid Through account – the account from which money is paid.
Date	Enter the date of the expense in the YYYY-MM-DD format.
Amount	Enter the amount of the expense.

Please find the descriptions of the fields in the Create an Expense section above.

Delete an Expense

Deletes an existing expense.

Required Permissions: ZohoBooks.expenses.DELETE, ZohoBooks.expenses.READ

Organization	Select your organization.
Expense ID	Select or map the Expense ID of the expense you want to delete.

Create an Employee

Creates an employee for an expense.

Required Permissions: ZohoBooks.expenses.CREATE

Organization	Select your organization.
Name	Enter the name of the employee.
Email	Enter employee's email address.

Get an Employee

Retrieves employee details.

Required Permissions: ZohoBooks.expenses.READ

Organization	Select your organization.
Employee ID	Map or select the employee you want to get information about.

List Employees

Retrieves employees based on filter settings.

Required Permissions: ZohoBooks.expenses.READ

Organization	Select your organization.
Limit	Set the maximum number of employees Ibexa Connect will return during one cycle.
Sort Column
Filter By

List Employees

Deletes an existing employee.

Required Permissions: ZohoBooks.expenses.READ

Organization	Select your organization.
Employee ID	Map or select the employee you want to delete.

Bills

Watch Bill

Triggers when a bill is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

Create a Bill

The module creates a bill received from your vendor.

Required Permissions: ZohoBooks.bills.CREATE", ZohoBooks.purchaseorder.READ", ZohoBooks.settings.READ, ZohoBooks.projects.READ, ZohoBooks.contacts.READ, "ZohoBooks.accountants.READ

Organization	Select your organization.
Vendor ID	Select or map the vendor of the bill that has to be created.
Bill Number	Enter the bill number.
Is update customer?	Enable this option to update the customer.
Purchase Order IDs	Add the purchase orders.
Date	Enter the creation date of the bill in the yyyy-mm-dd format.
Due Date	Enter the due date of the bill in the yyyy-mm-dd format.
Payment Terms	Enter the net payment term.
Payment Terms Label	Enter the label for net payment term
Recurring Bill ID	Enter the ID of the recurring bill.
Line Items	Add line items of a bill.
Is Item Level Tax Calculation?	Enable if the Item Level Tax Calculation is present.
Is inclusive tax?	Enable to set line item rates as inclusive of tax.
Reference Number	Enter the Reference Number of the entity
Adjustment	Add the bill adjustments. The amount entered as adjustment is added to the invoice total.
Adjustment Description	Enter the adjustment description. E.g. Rounding off.

Get a Bill

Retrieves details of a specified bill.

Required Permissions: ZohoBooks.bills.READ

Organization	Select your organization.
Bill ID	Select or map the Bill ID of the bill that you want retrieve details about.

List Bills

Retrieves all bills based on the filter settings.

Required Permissions: ZohoBooks.bills.READ, ZohoBooks.contacts.READ, ZohoBooks.settings.READ, ZohoBooks.purchaseorders.READ

Organization	Select your organization.
Search Criteria	Enter the search criteria to filter the results by.
Status	Select the status of returned bills.
Limit	Set the maximum number of bills Ibexa Connect will return during one execution cycle.

Update a Bill

Updates an existing bill.

Required Permissions: ZohoBooks.bills.UPDATE, ZohoBooks.bills.READ, ZohoBooks.purchaseorders.READ, ZohoBooks.settings.READ, ZohoBooks.projects.READ, ZohoBooks.contacts.READ

Organization	Select your organization.
Bill ID	Enter (map) the Bill ID of the bill you want to update.
Vendor ID	Select or map the vendor of the bill that has to be updated.
Bill Number	Enter the bill number of the bill you want to update.

Please find the descriptions of the fields in the Create a Bill section above.

Delete a Bill

Deletes a specified bill.

Required Permissions: ZohoBooks.bills.DELETE, ZohoBooks.bills.READ

Organization	Select your organization.
Bill ID	Select or map the Bill ID of the bill you want to update.

Items

Watch Item

Triggers when an item is created, edited or deleted.

Please see the Setting Up Zoho Books Webhooks section.

List Items

Required Permissions: ZohoBooks.settings.READ

Organization	Select your organization.
Search Criteria	Enter the search criteria to filter the results by.
Limit	Set the maximum number of items Ibexa Connect will return during one execution cycle.
Tax ID	Enter the Tax ID to filter the results by.
Tax name	Search items by the tax name.
Is Taxable?	Filter items by taxability.
Tax Exemption ID	Enter the ID of the tax exemption.
Account ID	Enter the ID of the account to which the item is associated with.
Filter by	Select the status you want to filter returned items by.
Search Text	Filter items by name or description.
Sort Column	Select whether you want to sort result by name, rate, or tax name.

Make an API Call

Allows you to perform a custom API call.

URL

Enter a path relative to https://books.zoho.{region}/api (e.g. /v3/bills)

For the list of available endpoints, refer to the Zoho Books API Documentation.

Method

Select the HTTP method you want to use:

GET

to retrieve information for an entry.

POST

to create a new entry.

PUT

to update/replace an existing entry.

PATCH

to make a partial entry update.

DELETE

to delete an entry.

Headers

Enter the desired request headers. You don't have to add authorization headers; we already did that for you.

Query String

Enter the request query string.

Body

Enter the body content for your API call.

Example of Use - List Bills

The following API call returns a list of all your bills in your Zoho Books account:

Matches of the search can be found in the module's Output under *Bundle > Body > bills. *

In our example, 6 bills were returned:

Setting Up Zoho Books Webhooks

The process consists of two main steps:

1. Creating a Webhook

2. Creating a Workflow Rule

Step 1: Creating a Webhook

1. Go to Ibexa Connect and add a Zoho Books' instant trigger module to your scenario. E.g. Watch Invoice module.

2. Copy the provided URL.

   

3. Log in to your Zoho Books account.

4. Click the cog-wheel in the top-right corner to open Settings \> Automation

   

5. Open Webhooks and click the +New Webhook button.

   

6. Enter the name for the webhook, select the corresponding module (e.g. Sales > Invoice for Watch Invoice instant trigger) and enter the URL you have copied in step 2 above to the URL to the notify field and click the Save button.

   

Step 2: Creating a Workflow Rule

1. Go to Settings > Automation > Workflow Rules

2. Click the + New Workflow Rule button in the top-right corner.

   

3. Enter the Workflow Rule Name, select the module you want to watch (e.g. Invoice) and click the Next button.

   

4. Select an event that will trigger the webhook.

5. Add a trigger filter, if needed.

   

6. Select the Webhooks option from the Type drop-down menu and the webhook you have created (e.g. Invoice) in the Name drop-down menu.

   

7. Click the Save button to save your settings

Now, when a specified event is performed, the respective webhook is triggered in your scenario.

Please see the Zoho Books Automation help for further details about automation functions. lows you to perform a custom API call.

URL

Enter a path relative to https://books.zoho.{region}/api (e.g. /v3/bills)

For the list of available endpoints, refer to the Zoho Books API Documentation.

Method

Select the HTTP method you want to use:

GET

to retrieve information for an entry.

POST

to create a new entry.

PUT

to update/replace an existing entry.

PATCH

to make a partial entry update.

DELETE

to delete an entry.

Headers

Enter the desired request headers. You don't have to add authorization headers; we already did that for you.

Query String

Enter the request query string.

Body

Enter the body content for your API call.

Example of Use - List Bills

The following API call returns a list of all your bills in your Zoho Books account:

Matches of the search can be found in the module's Output under *Bundle > Body > bills. *

In our example, 6 bills were returned:

Setting Up Zoho Books Webhooks

The process consists of two main steps:

1. Creating a Webhook

2. Creating a Workflow Rule

Step 1: Creating a Webhook

1. Go to Ibexa Connect and add a Zoho Books' instant trigger module to your scenario. E.g. Watch Invoice module.

2. Copy the provided URL.

   

3. Log in to your Zoho Books account.

4. Click the cog-wheel in the top-right corner to open Settings \> Automation

   

5. Open Webhooks and click the +New Webhook button.

   

6. Enter the name for the webhook, select the corresponding module (e.g. Sales > Invoice for Watch Invoice instant trigger) and enter the URL you have copied in step 2 above to the URL to the notify field and click the Save button.

   

Step 2: Creating a Workflow Rule

1. Go to Settings > Automation > Workflow Rules

2. Click the + New Workflow Rule button in the top-right corner.

   

3. Enter the Workflow Rule Name, select the module you want to watch (e.g. Invoice) and click the Next button.

   

4. Select an event that will trigger the webhook.

5. Add a trigger filter, if needed.

   

6. Select the Webhooks option from the Type drop-down menu and the webhook you have created (e.g. Invoice) in the Name drop-down menu.

   

7. Click the Save button to save your settings

Now, when a specified event is performed, the respective webhook is triggered in your scenario.

Please see the Zoho Books Automation help for further details about automation functions.