n8n-nodes-zoho-books-community

Custom n8n community node for Zoho Books with OAuth2 support.

Features

• OAuth2 credential with selectable Zoho data center (.com, .eu, .in, .com.au, .jp, .ca, .com.cn, .sa) and sandbox toggle.
• Organizations: list/get.
• Contacts: list/get/create/update/delete (with custom fields helper, extra body fields, and a mapped-field dropdown; email/phone in mapped/extra fields auto-create a primary contact person).
• Invoices: list/get/create/update/delete (with custom fields helper and extra body fields).
• Payments (customer payments): list/get/create/delete (with custom fields helper and extra body fields).
• Custom fields helper maps label/name + value into custom_fields payload. Extra body fields lets you inject arbitrary API fields without editing raw JSON.
• Generic "API Request" operation to hit any /books/v3 endpoint with JSON query/body helpers and optional organization_id injection.
• Comprehensive API filters for List operations (see below).

Available Filters

Contact Filters (List Operation)

| Filter | Description | |--------|-------------| | Contact Name | Filter by contact name (exact match) | | Contact Name Contains | Search contacts whose name contains text | | Contact Name Starts With | Search contacts whose name starts with text | | Company Name | Filter by company name | | Email | Filter by email address | | Email Contains | Search contacts whose email contains text | | Phone | Filter by phone number | | Contact Type | Filter by type (customer/vendor) | | Status | Filter by status (active/inactive/duplicate/crm) | | Filter By | Predefined filter options (Status.All, Status.Active, etc.) | | Search Text | Search across name, email, phone, or company | | Address / City / State / Country / Zip | Location filters | | Sort Column | Sort by contact_name, company_name, email, created_time, etc. | | Sort Order | Ascending (A) or Descending (D) | | Page / Per Page | Pagination controls |

Invoice Filters (List Operation)

| Filter | Description | |--------|-------------| | Invoice Number | Filter by invoice number (exact match) | | Invoice Number Contains | Search invoices where number contains text | | Invoice Number Starts With | Search invoices where number starts with text | | Reference Number | Filter by reference number (exact match) | | Reference Number Contains | Search by reference number containing text | | Reference Number Starts With | Search by reference number starting with text | | Customer ID | Filter by customer ID | | Customer Name | Filter by customer name | | Customer Name Contains | Search by customer name containing text | | Email | Filter by customer email | | Status | Filter by status (draft/sent/overdue/unpaid/partially_paid/paid/void) | | Filter By | Predefined filters (Status.Sent, Date.ThisMonth, etc.) | | Invoice Date / Date Start / Date End | Date filters (YYYY-MM-DD format) | | Due Date / Due Date Start / Due Date End | Due date filters | | Total (exact/less than/greater than) | Amount filters | | Balance (exact/less than/greater than) | Balance due filters | | Item Name / Item Description | Filter by line item details | | Search Text | Search across all invoice fields | | Item ID | Filter invoices containing specific item | | Recurring Invoice ID | Filter by recurring invoice | | Sort Column | Sort by customer_name, invoice_number, date, total, etc. | | Sort Order | Ascending (A) or Descending (D) | | Page / Per Page | Pagination controls |

Payment Filters (List Operation)

| Filter | Description | |--------|-------------| | Customer ID | Filter by customer ID | | Customer Name | Filter by customer name | | Reference Number | Filter by reference number | | Payment Number | Filter by payment number | | Payment Mode | Filter by payment mode (Cash, Check, etc.) | | Date / Date Start / Date End | Date filters | | Amount (exact/less than/greater than) | Amount filters | | Search Text | Search across payment fields | | Filter By | Predefined filters (PaymentMode.Cash, etc.) | | Sort Column | Sort by customer_name, payment_number, date, amount | | Sort Order | Ascending (A) or Descending (D) | | Page / Per Page | Pagination controls |

Setup

1. Create a Zoho OAuth client (server-based) in the right data center. Use scope ZohoBooks.fullaccess.all.
   Reference: Zoho Books API – Organization ID & OAuth.
2. In n8n, add credentials using Zoho Books OAuth2 API:
   • Set Client ID/Secret from Zoho.
   • Choose the data center and environment (production/sandbox).
   • Complete the OAuth flow.
3. Install this package in your n8n instance (e.g. npm i n8n-nodes-zoho-books-community in the n8n user folder or use the UI custom nodes installer).

Usage

• Organization → List/Get: quickly fetch available organizations.
• Contacts/Invoices/Payments: dedicated CRUD-style ops with org id + comprehensive filters.
• API Request (Generic):
  • Set the HTTP method and endpoint (e.g. /invoices).
  • Provide query/body as JSON strings. Optional organization_id field can be set directly on the node.

Example: Find Invoice by Reference Number

1. Select Resource: Invoice
2. Select Operation: List
3. Add Filter: Reference Number = YOUR_REF_NUMBER
4. Execute — returns only invoices matching that reference number

Build

npm install
npm run build

The compiled files will be placed in dist/ as required by n8n.

Changelog

v0.6.0

• Added comprehensive filter options for Contacts, Invoices, and Payments
• Invoice filters: invoice_number, reference_number, customer_id, customer_name, email, status, date ranges, total/balance filters, item_name, item_description, search_text, sorting
• Contact filters: contact_name, company_name, email, phone, contact_type, status, address fields, sorting
• Payment filters: customer_id, customer_name, reference_number, payment_number, payment_mode, date ranges, amount filters, sorting

v0.5.1

• Initial release with CRUD operations for Organizations, Contacts, Invoices, and Payments

Notes

• organization_id is required by most Zoho Books endpoints; provide it either via the dedicated field or inside the query JSON.
• Respect Zoho Books rate limits (per plan and per minute) to avoid HTTP 429 responses.
• Filter values of 0 for numeric fields and empty strings are ignored (not sent to API).