n8n-nodes-zoho

Comprehensive Zoho API integration for n8n workflows with OAuth2 authentication and multiple service support.

Features

• OAuth2 Authentication: Secure credential management with automatic token refresh
• Multi-Regional Support: Works with Zoho services across US, EU, IN, AU, and CN regions
• Comprehensive API Coverage: Four specialized nodes covering major Zoho services
• TypeScript Implementation: Full type safety and modern development practices
• n8n Native Integration: Seamless integration with n8n's workflow ecosystem

Available Nodes

🗂️ Zoho Sheets

Complete spreadsheet management capabilities:

• Create and list workbooks
• Add records to worksheets with JSON data support
• Header row configuration and flexible data input

✅ Zoho Tasks

Full task and project management:

• Personal Tasks: Create, retrieve, update, and delete personal tasks
• Group Tasks: Manage tasks within team groups
• Project Management: Create and manage projects with task assignments
• Subtask Support: Handle hierarchical task structures
• Advanced Features: Priority management, status updates, due dates, reminders, and recurring tasks

💰 Zoho Billing (Subscriptions)

Comprehensive billing and subscription management:

• Products & Plans: CRUD operations for products and subscription plans
• Subscriptions: Create, update, cancel, and manage subscriptions
• Customers: Complete customer lifecycle management including bulk operations
• Invoices: Invoice creation, updates, and status filtering
• Payments: Payment processing and tracking
• Add-ons & Items: Manage additional services and items
• Events: Access billing events and transaction history

📧 Zoho Email

Advanced email automation:

• Send immediate or scheduled emails
• Support for HTML and plain text formats
• CC/BCC functionality with multiple recipients
• Read receipt requests and custom encoding options
• Flexible Scheduling: Multiple scheduling options including custom date/time
• Timezone support for global operations

Installation

Prerequisites

• n8n installed and running
• Node.js 16+ and npm
• Zoho developer account with API access

Installation Methods

Option 1: NPM Installation (Recommended)

npm install n8n-nodes-zoho

Option 2: Custom Nodes Directory

# Clone to your n8n custom nodes directory
git clone https://github.com/vladaman/n8n-nodes-zoho.git ~/.n8n/custom/n8n-nodes-zoho
cd ~/.n8n/custom/n8n-nodes-zoho
npm install
npm run build

Option 3: Development Setup

git clone https://github.com/vladaman/n8n-nodes-zoho.git
cd n8n-nodes-zoho
npm install
npm run build
npm test  # Run tests (optional)

After installation, restart n8n to load the new nodes and credentials.

Configuration

1. Zoho Developer Setup

Before using the nodes, you need to create a Zoho application:

1. Go to Zoho Developer Console
2. Create a new application and note your Client ID and Client Secret
3. Configure appropriate scopes based on the services you'll use:
   • Sheets: ZohoSheet.operation.ALL
   • Tasks: ZohoTasks.operation.ALL
   • Billing: ZohoBilling.operation.ALL
   • Email: ZohoMail.operation.ALL

2. n8n Credential Configuration

1. In n8n, navigate to Settings → Credentials

2. Click Add Credential and select Zoho API

3. Configure the following settings:

   Field	Value	Notes
   Client ID	Your Zoho app client ID	From developer console
   Client Secret	Your Zoho app client secret	Keep secure
   Authorization URL	Regional endpoint	See table below
   Access Token URL	Regional endpoint	See table below
   Scope	Service-specific scopes	Comma-separated

Regional Endpoints

Region	Authorization URL	Access Token URL
US	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.com/oauth/v2/token
EU	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.eu/oauth/v2/token
India	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.in/oauth/v2/token
Australia	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.com.au/oauth/v2/token
China	https://accounts.zoho.com.cn/oauth/v2/auth	https://accounts.zoho.com.cn/oauth/v2/token

4. Click Connect and complete the OAuth2 authorization flow
5. Test the connection to ensure proper setup

Usage Examples

Zoho Sheets Examples

Create and Populate a Workbook

// 1. Create Workbook Node
Operation: "Create Workbook"
Workbook Name: "Sales Report 2024"

// 2. Add Records Node  
Operation: "Add Records to Worksheet"
Workbook Resource ID: "{{$node["Create Workbook"].json["workbook"]["resource_id"]}}"
Worksheet Name: "Sheet1"
Header Row: 1
JSON Data: '[{"Name":"John","Sales":1000},{"Name":"Jane","Sales":1500}]'

List and Filter Workbooks

Operation: "List Workbooks"
Start Index: 1
Count: 50
Sort Option: "recently_modified"

Zoho Tasks Examples

Create and Manage Tasks

// Personal Task
Operation: "Add Personal Task"
JSON Data: '{"title":"Review quarterly report","priority":"high","due_date":"2024-01-31"}'

// Group Task with Project
Operation: "Add Group Task"
Group ID: "your_group_id"
JSON Data: '{"title":"Website redesign","project_id":"proj_123","assignee":"[email protected]"}'

Task Updates and Management

// Update Task Status
Operation: "Change Task Status"
Group ID: "your_group_id"
Task ID: "task_456"
JSON Data: '{"status":"completed"}'

// Set Reminder
Operation: "Set/Change Task Reminder"
JSON Data: '{"reminder_datetime":"2024-01-30T09:00:00Z","reminder_type":"email"}'

Zoho Billing Examples

Customer and Subscription Management

// List Customers
Operation: "List"
Resource: "Customer"
Organization ID: "your_org_id"
Status Filter:
  Status: ["Status.Active"]
Filters: [
  { filterBy: 'contact_number_contains', filterValue: '12345' },
  { filterBy: 'email_contains',           filterValue: '[email protected]' },
  { filterBy: 'custom_field', customFieldId: '789785000000088591', filterValue: 'some substring' },
]

// List Subscriptions (with optional search and paging)
Operation: "List"
Resource: "Subscription"
Organization ID: "your_org_id"
Filters: [
  { filterBy: 'search_text',                  filterValue: 'widget'   },
  { filterBy: 'subscription_number_contains', filterValue: 'sub_1234' },
  { filterBy: 'reference_contains',           filterValue: 'ref_5678' },
  { filterBy: 'filter_by',                    filterValue: 'UNPAID'   },
]
Page: 2
Per Page: 50

// Create Subscription
Operation: "Create"
Resource: "Subscription"
JSON Data: '{"customer_id":"cust_123","plan_id":"plan_456","starts_at":"2024-01-01"}'

Invoice and Payment Processing

// Filter Invoices
Operation: "List"
Resource: "Invoice"
Filter By: "Overdue"
Customer ID: "cust_123"

// Create Payment
Operation: "Create"
Resource: "Payment"
JSON Data: '{"customer_id":"cust_123","amount":99.99,"payment_mode":"credit_card"}'

Zoho Email Examples

Send Immediate Email

Operation: "Send Email"
Account ID: "your_account_id"
From Address: "[email protected]"
To Address: "[email protected]"
Subject: "Welcome to our service"
Content: "<h1>Welcome!</h1><p>Thanks for joining us.</p>"
Mail Format: "html"

Schedule Email Campaign

Operation: "Send Email"
// ... basic email fields ...
Is Schedule: true
Schedule Type: 6  // Custom date & time
Time Zone: "GMT +5:30"
Schedule Time: "01/25/2024 10:30:00"

Advanced Configuration

Error Handling

All nodes include comprehensive error handling with detailed error messages. Use n8n's built-in error handling to:

• Retry failed requests
• Route errors to separate workflow paths
• Log errors for debugging

Rate Limiting

Zoho APIs have rate limits. Consider:

• Adding delays between requests for bulk operations
• Using n8n's batch processing capabilities
• Implementing exponential backoff for retries

Data Transformation

Leverage n8n's expression editor for:

• Dynamic parameter values
• Data format conversion
• Complex JSON manipulation

API Documentation

Detailed API documentation is available in the docs/ directory:

• Email API Documentation - Complete email functionality reference
• Tasks API Documentation - Task and project management details

Development

Project Structure

n8n-nodes-zoho/
├── credentials/          # OAuth2 credential definitions
├── nodes/               # Node implementations
│   ├── ZohoBilling.node.ts
│   ├── ZohoEmail.node.ts
│   ├── ZohoSheets.node.ts
│   ├── ZohoTasks.node.ts
│   ├── GenericFunctions.ts
│   └── types.ts
├── docs/                # API documentation
└── dist/                # Compiled output

Building from Source

# Clone the repository
git clone https://github.com/vladaman/n8n-nodes-zoho.git
cd n8n-nodes-zoho

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run tslint

# Watch for changes during development
npm run watch

# Run tests (if available)
npm test

Development Scripts

• npm run build - Compile TypeScript and build distribution
• npm run watch - Watch for changes and rebuild automatically
• npm run tslint - Run TypeScript linting
• npm run dev - Alias for watch mode
• npm run release - Build and publish to npm

Troubleshooting

Common Issues

Authentication Errors

• Verify your Client ID and Client Secret are correct
• Ensure the correct regional endpoints are configured
• Check that your Zoho app has the required scopes
• Confirm your OAuth2 callback URL is properly set in Zoho Developer Console

API Rate Limits

• Implement delays between bulk operations
• Use n8n's batch processing features
• Monitor your API usage in Zoho Developer Console

Regional Configuration

• Double-check you're using the correct endpoints for your Zoho region
• Ensure your Zoho account and application are in the same region

Getting Help

• Check the GitHub Issues for known problems
• Review the official Zoho API Documentation
• Consult the n8n Community for workflow-specific questions

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository on GitHub
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the existing code style
4. Add tests if applicable
5. Run linting (npm run tslint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain backward compatibility
• Add appropriate error handling
• Update documentation for new features
• Test your changes thoroughly

License

This project is licensed under the GPL-3.0 License.

Acknowledgments

• Built for the n8n automation platform
• Uses Zoho APIs for service integration
• TypeScript implementation following n8n node development standards