
Zoho Books for Docusign IAM
Get started Section 1 of 8
Quick Start
1. Install the App
- Open the Docusign App Center and search for Zoho Books.
- Open the Zoho Books app card, click Install App, then Install and Authorize on the consent screen.
2. Create a Connection
- On the installed app page, click Connect Account.
- Choose the connection visibility (Private or Shared), give the connection a name, and click Log In.
- Sign in to Zoho, tick the box on the Zoho consent screen and click Accept. If your Zoho account has more than one Zoho Books organization, choose the one this connection works with.
3. Create a Workflow
- In Docusign, open Automations → Workflows and click Create Workflow.
- Choose your preferred workflow start type.
- Add a Zoho Books step: Read, Writeback, or File Upload.
4. Available Actions
- Read from Zoho Books: pull a Customer, Vendor, Quote, Sales Order, Invoice or Purchase Order into your workflow to pre-fill an agreement.
- Writeback to Zoho Books: create or update a customer or vendor, or set the status of a quote, sales order or purchase order.
- File Upload to Zoho Books: attach the signed document to the record it belongs to.
5. Key Things to Know
- Every later step addresses a record by its Record ID (the long number in the Zoho Books address bar), not by its number (
QT-000002) or name. The Read and Writeback steps return the Record ID. - Transactions are read with their totals, not their line items. Quotes, sales orders and purchase orders take one write, Status; invoices are read-only.
- When a step fails, Docusign shows "Something went wrong". The usual causes are listed under FAQ & Troubleshooting.
Reference Section 7 of 8
Implementation Guide & Known Behaviors
The app works with six objects:
| Object | What the app can do | Fields |
|---|---|---|
| Customer | Read, search, create, update, attach files | 39 |
| Vendor | Read, search, create, update, attach files | 37 |
| Quote | Read, search, set Status, attach files | 21 |
| Sales Order | Read, search, set Status, attach files | 21 |
| Invoice | Read, search, attach files | 24 |
| Purchase Order | Read, search, set Status, attach files | 19 |
Field labels are the words Zoho Books' own forms use. A label ending in (Searchable) marks a field a Read step can filter by; Record ID can always be used. After an app update that changes labels or fields, run Reload Objects under Manage Connections so the steps show the new list.
Building Workflows
- Read a record with a Read from Zoho Books step, then use the Record ID it returns in every later step: the Writeback rule and the File Upload record.
- A typical quote flow reads the Quote by its Quote Number, sends the agreement, attaches the signed PDF to the quote and writes Status = Accepted.
- Customer and Vendor are separate objects. A Customer step never reads, updates or attaches to a vendor, and the reverse.
- Customer ID and Vendor ID on a transaction are the Record ID of that customer or vendor. Use them in a second Read step to fetch the customer's address and contact details.
- A Read step that finds no record does not stop the workflow. Its variables are empty.
- Update or Create keyed on Display Name is safe. Zoho Books refuses a second customer with the same display name, so a repeated run updates the customer. Zoho allows several customers with one email address: a rule on Email Address stops the step when two customers share it.
- Sales Orders and Purchase Orders are switched off in a new Zoho Books organization (Settings › Preferences › General). Until they are on, those objects return nothing.
Writeback Behaviors
Customers and vendors
| Topic | Behavior |
|---|---|
| Required field | Display Name. Zoho Books refuses a display name that already exists unless "Allow duplicates for customer and vendor display name" is switched on; nothing is created. |
| Update | Changes only the fields you map. Address parts you do not map keep their values. Changing Display Name renames the record in place (same Record ID). |
| Primary contact | Email Address, Work Phone, Mobile, Salutation, First Name and Last Name belong to the primary contact person. Any of them can be written alone. The other contact persons are never changed. |
| Empty values | Ignored. A field cannot be cleared from a workflow. |
| Retries | Docusign's retries are de-duplicated: a customer is never created twice by one run. |
Quotes, sales orders and purchase orders
| Object | Status words the step accepts |
|---|---|
| Quote | Sent, Accepted, Declined |
| Sales Order | Confirmed |
| Purchase Order | Issued |
- Any other word (Void, Cancelled, Invoiced) fails the step. Void a sales order or cancel a purchase order in Zoho Books.
- A draft quote can be written Accepted or Declined directly. Zoho allows both only on a sent quote, so the app marks the draft Sent first and then sets your status. No email is sent to the customer, and the quote's history shows both steps.
- A record already in the written status is left as it is and the step succeeds, so a workflow can run again safely.
- Quotes, sales orders, invoices and purchase orders cannot be created: Zoho Books needs line items to create them. Invoices are read-only.
Field values
| Field | What to know |
|---|---|
| Currency | A three-letter code enabled in your organization (USD, EUR). |
| Credit Limit | An amount: $5,000 and 5000.50 work; 77,50 is refused as ambiguous. Empty until "Customer Credit Limit" is enabled in Zoho Books. |
| Payment Terms (Days) | A whole number; 0 means Due on Receipt. The app writes the label Zoho shows with it: your organization's own term with that number of days, else "Net 45" for 45 days. A day count that matches none of your terms adds a term to your Payment Terms list in Zoho Books. |
| Customer Type | Business or Individual, in any letter case. |
| Phones | Stored as written. Zoho's own form adds the country code it has selected. |
Searching for a Record
Searchable fields
| Object | Searchable fields |
|---|---|
| Customer, Vendor | Display Name, Company Name, Primary Contact First Name, Primary Contact Last Name, Email Address, Work Phone, Status |
| Quote | Quote Number, Reference Number, Status, Quote Date, Expiry Date, Customer ID, Customer Name |
| Sales Order | Sales Order Number, Reference Number, Status, Sales Order Date, Expected Shipment Date, Customer ID, Customer Name |
| Invoice | Invoice Number, Order Number, Status, Invoice Date, Due Date, Customer ID, Customer Name |
| Purchase Order | Purchase Order Number, Reference Number, Status, Purchase Order Date, Vendor ID, Vendor Name |
Record ID is searchable on every object. Any other field in the rule stops the step. In the rule builder that refusal shows as "Unable to load data", so check the field is in this list first.
Matching
- Text conditions match the whole value, ignoring letter case and extra spaces.
- Conditions combine with AND. OR is not supported: use separate Read steps.
- Record ID overrides every other condition in the rule. A Record ID that does not exist, or belongs to another object, returns nothing.
- Status takes the words Zoho Books shows, in any letter case. Any other word is refused.
- Sales Order Status takes Draft, Confirmed or Void in a rule. A confirmed sales order stays Confirmed after its Expected Shipment Date; to find orders past their shipment date, filter on Expected Shipment Date.
- Invoice Status "Unpaid" finds every invoice still to be paid (sent, viewed, overdue, partially paid); the invoice itself reads its own status.
- Email Address matches the primary contact person only, as Zoho's own email filter does.
- Work Phone must be written as Zoho stores it, with the country code:
+1-302 555 0101. - A rule that matches more than 1,000 similar records, or cannot be checked in time, is refused asking for a narrower rule. It never returns a partial list.
⚠️ With A single record and several matches, the step returns the first record by Display Name. Search by a number (Quote Number, Invoice Number) or the Record ID when one exact record matters.
Reading Record Data
| Type | Reads as |
|---|---|
| Dates (Quote Date, Due Date, …) | The calendar day as UTC midnight: 2026-03-28T00:00:00.000Z |
| Created Time, Last Modified Time | The instant, in UTC |
| Status | The words Zoho Books shows: Draft, Sent, Accepted, Declined, Invoiced, Expired (quotes); Draft, Confirmed, Closed, Void, On Hold (sales orders); Draft, Sent, Viewed, Overdue, Paid, Partially Paid, Unpaid, Void (invoices); Draft, Issued, Billed, Cancelled (purchase orders); Active, Inactive (customers, vendors) |
| Payment Terms | As Zoho shows it (Net 15); Payment Terms (Days) is the number behind it |
| Totals | Sub Total − Discount + Shipping Charges + Tax Total + Adjustment = Total. A purchase order has no Shipping Charges |
| Receivables, Payables, Unused Credits, Balance Due, Amount Paid | Computed by Zoho Books, read-only |
- Empty text and date fields read as empty; an amount that is not set reads 0. Credit Limit reads 0 for a customer Zoho shows as "Unlimited".
- A void invoice keeps its Balance Due. A workflow condition on Balance Due should also check Status.
- On an Invoice, Order Number is the field Zoho's invoice form calls "Order Number". Quotes, sales orders and purchase orders call the same field Reference Number.
- A rule that matches many records returns full details for the first 10. Further records carry the fields of Zoho's list view; addresses, notes and terms need a narrower rule or the Record ID.
- Line items, custom fields, tax registration fields (GST, VAT, TDS) and contact persons other than the primary are not available in this version.
Get started Section 2 of 8
Installation and Configuration
Prerequisites
- A Zoho Books organization in any Zoho data center, and a Zoho user whose role can open the modules your workflows use. The connected user's role decides what the app can read and write.
- A Docusign account with admin rights to install and manage apps in the App Center.
How to Install the App
-
Open the Docusign App Center and search for Zoho Books in the search bar.
-
Click the Zoho Books app card to open its detail page, then click Install App.
-
Review the access the app requests and click Install and Authorize.
The app now appears with an Installed status.
Connecting Your Account
-
On the installed app page, click Connect Account.
-
Connection Visibility: choose how the connection is shared:
- Private: accessible only by you in Docusign.
- Shared: accessible by multiple users or the whole team.
-
Name Connection: enter a name. It appears in workflow steps, so make it easy to identify. Click Log In.
-
Sign in to Zoho if you are not signed in already. Every sign-in starts at accounts.zoho.com; Zoho moves you to your own data center (for example accounts.zoho.eu) by itself.
-
Zoho shows the consent screen of Docusign Workflows For Books. It lists the access the app requests: customers and vendors, estimates (quotes), sales orders, invoices, purchase orders and bills (read and write), and settings (read). Tick I allow Docusign Workflows For Books to access the above data from my Zoho account, then click Accept.
-
If your Zoho account has more than one Zoho Books organization, choose the one this connection works with. A connection reads and writes that organization only; add another connection for another organization.
The connection is added and ready to use in workflow steps. The step cards appear in the workflow builder once a connection exists.
The Zoho consent screen appears every time you create a connection. A connection attempt stays open for 10 minutes; after that, start again from Docusign.
Managing Connections
On the Zoho Books app page, open the Manage dropdown.
Select Manage Connections to see every connection.
Use the three-dot (⋮) menu next to a connection:
- Edit connection name: rename the connection.
- Reconnect: refresh the connection.
- Reload Objects: refresh the available objects and fields. Run this once after an app update that changes its fields.
- Delete Connection: remove the connection. ⚠️ Steps built on a deleted connection can no longer be edited and have to be added again.
Adding a New Connection
Use Manage → New Connection on the app page, or + New Connection on the Connections page. Each connection appears separately in workflow steps, and each works with one Zoho Books organization.
Revoking Access from Zoho
In your Zoho account settings (accounts.zoho.com), open Sessions → Connected Apps and remove the Docusign connector. That stops every Docusign connection created by that Zoho user. Zoho keeps up to 20 connections per user and app; creating more retires the oldest one.
Use the app Section 3 of 8
How to Use the App
Create a Workflow
-
Log in to Docusign and go to Automations → Workflows.
-
Click Create Workflow.
-
Build your workflow using the available steps, including the Zoho Books actions.
-
Publish the workflow when it is ready.
Available Zoho Books Actions
Click + Add Step and search for Zoho Books:
- Read from Zoho Books: fetch a record and expose its fields as workflow variables. See Read from Zoho Books.
- Writeback to Zoho Books: create or update a customer or vendor, or set a transaction's status. See Writeback to Zoho Books.
- File Upload to Zoho Books: attach a document from the workflow to a record. See File Upload to Zoho Books.
A typical quote flow:
- Read from Zoho Books: find the quote, for its number, customer and totals.
- Prepare eSignature Template: pre-fill the quote acceptance or the order form.
- Send Documents for Signature.
- File Upload to Zoho Books: attach the signed document to the quote.
- Writeback to Zoho Books: set the quote's Status to Accepted.
Use the app Section 4 of 8
Read from Zoho Books
The Read from Zoho Books step retrieves a record and exposes its fields as workflow variables.
Start the Workflow
The example below starts the workflow From an API Call with one Text variable, quote_number, that carries the quote's number. Any start type works: with a web form, use the form's field wherever this example uses quote_number.
1. Add the Read Step
On the workflow canvas, click + Add a step below the start.
Search for Zoho Books and select Read from Zoho Books.
2. Configure Connection and Object
-
Connection: select the connection you created during installation.
-
Zoho Books object: Customer, Vendor, Quote, Sales Order, Invoice or Purchase Order. This example uses Quote.
Click Next.
3. Select Fields
Click Add or Remove Fields and tick the fields your workflow needs. The selected fields become workflow variables for later steps.
Available fields:
Customer: Record ID, Display Name, Company Name, Customer Type, Primary Contact Salutation, Primary Contact First Name, Primary Contact Last Name, Email Address, Work Phone, Mobile, Website, Currency, Payment Terms, Payment Terms (Days), Credit Limit, Receivables, Unused Credits, Remarks, Status, Billing and Shipping address (Attention, Street 1, Street 2, City, State, ZIP Code, Country, Phone, Fax each), Created Time, Last Modified Time.
Vendor: the Customer fields without Customer Type and Credit Limit, with Payables in place of Receivables.
Quote: Record ID, Quote Number, Reference Number, Subject, Status, Quote Date, Expiry Date, Customer ID, Customer Name, Currency, Sub Total, Discount, Shipping Charges, Tax Total, Adjustment, Total, Salesperson, Customer Notes, Terms & Conditions, Created Time, Last Modified Time.
Sales Order: Record ID, Sales Order Number, Reference Number, Status, Sales Order Date, Expected Shipment Date, Customer ID, Customer Name, Currency, Sub Total, Discount, Shipping Charges, Tax Total, Adjustment, Total, Payment Terms, Salesperson, Customer Notes, Terms & Conditions, Created Time, Last Modified Time.
Invoice: Record ID, Invoice Number, Order Number, Subject, Status, Invoice Date, Due Date, Customer ID, Customer Name, Currency, Sub Total, Discount, Shipping Charges, Tax Total, Adjustment, Total, Amount Paid, Balance Due, Payment Terms, Salesperson, Customer Notes, Terms & Conditions, Created Time, Last Modified Time.
Purchase Order: Record ID, Purchase Order Number, Reference Number, Status, Purchase Order Date, Delivery Date, Vendor ID, Vendor Name, Currency, Sub Total, Discount, Tax Total, Adjustment, Total, Payment Terms, Notes, Terms & Conditions, Created Time, Last Modified Time.
Click Next.
4. Identify the Record
Create a rule that tells the step which record to read. In this example, match the quote's Quote Number to the quote_number start variable:
- Zoho Books field: Quote Number (Searchable)
- Operator: Equal to
- Workflow field:
quote_number
Under How many records should this step return?, pick one:
- A single record: the first record that matches.
- Multiple records: up to five records that match.
Click Done to confirm the rule. Use preview this step to check it against live data: enter a quote number and click Preview Zoho Books Data. Then click Apply.
The rule builder lists every field of the object; only the fields marked (Searchable) and Record ID work in a rule. See Searching for a Record.
Use the app Section 5 of 8
Writeback to Zoho Books
The Writeback to Zoho Books step creates or updates a customer or vendor, or sets the status of a quote, sales order or purchase order.
1. Add the Writeback Step
On the workflow canvas, click + Add a step where the writeback belongs, then search for Zoho Books and select Writeback to Zoho Books.
2. Configure Connection, Object, and Write Setting
-
Connection: select your Zoho Books connection.
-
Zoho Books object: Customer, Vendor, Quote, Sales Order or Purchase Order. Invoice is read-only and is not offered.
-
Write settings:
- Update or Create: updates the matching record, or creates one if the rule finds nothing. Customer and Vendor only; Display Name is required.
- Update: updates an existing record only. Nothing is required. Quote, Sales Order and Purchase Order offer this setting alone.
- Create: always creates a record. Customer and Vendor only; Display Name is required.
Click Next.
3. Map Fields
Click Add or Remove Fields and tick the fields you want to write.
Each selected field gets its own row. Map it to the workflow variable that supplies the value, or type a value.
Writable Customer fields: Display Name*, Company Name, Customer Type, Primary Contact Salutation, Primary Contact First Name, Primary Contact Last Name, Email Address, Work Phone, Mobile, Website, Currency, Payment Terms (Days), Credit Limit, Remarks, and the Billing and Shipping address fields.
Writable Vendor fields: the same without Customer Type and Credit Limit.
Quote, Sales Order, Purchase Order: Status.
* Required in Create and Update or Create. An Update step writes only the fields you tick.
⚠️ Map from the right source. The variable picker also lists the output of your Read from Zoho Books step. Mapping from there writes the original values back unchanged. Map new values from the step that collected them, such as a start variable, a web form or the signed document's fields.
Click Next.
4. Identify the Record
Match the record by its Record ID. In this example the Read step returned a quote, and the quote's Customer ID is the Record ID of its customer:
- Zoho Books field: Record ID
- Operator: Equal to
- Workflow field: Quote / Customer ID of the Read from Zoho Books step
Click Done, then Apply. A customer or vendor can also be matched by Display Name.
Marking a Quote Accepted
To close the loop on a signed quote, add a Writeback step on Quote (its one write setting is Update), tick Status, type Accepted, and match the quote by Quote / Record ID of the Read step.
After the run, the quote shows Accepted in Zoho Books.
Use the app Section 6 of 8
File Upload to Zoho Books
The File Upload to Zoho Books step attaches a document produced earlier in the workflow to a customer, vendor, quote, sales order, invoice or purchase order. Zoho Books accepts attachments up to 10 MB.
1. Add the File Upload Step
Add a step after signing completes, search for Zoho Books, and select File Upload to Zoho Books.
2. Select the File
Choose the file or envelope from an earlier step, for example the Combined Envelope File from Send Documents for Signature.
An empty list means no earlier step in the workflow produced a file. When a workflow stores an envelope's documents individually, each document is attached.
3. Choose the Record
-
Select connection: your Zoho Books connection.
-
Select record: open the list, choose the step that returns the record, and pick its Record ID.
-
Object fills itself with the object of that step, here Quote. Click Next.
Map the Record ID and nothing else. A name, a number such as QT-000002 or an email address names no record, and the step fails without uploading. There is no folder to build.
4. Name the File
Build the file name from Add Variable and Add Text, here the quote number followed by " - Signed order form". Docusign adds the file extension. A date or time variable keeps repeat runs apart.
Click Apply.
5. Verification
After the workflow runs, the document appears in the record's attachments in Zoho Books, uploaded by the connected user. The record's status does not change.
- Filing the same file name on the same record again adds a second copy under the same name. Zoho neither overwrites nor renames.
- Zoho limits the attachments per record (5 on a transaction) and the file types: invoices accept PDF and images; purchase orders also accept DOC, DOCX, XLS and XLSX.
Reference Section 8 of 8
FAQ & Troubleshooting
A step failed and Docusign only says "Something went wrong".
Docusign does not show the app's message. The usual causes: a Status word the step does not accept, a Display Name another customer already has, a Currency code your organization has not enabled, a Credit Limit written like
77,50, a file step whose record is not a Record ID, a rule on a field that is not searchable, or a module the connected Zoho user's role cannot open.
The rule builder or the preview shows "Unable to load data … Please contact our support team".
The rule names a field that is not searchable, or a Status word the object does not have. A Sales Order rule takes Draft, Confirmed or Void; Overdue, Invoiced and Partially Invoiced are refused. Change the rule and preview again.
The Zoho consent screen appears every time I create a connection.
That is how Zoho authorizes the app. Earlier connections stay Active under Manage Connections.
The page says "This connection attempt has expired".
A connection attempt stays open for 10 minutes, or the attempt was already completed. Start again from Docusign.
A field I expect is missing from the step, or a field was removed by an update.
Open Manage Connections and click Reload Objects on the connection, then reopen the step. A field an update removed disappears from the picker; a step that had it selected keeps its saved fields until you edit it.
The step picker lists only File Upload to Zoho Books.
Reload Objects does not bring the Read and Writeback steps back. Delete the connection, uninstall and install the app again, and create a new connection.
"You cannot edit this step because it uses another user's credentials".
The step was built on a connection that was deleted. Add the Zoho Books step again with the current connection.
Sales Orders or Purchase Orders return nothing.
The module is switched off in Zoho Books. Enable it under Settings › Preferences › General.
A confirmed sales order is past its shipment date. Which status does it read?
Confirmed, as every Zoho Books screen shows it. Zoho also lists the order in its Overdue view; to find those orders, filter on Expected Shipment Date.
The customer was not created: the name already exists.
Zoho Books refuses a duplicate display name. Use Update or Create keyed on Display Name, or enable duplicate display names in Zoho Books.
"Found multiple records for the given search query".
Two customers share the email address in the rule. Key the step on Display Name or Record ID.
My Work Phone search finds nothing.
Zoho stores the phone with the country code chosen in its form. Search with the stored form, for example
+1-302 555 0101.
Can I void a sales order, cancel a purchase order or create an invoice?
Not from a workflow. The step sets Sent, Accepted or Declined on a quote, Confirmed on a sales order and Issued on a purchase order. Do the rest in Zoho Books.
How do I clear a field?
Not from a workflow: empty values are ignored. Clear it in Zoho Books.
The file picker says no files are available.
No earlier step produced a file. Add the upload after Send Documents for Signature.
The file did not appear on the record.
The record has to be the Record ID variable of a step that runs before the upload, and the object has to match that record: a vendor's Record ID on Customer is refused. Zoho also refuses a file over 10 MB, a sixth attachment on a transaction and a file type the module does not accept.
The step failed with a daily limit message.
Zoho Books limits API calls per organization and day (1,000 to 10,000 by plan). Steps succeed again when the limit resets.
The connection asks me to reconnect.
Zoho retired or revoked the authorization: Zoho keeps 20 connections per user and app. Click Reconnect under Manage Connections.