🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Zoho Books
πŸ¦€ ClawHub

Zoho Books

by @byungkyu

Zoho Books API integration with managed OAuth. Manage invoices, contacts, bills, expenses, and other accounting data. Use this skill when users want to read,...

Versionv1.0.3
Downloads4,378
Installs2
Stars⭐ 3
#crypto-defi#security#audio#finance#legal
TERMINAL
clawhub install zoho-books

πŸ“– About This Skill

name: zoho-books description: | Zoho Books API integration with managed OAuth. Manage invoices, contacts, bills, expenses, and other accounting data. Use this skill when users want to read, create, update, or delete invoices, contacts, bills, expenses, or other financial records in Zoho Books. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY

Zoho Books

Access the Zoho Books API with managed OAuth authentication. Manage invoices, contacts, bills, expenses, sales orders, purchase orders, and other accounting data with full CRUD operations.

Quick Start

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/zoho-books/books/v3/{endpoint}

Maton proxies requests to www.zohoapis.com/books/v3 and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

Manage your Zoho Books OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=zoho-books&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-books'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response: 

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-books",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Zoho Books connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

  • Access is scoped to invoices, contacts, bills, expenses, and other accounting data within the connected Zoho Books account.
  • All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

    • API Reference

    Available Modules

    Zoho Books organizes data into modules. Key modules include:

    | Module | Endpoint | Description | |--------|----------|-------------| | Contacts | /contacts | Customers and vendors | | Invoices | /invoices | Sales invoices | | Bills | /bills | Vendor bills | | Expenses | /expenses | Business expenses | | Sales Orders | /salesorders | Sales orders | | Purchase Orders | /purchaseorders | Purchase orders | | Credit Notes | /creditnotes | Customer credit notes | | Recurring Invoices | /recurringinvoices | Automated recurring invoices | | Recurring Bills | /recurringbills | Automated recurring bills |

    Contacts

    #### List Contacts

    GET /zoho-books/books/v3/contacts

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Response: 

    {
  "code": 0,
  "message": "success",
  "contacts": [...],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "sort_column": "contact_name",
    "sort_order": "A"
  }
}

    #### Get Contact

    GET /zoho-books/books/v3/contacts/{contact_id}

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    #### Create Contact

    POST /zoho-books/books/v3/contacts
Content-Type: application/json
    {
  "contact_name": "Customer Name",
  "contact_type": "customer"
}

    Required Fields:

  • contact_name - Display name for the contact
  • contact_type - Either customer or vendor

    • Optional Fields:

  • company_name - Legal entity name
  • email - Email address
  • phone - Phone number
  • billing_address - Address object
  • payment_terms - Days for payment

    • Example:

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "contact_name": "Acme Corporation",
    "contact_type": "customer",
    "company_name": "Acme Corp",
    "email": "billing@acme.com",
    "phone": "+1-555-1234"
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Response: 

    {
  "code": 0,
  "message": "The contact has been added.",
  "contact": {
    "contact_id": "8527119000000099001",
    "contact_name": "Acme Corporation",
    "company_name": "Acme Corp",
    "contact_type": "customer",
    ...
  }
}

    #### Update Contact

    PUT /zoho-books/books/v3/contacts/{contact_id}
Content-Type: application/json
    {
  "contact_name": "Updated Name",
  "phone": "+1-555-9999"
}

    Example:

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "contact_name": "Acme Corporation Updated",
    "phone": "+1-555-9999"
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    #### Delete Contact

    DELETE /zoho-books/books/v3/contacts/{contact_id}

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts/8527119000000099001', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Response: 

    {
  "code": 0,
  "message": "The customer has been deleted."
}

    Invoices

    #### List Invoices

    GET /zoho-books/books/v3/invoices

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/invoices')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    #### Get Invoice

    GET /zoho-books/books/v3/invoices/{invoice_id}

    #### Create Invoice

    POST /zoho-books/books/v3/invoices
Content-Type: application/json
    {
  "customer_id": "8527119000000099001",
  "line_items": [
    {
      "item_id": "8527119000000100001",
      "quantity": 1,
      "rate": 100.00
    }
  ]
}

    Required Fields:

  • customer_id - Customer identifier
  • line_items - Array of items with item_id or manual entry

    • Optional Fields:

  • invoice_number - Auto-generated if not specified
  • date - Invoice date (yyyy-mm-dd format)
  • due_date - Payment due date
  • discount - Percentage or fixed amount
  • payment_terms - Days until due

    • #### Update Invoice

    PUT /zoho-books/books/v3/invoices/{invoice_id}

    #### Delete Invoice

    DELETE /zoho-books/books/v3/invoices/{invoice_id}

    #### Invoice Actions

    # Mark as sent
POST /zoho-books/books/v3/invoices/{invoice_id}/status/sent
    Void invoice
    
POST /zoho-books/books/v3/invoices/{invoice_id}/status/void
    Email invoice
    
POST /zoho-books/books/v3/invoices/{invoice_id}/email

    Bills

    #### List Bills

    GET /zoho-books/books/v3/bills

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/bills')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    #### Create Bill

    POST /zoho-books/books/v3/bills
Content-Type: application/json
    {
  "vendor_id": "8527119000000099002",
  "bill_number": "BILL-001",
  "date": "2026-02-06",
  "line_items": [
    {
      "account_id": "8527119000000100002",
      "description": "Office Supplies",
      "amount": 150.00
    }
  ]
}

    Required Fields:

  • vendor_id - Vendor identifier
  • bill_number - Unique bill number
  • date - Bill date (yyyy-mm-dd)

    • #### Update Bill

    PUT /zoho-books/books/v3/bills/{bill_id}

    #### Delete Bill

    DELETE /zoho-books/books/v3/bills/{bill_id}

    Expenses

    #### List Expenses

    GET /zoho-books/books/v3/expenses

    Example:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/expenses')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    #### Create Expense

    POST /zoho-books/books/v3/expenses
Content-Type: application/json
    {
  "account_id": "8527119000000100003",
  "date": "2026-02-06",
  "amount": 75.50,
  "paid_through_account_id": "8527119000000100004",
  "description": "Business lunch"
}

    Required Fields:

  • account_id - Expense account ID
  • date - Expense date (yyyy-mm-dd)
  • amount - Expense amount
  • paid_through_account_id - Payment account ID

    • Optional Fields:

  • description - Expense details
  • customer_id - Billable customer ID
  • is_billable - Boolean for billable expenses
  • project_id - Associated project

    • #### Update Expense

    PUT /zoho-books/books/v3/expenses/{expense_id}

    #### Delete Expense

    DELETE /zoho-books/books/v3/expenses/{expense_id}

    Sales Orders

    #### List Sales Orders

    GET /zoho-books/books/v3/salesorders

    #### Create Sales Order

    POST /zoho-books/books/v3/salesorders

    Purchase Orders

    #### List Purchase Orders

    GET /zoho-books/books/v3/purchaseorders

    #### Create Purchase Order

    POST /zoho-books/books/v3/purchaseorders

    Credit Notes

    #### List Credit Notes

    GET /zoho-books/books/v3/creditnotes

    Recurring Invoices

    #### List Recurring Invoices

    GET /zoho-books/books/v3/recurringinvoices

    Recurring Bills

    #### List Recurring Bills

    GET /zoho-books/books/v3/recurringbills

    Pagination

    Zoho Books uses page-based pagination:

    GET /zoho-books/books/v3/contacts?page=1&per_page=50

    Response includes pagination info in page_context:

    {
  "code": 0,
  "message": "success",
  "contacts": [...],
  "page_context": {
    "page": 1,
    "per_page": 50,
    "has_more_page": true,
    "sort_column": "contact_name",
    "sort_order": "A"
  }
}

    Continue fetching while has_more_page is true, incrementing page each time.

    Code Examples

    JavaScript

    const response = await fetch(
  'https://api.maton.ai/zoho-books/books/v3/contacts',
  {
    headers: {
      'Authorization': Bearer ${process.env.MATON_API_KEY}
    }
  }
);
const data = await response.json();

    Python

    import os
import requests
    response = requests.get(
    'https://api.maton.ai/zoho-books/books/v3/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

    Notes

  • All successful responses have code: 0 and a message field
  • Dates should be in yyyy-mm-dd format
  • Contact types are customer or vendor
  • Some modules (items, chart of accounts, bank accounts, projects) may require additional OAuth scopes. If you receive a scope error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case
  • Rate limits: 100 requests/minute per organization
  • Daily limits vary by plan: Free (1,000), Standard (2,000), Professional (5,000), Paid (10,000)
  • IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

    • Error Handling

    | Status | Meaning | |--------|---------| | 400 | Missing Zoho Books connection or invalid request | | 401 | Invalid or missing Maton API key, or OAuth scope mismatch | | 404 | Resource not found | | 429 | Rate limited | | 4xx/5xx | Passthrough error from Zoho Books API |

    Common Error Codes

    | Code | Description | |------|-------------| | 0 | Success | | 57 | Not authorized (OAuth scope mismatch) | | 1 | Invalid value | | 2 | Mandatory field missing | | 3 | Resource does not exist | | 5 | Invalid URL |

    Troubleshooting: API Key Issues

    1. Check that the MATON_API_KEY environment variable is set:

    echo $MATON_API_KEY

    2. Verify the API key is valid by listing connections:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Troubleshooting: Invalid App Name

    1. Ensure your URL path starts with zoho-books. For example:

  • Correct: https://api.maton.ai/zoho-books/books/v3/contacts
  • Incorrect: https://api.maton.ai/books/v3/contacts

    • Resources

  • Zoho Books API v3 Introduction
  • Zoho Books Invoices API
  • Zoho Books Contacts API
  • Zoho Books Bills API
  • Zoho Books Expenses API
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

    # List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-books/books/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    πŸ“‹ Tips & Best Practices

  • All successful responses have code: 0 and a message field
  • Dates should be in yyyy-mm-dd format
  • Contact types are customer or vendor
  • Some modules (items, chart of accounts, bank accounts, projects) may require additional OAuth scopes. If you receive a scope error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case
  • Rate limits: 100 requests/minute per organization
  • Daily limits vary by plan: Free (1,000), Standard (2,000), Professional (5,000), Paid (10,000)
  • IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments