KosmoKrator

data

Zoho Books Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Zoho Books KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.zoho_books.*. Use lua_read_doc("integrations.zoho-books") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Zoho Books workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.zoho_books.list_invoices({status = "example_status", customer_id = "example_customer_id", date_start = "example_date_start", date_end = "example_date_end", page = 1, per_page = 1, search_text = "example_search_text"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("zoho-books"))' --json
kosmo integrations:lua --eval 'print(docs.read("zoho-books.list_invoices"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local zoho_books = app.integrations.zoho_books
local result = zoho_books.list_invoices({status = "example_status", customer_id = "example_customer_id", date_start = "example_date_start", date_end = "example_date_end", page = 1, per_page = 1, search_text = "example_search_text"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.zoho_books, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.zoho_books.default.* or app.integrations.zoho_books.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Zoho Books, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Zoho Books — Lua API Reference

list_invoices

List invoices from Zoho Books.

Parameters

NameTypeRequiredDescription
statusstringnoFilter by status: draft, sent, overdue, paid, voided, unpaid
customer_idstringnoFilter by customer ID
date_startstringnoStart date (ISO 8601, e.g., "2025-01-01")
date_endstringnoEnd date (ISO 8601, e.g., "2025-12-31")
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
search_textstringnoSearch by invoice number or customer name

Example

local result = app.integrations["zoho-books"].zohobooks_list_invoices({
  status = "unpaid",
  per_page = 10
})

for _, inv in ipairs(result.invoices) do
  print(inv.invoice_number .. " — " .. inv.total .. " (" .. inv.status .. ")")
end

get_invoice

Get full details of a specific invoice.

Parameters

NameTypeRequiredDescription
invoice_idstringyesThe invoice ID

Example

local result = app.integrations["zoho-books"].zohobooks_get_invoice({
  invoice_id = "4815000000046819"
})

print("Invoice: " .. result.invoice_number)
print("Total: " .. result.total)
for _, item in ipairs(result.line_items) do
  print("  - " .. item.name .. ": " .. item.rate .. " x " .. item.quantity)
end

create_invoice

Create a new invoice.

Parameters

NameTypeRequiredDescription
customer_idstringyesCustomer (contact) ID
line_itemsarrayyesArray of line items (see below)
datestringnoInvoice date (ISO 8601)
due_datestringnoPayment due date (ISO 8601)
invoice_numberstringnoCustom invoice number
reference_numberstringnoReference / PO number
notesstringnoNotes on the invoice
termsstringnoTerms and conditions

Line Item Format

Each line item object:

{
  item_id = "4815000000046810",  -- optional: existing item ID
  name = "Consulting",           -- or provide name directly
  rate = 150.00,
  quantity = 10,
  description = "Strategy consulting hours"
}

Example

local result = app.integrations["zoho-books"].zohobooks_create_invoice({
  customer_id = "4815000000044001",
  line_items = {
    {
      name = "Web Design",
      rate = 2500.00,
      quantity = 1,
      description = "Homepage redesign"
    },
    {
      item_id = "4815000000046810",
      quantity = 5
    }
  },
  date = "2025-06-01",
  due_date = "2025-06-30",
  notes = "Thank you for your business!"
})

print("Created invoice: " .. result.invoice.invoice_number)

update_invoice

Update an existing invoice.

Parameters

NameTypeRequiredDescription
invoice_idstringyesThe invoice ID to update
customer_idstringnoChange customer
line_itemsarraynoReplace all line items
datestringnoInvoice date
due_datestringnoDue date
statusstringnoStatus: draft, sent, voided
notesstringnoInvoice notes
termsstringnoTerms
reference_numberstringnoReference number

Example

local result = app.integrations["zoho-books"].zohobooks_update_invoice({
  invoice_id = "4815000000046819",
  notes = "Updated: payment via bank transfer",
  status = "sent"
})

print("Updated invoice: " .. result.invoice.invoice_number)

list_contacts

List contacts (customers and vendors).

Parameters

NameTypeRequiredDescription
contact_typestringnocustomer, vendor, or all (default: all)
statusstringnoactive, inactive, or all
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
search_textstringnoSearch by name or email

Example

local result = app.integrations["zoho-books"].zohobooks_list_contacts({
  contact_type = "customer",
  per_page = 20
})

for _, contact in ipairs(result.contacts) do
  print(contact.contact_name .. " (" .. (contact.email or "no email") .. ")")
end

get_contact

Get full details of a specific contact.

Parameters

NameTypeRequiredDescription
contact_idstringyesThe contact ID

Example

local result = app.integrations["zoho-books"].zohobooks_get_contact({
  contact_id = "4815000000044001"
})

print("Name: " .. result.contact_name)
print("Email: " .. (result.email or "N/A"))
print("Outstanding: " .. (result.outstanding_receivable_amount or "0"))

create_contact

Create a new contact (customer or vendor).

Parameters

NameTypeRequiredDescription
namestringyesContact name
emailstringnoPrimary email
phonestringnoPhone number
company_namestringnoCompany name
contact_typestringnocustomer or vendor (default: customer)
billing_addressobjectnoBilling address
shipping_addressobjectnoShipping address
notesstringnoInternal notes

Address Object

{
  attention = "John Doe",
  address = "123 Main St",
  city = "Amsterdam",
  state = "North Holland",
  zip = "1012 AB",
  country = "Netherlands",
  phone = "+31 20 123 4567"
}

Example

local result = app.integrations["zoho-books"].zohobooks_create_contact({
  name = "Acme Corp",
  email = "billing@acme.com",
  contact_type = "customer",
  billing_address = {
    address = "123 Business Ave",
    city = "New York",
    state = "NY",
    zip = "10001",
    country = "USA"
  }
})

print("Created contact: " .. result.contact.contact_id)

list_items

List items (products and services).

Parameters

NameTypeRequiredDescription
filter_typestringnoactive, inactive, sales, purchases, all
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
search_textstringnoSearch by name or description

Example

local result = app.integrations["zoho-books"].zohobooks_list_items({
  filter_type = "active"
})

for _, item in ipairs(result.items) do
  print(item.name .. " — " .. item.rate .. " " .. (item.unit or ""))
end

create_item

Create a new item (product or service).

Parameters

NameTypeRequiredDescription
namestringyesItem name
ratenumberyesUnit price
descriptionstringnoDescription shown on invoices
unitstringnoUnit of measurement (e.g., "hrs", "pcs")
item_typestringnosales, purchases, or both (default: both)
tax_idstringnoTax ID to apply
skustringnoSKU identifier

Example

local result = app.integrations["zoho-books"].zohobooks_create_item({
  name = "Consulting Hour",
  rate = 175.00,
  description = "Professional consulting per hour",
  unit = "hrs",
  item_type = "sales"
})

print("Created item: " .. result.item.item_id)

list_estimates

List estimates (quotes).

Parameters

NameTypeRequiredDescription
statusstringnodraft, sent, accepted, declined, expired, invoiced, all
customer_idstringnoFilter by customer ID
date_startstringnoStart date (ISO 8601)
date_endstringnoEnd date (ISO 8601)
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
search_textstringnoSearch by estimate number or customer name

Example

local result = app.integrations["zoho-books"].zohobooks_list_estimates({
  status = "accepted"
})

for _, est in ipairs(result.estimates) do
  print(est.estimate_number .. " — " .. est.total .. " (" .. est.status .. ")")
end

create_estimate

Create a new estimate (quote).

Parameters

NameTypeRequiredDescription
customer_idstringyesCustomer (contact) ID
line_itemsarrayyesArray of line items (same format as create_invoice)
datestringnoEstimate date (ISO 8601)
expiry_datestringnoExpiry date (ISO 8601)
estimate_numberstringnoCustom estimate number
reference_numberstringnoReference number
notesstringnoNotes on the estimate
termsstringnoTerms and conditions

Example

local result = app.integrations["zoho-books"].zohobooks_create_estimate({
  customer_id = "4815000000044001",
  line_items = {
    {
      name = "Website Development",
      rate = 5000.00,
      quantity = 1,
      description = "Complete website build"
    }
  },
  date = "2025-06-01",
  expiry_date = "2025-07-01",
  notes = "Valid for 30 days"
})

print("Created estimate: " .. result.estimate.estimate_number)

get_current_user

Get the currently authenticated Zoho Books user.

Parameters

None.

Example

local result = app.integrations["zoho-books"].zohobooks_get_current_user({})

print("Logged in as: " .. (result.users and result.users[1] and result.users[1].name or "Unknown"))

Multi-Account Usage

If you have multiple Zoho Books accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations["zoho-books"].zohobooks_function_name({...})

-- Explicit default (portable across setups)
app.integrations["zoho-books"].default.zohobooks_function_name({...})

-- Named accounts
app.integrations["zoho-books"].production.zohobooks_function_name({...})
app.integrations["zoho-books"].sandbox.zohobooks_function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Zoho Books — Lua API Reference

## list_invoices

List invoices from Zoho Books.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | no | Filter by status: `draft`, `sent`, `overdue`, `paid`, `voided`, `unpaid` |
| `customer_id` | string | no | Filter by customer ID |
| `date_start` | string | no | Start date (ISO 8601, e.g., `"2025-01-01"`) |
| `date_end` | string | no | End date (ISO 8601, e.g., `"2025-12-31"`) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `search_text` | string | no | Search by invoice number or customer name |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_list_invoices({
  status = "unpaid",
  per_page = 10
})

for _, inv in ipairs(result.invoices) do
  print(inv.invoice_number .. " — " .. inv.total .. " (" .. inv.status .. ")")
end
```

---

## get_invoice

Get full details of a specific invoice.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `invoice_id` | string | yes | The invoice ID |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_get_invoice({
  invoice_id = "4815000000046819"
})

print("Invoice: " .. result.invoice_number)
print("Total: " .. result.total)
for _, item in ipairs(result.line_items) do
  print("  - " .. item.name .. ": " .. item.rate .. " x " .. item.quantity)
end
```

---

## create_invoice

Create a new invoice.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `customer_id` | string | yes | Customer (contact) ID |
| `line_items` | array | yes | Array of line items (see below) |
| `date` | string | no | Invoice date (ISO 8601) |
| `due_date` | string | no | Payment due date (ISO 8601) |
| `invoice_number` | string | no | Custom invoice number |
| `reference_number` | string | no | Reference / PO number |
| `notes` | string | no | Notes on the invoice |
| `terms` | string | no | Terms and conditions |

### Line Item Format

Each line item object:

```lua
{
  item_id = "4815000000046810",  -- optional: existing item ID
  name = "Consulting",           -- or provide name directly
  rate = 150.00,
  quantity = 10,
  description = "Strategy consulting hours"
}
```

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_create_invoice({
  customer_id = "4815000000044001",
  line_items = {
    {
      name = "Web Design",
      rate = 2500.00,
      quantity = 1,
      description = "Homepage redesign"
    },
    {
      item_id = "4815000000046810",
      quantity = 5
    }
  },
  date = "2025-06-01",
  due_date = "2025-06-30",
  notes = "Thank you for your business!"
})

print("Created invoice: " .. result.invoice.invoice_number)
```

---

## update_invoice

Update an existing invoice.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `invoice_id` | string | yes | The invoice ID to update |
| `customer_id` | string | no | Change customer |
| `line_items` | array | no | Replace all line items |
| `date` | string | no | Invoice date |
| `due_date` | string | no | Due date |
| `status` | string | no | Status: `draft`, `sent`, `voided` |
| `notes` | string | no | Invoice notes |
| `terms` | string | no | Terms |
| `reference_number` | string | no | Reference number |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_update_invoice({
  invoice_id = "4815000000046819",
  notes = "Updated: payment via bank transfer",
  status = "sent"
})

print("Updated invoice: " .. result.invoice.invoice_number)
```

---

## list_contacts

List contacts (customers and vendors).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contact_type` | string | no | `customer`, `vendor`, or `all` (default: `all`) |
| `status` | string | no | `active`, `inactive`, or `all` |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `search_text` | string | no | Search by name or email |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_list_contacts({
  contact_type = "customer",
  per_page = 20
})

for _, contact in ipairs(result.contacts) do
  print(contact.contact_name .. " (" .. (contact.email or "no email") .. ")")
end
```

---

## get_contact

Get full details of a specific contact.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `contact_id` | string | yes | The contact ID |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_get_contact({
  contact_id = "4815000000044001"
})

print("Name: " .. result.contact_name)
print("Email: " .. (result.email or "N/A"))
print("Outstanding: " .. (result.outstanding_receivable_amount or "0"))
```

---

## create_contact

Create a new contact (customer or vendor).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Contact name |
| `email` | string | no | Primary email |
| `phone` | string | no | Phone number |
| `company_name` | string | no | Company name |
| `contact_type` | string | no | `customer` or `vendor` (default: `customer`) |
| `billing_address` | object | no | Billing address |
| `shipping_address` | object | no | Shipping address |
| `notes` | string | no | Internal notes |

### Address Object

```lua
{
  attention = "John Doe",
  address = "123 Main St",
  city = "Amsterdam",
  state = "North Holland",
  zip = "1012 AB",
  country = "Netherlands",
  phone = "+31 20 123 4567"
}
```

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_create_contact({
  name = "Acme Corp",
  email = "billing@acme.com",
  contact_type = "customer",
  billing_address = {
    address = "123 Business Ave",
    city = "New York",
    state = "NY",
    zip = "10001",
    country = "USA"
  }
})

print("Created contact: " .. result.contact.contact_id)
```

---

## list_items

List items (products and services).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `filter_type` | string | no | `active`, `inactive`, `sales`, `purchases`, `all` |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `search_text` | string | no | Search by name or description |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_list_items({
  filter_type = "active"
})

for _, item in ipairs(result.items) do
  print(item.name .. " — " .. item.rate .. " " .. (item.unit or ""))
end
```

---

## create_item

Create a new item (product or service).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Item name |
| `rate` | number | yes | Unit price |
| `description` | string | no | Description shown on invoices |
| `unit` | string | no | Unit of measurement (e.g., `"hrs"`, `"pcs"`) |
| `item_type` | string | no | `sales`, `purchases`, or `both` (default: `both`) |
| `tax_id` | string | no | Tax ID to apply |
| `sku` | string | no | SKU identifier |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_create_item({
  name = "Consulting Hour",
  rate = 175.00,
  description = "Professional consulting per hour",
  unit = "hrs",
  item_type = "sales"
})

print("Created item: " .. result.item.item_id)
```

---

## list_estimates

List estimates (quotes).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | no | `draft`, `sent`, `accepted`, `declined`, `expired`, `invoiced`, `all` |
| `customer_id` | string | no | Filter by customer ID |
| `date_start` | string | no | Start date (ISO 8601) |
| `date_end` | string | no | End date (ISO 8601) |
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `search_text` | string | no | Search by estimate number or customer name |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_list_estimates({
  status = "accepted"
})

for _, est in ipairs(result.estimates) do
  print(est.estimate_number .. " — " .. est.total .. " (" .. est.status .. ")")
end
```

---

## create_estimate

Create a new estimate (quote).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `customer_id` | string | yes | Customer (contact) ID |
| `line_items` | array | yes | Array of line items (same format as create_invoice) |
| `date` | string | no | Estimate date (ISO 8601) |
| `expiry_date` | string | no | Expiry date (ISO 8601) |
| `estimate_number` | string | no | Custom estimate number |
| `reference_number` | string | no | Reference number |
| `notes` | string | no | Notes on the estimate |
| `terms` | string | no | Terms and conditions |

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_create_estimate({
  customer_id = "4815000000044001",
  line_items = {
    {
      name = "Website Development",
      rate = 5000.00,
      quantity = 1,
      description = "Complete website build"
    }
  },
  date = "2025-06-01",
  expiry_date = "2025-07-01",
  notes = "Valid for 30 days"
})

print("Created estimate: " .. result.estimate.estimate_number)
```

---

## get_current_user

Get the currently authenticated Zoho Books user.

### Parameters

None.

### Example

```lua
local result = app.integrations["zoho-books"].zohobooks_get_current_user({})

print("Logged in as: " .. (result.users and result.users[1] and result.users[1].name or "Unknown"))
```

---

## Multi-Account Usage

If you have multiple Zoho Books accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations["zoho-books"].zohobooks_function_name({...})

-- Explicit default (portable across setups)
app.integrations["zoho-books"].default.zohobooks_function_name({...})

-- Named accounts
app.integrations["zoho-books"].production.zohobooks_function_name({...})
app.integrations["zoho-books"].sandbox.zohobooks_function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.zoho_books.list_invoices({status = "example_status", customer_id = "example_customer_id", date_start = "example_date_start", date_end = "example_date_end", page = 1, per_page = 1, search_text = "example_search_text"})
print(result)

Functions

list_invoices Read

List invoices from Zoho Books. Returns a paginated list of invoices with optional filters for status, customer, and date range.

Lua path
app.integrations.zoho_books.list_invoices
Full name
zoho-books.zohobooks_list_invoices
ParameterTypeRequiredDescription
status string no Filter by invoice status: draft, sent, overdue, paid, voided, unpaid.
customer_id string no Filter invoices by customer ID.
date_start string no Filter by start date (ISO 8601, e.g., "2025-01-01").
date_end string no Filter by end date (ISO 8601, e.g., "2025-12-31").
page integer no Page number for pagination (default: 1).
per_page integer no Number of invoices per page (default: 25, max: 200).
search_text string no Search invoices by invoice number or customer name.
get_invoice Read

Get full details of a specific invoice in Zoho Books by its ID, including line items, totals, payments, and credits.

Lua path
app.integrations.zoho_books.get_invoice
Full name
zoho-books.zohobooks_get_invoice
ParameterTypeRequiredDescription
invoice_id string yes The unique ID of the invoice to retrieve.
create_invoice Write

Create a new invoice in Zoho Books. Requires a customer_id and line_items array. Each line item needs at least an item_id or name with a rate and quantity.

Lua path
app.integrations.zoho_books.create_invoice
Full name
zoho-books.zohobooks_create_invoice
ParameterTypeRequiredDescription
customer_id string yes The customer (contact) ID to invoice.
line_items array yes Array of line items. Each item should have: item_id (or name), rate, quantity, and optionally description.
date string no Invoice date (ISO 8601, e.g., "2025-01-15"). Defaults to today.
due_date string no Due date for payment (ISO 8601).
invoice_number string no Custom invoice number. Auto-generated if omitted.
reference_number string no Reference number (e.g., PO number).
notes string no Notes to display on the invoice.
terms string no Terms and conditions.
update_invoice Write

Update an existing invoice in Zoho Books. Provide the invoice_id and any fields to change (line_items, dates, notes, status, etc.).

Lua path
app.integrations.zoho_books.update_invoice
Full name
zoho-books.zohobooks_update_invoice
ParameterTypeRequiredDescription
invoice_id string yes The unique ID of the invoice to update.
customer_id string no Change the customer (contact) ID on the invoice.
line_items array no Replace all line items. Each item should have: item_id (or name), rate, quantity.
date string no Invoice date (ISO 8601).
due_date string no Due date for payment (ISO 8601).
notes string no Notes displayed on the invoice.
terms string no Terms and conditions.
status string no Update invoice status: draft, sent, voided.
reference_number string no Reference number (e.g., PO number).
list_contacts Read

List contacts (customers and vendors) from Zoho Books. Returns a paginated list with optional filters.

Lua path
app.integrations.zoho_books.list_contacts
Full name
zoho-books.zohobooks_list_contacts
ParameterTypeRequiredDescription
contact_type string no Filter by type: customer, vendor, or all (default: all).
status string no Filter by status: active, inactive, or all.
page integer no Page number for pagination (default: 1).
per_page integer no Number of contacts per page (default: 25, max: 200).
search_text string no Search contacts by name or email.
get_contact Read

Get full details of a specific contact (customer or vendor) in Zoho Books, including addresses and contact persons.

Lua path
app.integrations.zoho_books.get_contact
Full name
zoho-books.zohobooks_get_contact
ParameterTypeRequiredDescription
contact_id string yes The unique ID of the contact to retrieve.
create_contact Write

Create a new contact (customer or vendor) in Zoho Books. Requires a name; optionally provide email, phone, company name, and contact type.

Lua path
app.integrations.zoho_books.create_contact
Full name
zoho-books.zohobooks_create_contact
ParameterTypeRequiredDescription
name string yes Contact name (person or company).
email string no Primary email address.
phone string no Phone number.
company_name string no Company name (if different from contact name).
contact_type string no Contact type: customer, vendor (default: customer).
billing_address object no Billing address object with fields: attention, address, city, state, zip, country, phone.
shipping_address object no Shipping address object (same fields as billing_address).
notes string no Internal notes about this contact.
list_items Read

List items (products and services) from Zoho Books. Returns a paginated list with optional filters.

Lua path
app.integrations.zoho_books.list_items
Full name
zoho-books.zohobooks_list_items
ParameterTypeRequiredDescription
filter_type string no Filter by item type: active, inactive, sales, purchases, or all.
page integer no Page number for pagination (default: 1).
per_page integer no Number of items per page (default: 25, max: 200).
search_text string no Search items by name or description.
create_item Write

Create a new item (product or service) in Zoho Books. Requires a name and rate. Optionally specify item type, description, unit, and tax.

Lua path
app.integrations.zoho_books.create_item
Full name
zoho-books.zohobooks_create_item
ParameterTypeRequiredDescription
name string yes Item name (e.g., "Web Design Service" or "Widget A").
rate number yes Unit price or hourly rate.
description string no Item description shown on invoices.
unit string no Unit of measurement (e.g., "hrs", "pcs", "kg").
item_type string no Type of item: sales, purchases, or both (default: both).
tax_id string no Tax ID to apply to this item.
sku string no Stock Keeping Unit identifier.
list_estimates Read

List estimates (quotes) from Zoho Books. Returns a paginated list with optional filters for status, customer, and date range.

Lua path
app.integrations.zoho_books.list_estimates
Full name
zoho-books.zohobooks_list_estimates
ParameterTypeRequiredDescription
status string no Filter by estimate status: draft, sent, accepted, declined, expired, invoiced, or all.
customer_id string no Filter estimates by customer ID.
date_start string no Filter by start date (ISO 8601).
date_end string no Filter by end date (ISO 8601).
page integer no Page number for pagination (default: 1).
per_page integer no Number of estimates per page (default: 25, max: 200).
search_text string no Search estimates by estimate number or customer name.
create_estimate Write

Create a new estimate (quote) in Zoho Books. Requires a customer_id and line_items array. Each line item needs at least an item_id or name with a rate and quantity.

Lua path
app.integrations.zoho_books.create_estimate
Full name
zoho-books.zohobooks_create_estimate
ParameterTypeRequiredDescription
customer_id string yes The customer (contact) ID for the estimate.
line_items array yes Array of line items. Each item should have: item_id (or name), rate, quantity, and optionally description.
date string no Estimate date (ISO 8601, e.g., "2025-01-15"). Defaults to today.
expiry_date string no Date when the estimate expires (ISO 8601).
estimate_number string no Custom estimate number. Auto-generated if omitted.
reference_number string no Reference number.
notes string no Notes to display on the estimate.
terms string no Terms and conditions.
get_current_user Read

Get information about the currently authenticated Zoho Books user. Useful for verifying connectivity and identifying the active account.

Lua path
app.integrations.zoho_books.get_current_user
Full name
zoho-books.zohobooks_get_current_user
ParameterTypeRequiredDescription
No parameters.