@arathron/n8n-nodes-zoho-books

n8n-nodes-zoho-books

This is an n8n community node package that provides nodes for Zoho Books and Zoho Inventory in your n8n workflows.

Zoho Books is a cloud-based accounting software that helps you manage your finances, automate business workflows, and work collectively across departments.

Zoho Inventory is an inventory management software that helps you manage your stock, create assemblies, track inventory movements, and streamline order fulfillment.

n8n is a fair-code licensed workflow automation platform.

Table of Contents

• Installation
• Authentication
• Operations
• Resources
• Usage Examples
• Common Workflows
• Troubleshooting
• Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Using npm

• Navigate to your n8n installation directory
• Install the node:

  npm install n8n-nodes-zoho-books
  

• Restart n8n

Manual Installation

• Clone or download this repository
• Copy the n8n-nodes-zoho-books folder to your n8n custom nodes folder
• Install dependencies:

  cd /path/to/n8n-custom-nodes/n8n-nodes-zoho-books
  npm install
  

• Build the node:

  npm run build
  

• Restart n8n

Authentication

These nodes use OAuth2 authentication to connect to Zoho Books and Zoho Inventory. Follow these steps to set up authentication:

1. Create Zoho OAuth Client

• Go to Zoho API Console
• Click on "Add Client"
• Choose "Server-based Applications"
• Fill in the details:
  • Client Name: n8n Zoho Books Integration (or any name you prefer)
  • Homepage URL: Your n8n instance URL
  • Authorized Redirect URIs: https://your-n8n-instance.com/rest/oauth2-credential/callback
• Click "Create"
• Note down the Client ID and Client Secret

2. Get Organization ID

• Log in to your Zoho Books account
• Go to Settings > Organization Profile
• Copy your Organization ID

3. Configure Credentials in n8n

For Zoho Books:

• In n8n, go to Credentials > New
• Select Zoho Books OAuth2 API
• Configure the following:
  • Data Center: Select your Zoho data center (COM, EU, IN, AU, or CN)
  • Organization ID: Paste your Organization ID
  • Client ID: Paste from Zoho API Console
  • Client Secret: Paste from Zoho API Console
• Click Save to create the credentials
• Click Connect to authenticate

For Zoho Inventory:

• In n8n, go to Credentials > New
• Select Zoho Inventory OAuth2 API
• Configure the following:
  • Data Center: Select your Zoho data center (COM, EU, IN, AU, or CN)
  • Organization ID: Paste your Organization ID (same as Zoho Books if using the same organization)
  • Client ID: Paste from Zoho API Console (can use the same OAuth client)
  • Client Secret: Paste from Zoho API Console
• Click Save to create the credentials
• Click Connect to authenticate
• Authorize the requested permissions in the Zoho popup

Screenshot: Zoho Books OAuth2 credential configuration in n8n

Operations

The Zoho Books node supports the following operations across different resources:

Standard Operations

• Create: Create a new record
• Get: Retrieve a single record by ID
• Get Many: Retrieve multiple records with optional filtering
• Update: Update an existing record
• Delete: Delete or void a record

Resources

1. Sales Order

Manage sales orders in your Zoho Books account.

Operations:

• Create sales order
• Get sales order details
• List all sales orders
• Update sales order
• Void sales order

2. Invoice

Handle customer invoices and billing.

Operations:

• Create invoice
• Get invoice details
• List all invoices
• Update invoice
• Void invoice

3. Item

Manage products and services.

Operations:

• Create item
• Get item details
• Get item by SKU code
• List all items
• Update item
• Delete item

New Feature: The Get by SKU operation allows you to retrieve items using their SKU code instead of the item ID, making it easier to integrate with external systems that use SKU-based references.

4. Payment

Track customer payments.

Operations:

• Record payment
• Get payment details
• List all payments
• Update payment
• Delete payment

5. Vendor

Manage vendor/supplier information.

Operations:

• Create vendor
• Get vendor details
• List all vendors
• Update vendor
• Delete vendor

6. Credit Note

Handle credit notes for returns and adjustments.

Operations:

• Create credit note
• Get credit note details
• List all credit notes
• Update credit note
• Void credit note

Usage Examples

Example 1: Create an Invoice

{
  "resource": "invoice",
  "operation": "create",
  "customerId": "{{$node.Customer.json.contact_id}}",
  "lineItems": {
    "item": [
      {
        "item_id": "{{$node.Item.json.item_id}}",
        "quantity": 2,
        "rate": 99.99
      }
    ]
  },
  "additionalFields": {
    "date": "2024-01-15",
    "notes": "Thank you for your business!"
  }
}

Example 2: List Recent Sales Orders

{
  "resource": "salesOrder",
  "operation": "getAll",
  "returnAll": false,
  "limit": 10,
  "filters": {
    "status": "open",
    "fromDate": "2024-01-01"
  }
}

Example 3: Record a Payment

{
  "resource": "payment",
  "operation": "create",
  "customerId": "{{$node.Customer.json.contact_id}}",
  "paymentMode": "creditcard",
  "amount": 199.98,
  "additionalFields": {
    "date": "2024-01-15",
    "referenceNumber": "PAY-2024-001"
  }
}

Example 4: Get Item by SKU Code

{
  "resource": "item",
  "operation": "getBySku",
  "skuCode": "LAPTOP-001"
}

This operation will return the complete item details including stock levels, pricing, and warehouse information based on the SKU code. This is particularly useful when:

• Integrating with external systems that use SKU references
• Processing inventory from barcode scans
• Updating stock levels from supplier feeds
• Creating invoices where you know the SKU but not the item ID

Response example:

{
  "item_id": "123456789",
  "name": "Premium Laptop",
  "sku": "LAPTOP-001",
  "description": "High-performance laptop for professionals",
  "rate": 1299.99,
  "stock_on_hand": 25,
  "available_stock": 23,
  "status": "active",
  "item_type": "inventory"
}

Zoho Inventory Resources

1. Composite Item

Manage composite items (bundled products) in your Zoho Inventory account.

Operations:

• Create composite item with line items
• Get composite item details
• List all composite items
• Update composite item and line items
• Delete composite item

Key Fields:

• name: Name of the composite item
• sku: Stock Keeping Unit
• rate: Selling price
• lineItems: Component items and quantities

2. Assembly

Create and manage assemblies for composite items.

Operations:

• Create assembly: Assemble composite items from components
• Get assembly details
• Get assembly history: View all assemblies for a composite item
• Delete assembly

Key Fields:

• compositeItemId: ID of the composite item to assemble
• quantity: Quantity to assemble
• date: Assembly date
• referenceNumber: Reference for tracking

3. Item

Manage inventory items in your Zoho Inventory account.

Operations:

• Create item
• Get item details by ID
• Get item by SKU code
• List all items with filtering
• Update item
• Delete item

Key Features:

• SKU-based lookup: Find items using their SKU code for easier integration
• Stock tracking: Access stock levels, warehouse information, and availability
• Multi-warehouse support: Handle items across multiple warehouse locations
• Serial/batch tracking: Support for items with serial numbers or batch numbers

Common Workflows

1. Order to Invoice Automation

Workflow: Automatically create invoices from confirmed sales orders

• Trigger: Webhook or schedule trigger
• Zoho Books - Get Sales Orders: Fetch confirmed orders
• Zoho Books - Create Invoice: Convert each order to invoice
• Email: Send invoice to customer

2. Payment Reconciliation

Workflow: Match bank transactions with customer payments

• Bank API: Fetch new transactions
• Zoho Books - Get Customers: Match by reference
• Zoho Books - Create Payment: Record matched payments
• Slack: Notify finance team

3. Inventory Management

Workflow: Update item stock levels from external system

• External System: Get stock levels
• Zoho Books - Get Items: Fetch current items
• Compare: Calculate differences
• Zoho Books - Update Items: Update stock levels

4. Vendor Bill Processing

Workflow: Automate vendor bill creation from emails

• Email Trigger: New vendor email
• Extract Data: Parse bill details
• Zoho Books - Create Vendor: Create if new
• Zoho Books - Create Bill: Record the bill

5. Monthly Reporting

Workflow: Generate monthly sales reports

• Schedule Trigger: First day of month
• Zoho Books - Get Invoices: Last month's invoices
• Aggregate Data: Calculate totals
• Create Report: Format data
• Email/Slack: Send to stakeholders

6. SKU-based Inventory Sync

Workflow: Synchronize inventory from external system using SKU codes

• External System API: Fetch inventory updates with SKU codes
• Zoho Books/Inventory - Get by SKU: Find items by SKU code
• Compare Data: Check stock levels and pricing differences
• Zoho Books/Inventory - Update Item: Update stock levels and prices
• Notification: Alert inventory manager of changes

Benefits of SKU-based approach:

• No need to maintain item ID mappings
• Works with barcode systems that use SKU
• Easier integration with external inventory systems
• More reliable for bulk operations

Troubleshooting

Common Issues

Authentication Errors

• Invalid Organization ID: Verify the Organization ID in Zoho Books Settings
• Token Expired: Re-authenticate by clicking "Connect" in credentials
• Insufficient Permissions: Ensure the OAuth app has ZohoBooks.fullaccess.all scope

API Errors

• Rate Limiting: The node implements automatic retry with exponential backoff
• Invalid Data: Check required fields and data formats
• Resource Not Found: Verify IDs are correct and resources exist

Data Issues

• Missing Line Items: Line items are required for invoices and sales orders
• Currency Mismatch: Ensure currency matches organization settings
• Tax Calculation: Configure tax settings in Zoho Books first

SKU-Related Issues

• SKU Not Found: Verify the SKU code exists and is spelled correctly (case-insensitive search)
• Multiple Items with Same SKU: Ensure SKU codes are unique across your organization
• Empty SKU Code: Provide a valid, non-empty SKU code for the search
• Special Characters in SKU: SKU codes with special characters are supported

Error Messages

Error Code	Description	Solution
1002	Invalid data	Check field formats and required fields
1001	Resource not found	Verify the ID exists
4000	Rate limit exceeded	Wait and retry, node handles automatically
1000	Invalid Organization ID	Check credentials configuration
400	SKU code is required	Provide a valid, non-empty SKU code
404	Item with SKU not found	Verify the SKU code exists in your system
409	Multiple items with same SKU	Ensure SKU codes are unique
500	Invalid API response format	Contact support if this persists

Debug Mode

To enable detailed logging:

• Set n8n log level to debug
• Check execution data for API responses
• Use "Console" node to inspect data structure

Resources

• Zoho Books API Documentation - Official API reference
• n8n Documentation - Learn about n8n and workflow automation
• n8n Community Forum - Get help from the community
• GitHub Repository - Report issues and contribute

Version History

See CHANGELOG.md for version history and updates.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT