Skip to content
Docs
Finance & accounting

Zoho Books

Let hires look up customers and invoices, see who owes what, draft and send invoices, record payments and keep notes in Zoho Books.

Explore 10 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Zoho Books, a hire can:

  • find customers and see what each one owes,
  • list invoices by status (draft, unpaid, overdue, paid, void), customer and date,
  • read an invoice with its lines, payments and history,
  • see who owes what and how late (current, 1–30, 31–60, 61–90 and over 90 days),
  • draft an invoice, send it by email, record a payment, and add a note to an invoice.

It works in every Zoho data centre, including the UAE (zoho.ae) and Saudi Arabia (zoho.sa).

1. Make an app in the Zoho API console

Roster connects as an app you own, so you choose what it can reach and can revoke it at any time.

  1. Open the Zoho API console for your data centre: the same ending as your Zoho Books address. For books.zoho.com it's api-console.zoho.com; for books.zoho.eu it's api-console.zoho.eu; for the UAE api-console.zoho.ae; and so on.
  2. Click Add Client and choose Server-based Applications.
  3. Client Name: Roster. Homepage URL: your Roster address.
  4. Authorized Redirect URIs: the address Roster shows on the Zoho Books connection. It ends in /api/integrations/zoho-books/oauth/callback.
  5. Click Create, then copy the Client ID and Client Secret.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Zoho Books and choose it.
  2. Paste the OAuth app client ID and OAuth app client secret.
  3. Data centre: where your Zoho account lives. Look at your Zoho Books address: books.zoho.eu is Europe, books.zoho.in is India, and so on.
  4. Organisation ID: leave it empty if you have one organisation. If you have more, open Zoho Books, click your organisation's name at the top, and copy the ID shown for the one hires should use.
  5. Click Connect, then Connect with Zoho Books on the new connection.
  6. Zoho asks you to allow Roster. Click Accept. Back in Roster, the connection says Connected with Zoho Books.

What hires do in Zoho Books shows as the Zoho user who accepted.

What Roster asks Zoho for

PermissionWhy
Contacts: readFind customers and what they owe
Settings: readFind your organisation
Invoices: read, create, editRead invoices; draft, send and comment (only hires allowed to)
Customer payments: read, createSee payments; record new ones (only hires allowed to)

3. Give hires access

On the hire's Tools tab, click Give access on Zoho Books:

  • Read only: it can look up customers, invoices and payments and see who owes what. It can't change anything, draft or send.
  • Read and write: it can also draft invoices, send them, record payments and add notes.

Drafting and sending are separate. A draft stays in Zoho Books until someone sends it, so you can let a hire prepare invoices and check them yourself before they go out.

A hire with Read and write can also ask to void an invoice. That always waits for a person's approval: the hire asks in the thread with the invoice and the reason, and when the approver says yes, Roster voids exactly that invoice, once (more). Nobody can turn that asking off.

Hires refer to invoices by their number, like INV-000012, and to customers by name.

Watching invoices

A hire's responsibility can watch Zoho Books: it's woken when invoices change (paid, sent, edited) or fall overdue, with the list. Checking costs nothing when nothing changed.

If something goes wrong

  • "Isn't connected yet": press Connect with Zoho Books on the connection.
  • Zoho says the redirect URI doesn't match: the address in the API console must be exactly the one Roster shows, with no extra slash.
  • "Several organisations": set the Organisation ID on the connection.
  • Zoho's daily limit: Zoho Books allows a set number of requests a day depending on your plan. When it's used up, the hire says so and tries again later.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Zoho Books and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

OAuth 2.0

From the Server-based Application you added in the Zoho API console.

Requested scopes:

  • ZohoBooks.contacts.READ
  • ZohoBooks.settings.READ
  • ZohoBooks.invoices.READ
  • ZohoBooks.invoices.CREATE
  • ZohoBooks.invoices.UPDATE
  • ZohoBooks.customerpayments.READ
  • ZohoBooks.customerpayments.CREATE

Connection fields

Zoho Books connection fields
FieldWhat to provide
OAuth app client ID
clientId
Optional		From the Server-based Application you added in the Zoho API console.
OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.
Data centre
region
Optional		Where your Zoho account lives: look at your Zoho Books address, e.g. books.zoho.eu is Europe.

Choices: United States (zoho.com) (com); Europe (zoho.eu) (eu); India (zoho.in) (in); Australia (zoho.com.au) (com.au); Japan (zoho.jp) (jp); Canada (zohocloud.ca) (ca); Saudi Arabia (zoho.sa) (sa); United Arab Emirates (zoho.ae) (ae).

Starts with: com.

Organisation ID
organization
Optional		Only if you have more than one organisation: in Zoho Books, click your organisation's name to see its ID. Empty: your default organisation.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

No additional fields.

Actions

10 actions: 5 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

10 of 10 actions. Open an action for its arguments and full input schema.

list_contactsRead only

Customers in Zoho Books with what each owes, optionally matching words in their name, company or email, or only those with overdue or unpaid invoices.

Approval: Uses your workspace and hire approval settings.

Arguments for list_contacts
ArgumentTypeDetails
searchOptionalstringwords in the name, company or email
owingOptional"any" | "unpaid" | "overdue"See input schema below.Default: "any"
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "description": "words in the name, company or email",
      "type": "string"
    },
    "owing": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "unpaid",
        "overdue"
      ]
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
list_invoicesRead only

Invoices, newest first, filtered by status (draft, unpaid, overdue, paid, void), customer, invoice date and words in the number or reference.

Approval: Uses your workspace and hire approval settings.

Arguments for list_invoices
ArgumentTypeDetails
statusOptional"any" | "draft" | "unpaid" | "overdue" | "paid" | "void"unpaid: sent and not fully paid; overdue: unpaid and past its due dateDefault: "any"
customerOptionalstringa customer's name or id
fromOptionalstringinvoice date on or after, yyyy-mm-dd
toOptionalstringinvoice date on or before, yyyy-mm-dd
searchOptionalstringwords in the invoice number or reference
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "any",
      "description": "unpaid: sent and not fully paid; overdue: unpaid and past its due date",
      "type": "string",
      "enum": [
        "any",
        "draft",
        "unpaid",
        "overdue",
        "paid",
        "void"
      ]
    },
    "customer": {
      "description": "a customer's name or id",
      "type": "string"
    },
    "from": {
      "description": "invoice date on or after, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "invoice date on or before, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "search": {
      "description": "words in the invoice number or reference",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
get_invoiceRead only

One invoice in full: customer, dates, line items, totals, payments received and its latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-000012, or its id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. INV-000012, or its id"
    }
  },
  "required": [
    "invoice"
  ]
}
create_draft_invoiceRead and write

Create a draft invoice for a customer. Nothing is sent: the customer sees it only once someone sends it.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft_invoice
ArgumentTypeDetails
customerRequiredstringthe customer's name or id
linesRequiredobject[]See input schema below.
dateOptionalstringinvoice date, yyyy-mm-dd; default today
due_dateOptionalstringdefault: the customer's payment terms
referenceOptionalstringa PO or order number
notesOptionalstringnotes shown on the invoice
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "type": "string",
      "minLength": 1,
      "description": "the customer's name or id"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          },
          "item": {
            "description": "a product or service id or code from the accounting system",
            "type": "string"
          },
          "account": {
            "description": "an income account code, where the system needs one",
            "type": "string"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      }
    },
    "date": {
      "description": "invoice date, yyyy-mm-dd; default today",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "due_date": {
      "description": "default: the customer's payment terms",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "description": "a PO or order number",
      "type": "string",
      "maxLength": 100
    },
    "notes": {
      "description": "notes shown on the invoice",
      "type": "string",
      "maxLength": 5000
    }
  },
  "required": [
    "customer",
    "lines"
  ]
}
send_invoiceRead and write

Email an invoice to the customer from Zoho Books (a draft is marked sent). Goes to the customer's contacts unless addresses are given.

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-000012, or its id
toOptionalstring[]email addresses; default: the customer's contacts
subjectOptionalstringdefault: the organisation's invoice email template
messageOptionalstringthe email's text; default: the template's
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. INV-000012, or its id"
    },
    "to": {
      "description": "email addresses; default: the customer's contacts",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "subject": {
      "description": "default: the organisation's invoice email template",
      "type": "string",
      "maxLength": 300
    },
    "message": {
      "description": "the email's text; default: the template's",
      "type": "string",
      "maxLength": 10000
    }
  },
  "required": [
    "invoice"
  ]
}
record_paymentRead and write

Record a payment the customer made against an invoice.

Approval: Uses your workspace and hire approval settings.

Arguments for record_payment
ArgumentTypeDetails
invoiceRequiredstringthe invoice number or id
amountRequirednumberSee input schema below.
dateOptionalstringwhen it was paid; default today
referenceOptionalstringthe bank or cheque reference
modeOptionalstringhow it was paid: banktransfer, cash, check, creditcard…Default: "banktransfer"
accountOptionalstringthe id of the bank or cash account it went into; default Zoho's
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number or id"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "date": {
      "description": "when it was paid; default today",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "description": "the bank or cheque reference",
      "type": "string",
      "maxLength": 100
    },
    "mode": {
      "default": "banktransfer",
      "description": "how it was paid: banktransfer, cash, check, creditcard…",
      "type": "string",
      "maxLength": 50
    },
    "account": {
      "description": "the id of the bank or cash account it went into; default Zoho's",
      "type": "string"
    }
  },
  "required": [
    "invoice",
    "amount"
  ]
}
list_paymentsRead only

Payments received, newest first, optionally from one customer.

Approval: Uses your workspace and hire approval settings.

Arguments for list_payments
ArgumentTypeDetails
customerOptionalstringa customer's name or id
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "description": "a customer's name or id",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
receivables_summaryRead only

Who owes what and how late: open invoices totalled by age (current, 1-30, 31-60, 61-90, over 90 days) and the customers most overdue.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
add_noteRead and write

Add a comment to an invoice's history in Zoho Books, e.g. what the customer said when chased. Not shown to the customer unless asked.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-000012, or its id
noteRequiredstringSee input schema below.
show_to_customerOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. INV-000012, or its id"
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "show_to_customer": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "invoice",
    "note"
  ]
}
void_invoiceRead and writeApproval required · locked

Void an invoice in Zoho Books: it stays on record but is no longer owed. It always waits for a person's approval: Roster asks in the thread and voids exactly this invoice, once, when they approve.

Approval: Always asks for approval. This requirement cannot be turned off.

Arguments for void_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-000012, or its id
reasonRequiredstringwhy, kept as a note on the invoice
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. INV-000012, or its id"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "why, kept as a note on the invoice"
    }
  },
  "required": [
    "invoice",
    "reason"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Xero

Let hires look up customers and invoices, see who owes what, draft and send invoices, record payments and keep notes in Xero.

Zoho Invoice

Let hires look up customers and invoices, see who owes what, draft and send invoices, record payments and keep notes in Zoho Invoice.

On this page

1. Make an app in the Zoho API console2. Connect it in RosterWhat Roster asks Zoho for3. Give hires accessIf something goes wrongTools and permissions reference