KosmoKrator

payments

Zoho Bills Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Manual OAuth token auth
Submit Zoho Bills feedback View package source

Lua Namespace

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

Agent-Facing Lua Docs

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

Zoho Bills — Lua API Reference

list_invoices

List invoices from Zoho Bills with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
statusstringnoFilter by status: draft, sent, overdue, paid, voided, partially_paid
customer_idstringnoFilter by customer ID

Example

local result = app.integrations.zoho_bills.list_invoices({
  status = "overdue",
  per_page = 10
})

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

get_invoice

Retrieve a single invoice by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe invoice ID

Example

local result = app.integrations.zoho_bills.get_invoice({
  id = "inv_12345"
})

print("Invoice: " .. result.invoice.invoice_number)
print("Total: " .. result.invoice.total)
print("Status: " .. result.invoice.status)

create_invoice

Create a new invoice in Zoho Bills.

Parameters

NameTypeRequiredDescription
customer_idstringyesThe customer ID to bill
line_itemsarrayyesArray of line items (see below)
datestringnoInvoice date (YYYY-MM-DD), defaults to today
due_datestringnoDue date (YYYY-MM-DD)

Line Item Fields

FieldTypeDescription
item_idstringExisting item ID (preferred)
namestringItem name (if no item_id)
descriptionstringLine item description
quantitynumberQuantity (default: 1) still
ratenumberUnit price

Example

local result = app.integrations.zoho_bills.create_invoice({
  customer_id = "cnt_12345",
  line_items = {
    { item_id = "itm_001", quantity = 2, rate = 50.00 },
    { name = "Consulting", description = "Strategy session", quantity = 1, rate = 150.00 }
  },
  date = "2026-04-06",
  due_date = "2026-05-06"
})

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

list_customers

List customers (contacts) from Zoho Bills.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)
typestringnoFilter by type: customer, vendor

Example

local result = app.integrations.zoho_bills.list_customers({
  type = "customer",
  per_page = 50
})

for _, contact in ipairs(result.contacts) do
  print(contact.contact_id .. ": " .. contact.contact_name)
end

get_customer

Retrieve a single customer (contact) by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe contact ID

Example

local result = app.integrations.zoho_bills.get_customer({
  id = "cnt_12345"
})

print("Customer: " .. result.contact.contact_name)
print("Email: " .. result.contact.email)

list_items

List items (products and services) from Zoho Bills.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 25, max: 200)

Example

local result = app.integrations.zoho_bills.list_items({
  per_page = 100
})

for _, item in ipairs(result.items) do
  print(item.item_id .. ": " .. item.name .. " - " .. item.rate)
end

get_current_user

Get the currently authenticated Zoho Bills user profile.

Parameters

None.

Example

local result = app.integrations.zoho_bills.get_current_user({})

print("User: " .. result.user.name)
print("Email: " .. result.user.email)
print("Role: " .. result.user.role)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.zoho_bills.function_name({...})

-- Explicit default (portable across setups)
app.integrations.zoho_bills.default.function_name({...})

-- Named accounts
app.integrations.zoho_bills.production.function_name({...})
app.integrations.zoho_bills.sandbox.function_name({...})

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

Raw agent markdown 
# Zoho Bills — Lua API Reference

## list_invoices

List invoices from Zoho Bills with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `status` | string | no | Filter by status: `draft`, `sent`, `overdue`, `paid`, `voided`, `partially_paid` |
| `customer_id` | string | no | Filter by customer ID |

### Example

```lua
local result = app.integrations.zoho_bills.list_invoices({
  status = "overdue",
  per_page = 10
})

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

---

## get_invoice

Retrieve a single invoice by ID.

### Parameters

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

### Example

```lua
local result = app.integrations.zoho_bills.get_invoice({
  id = "inv_12345"
})

print("Invoice: " .. result.invoice.invoice_number)
print("Total: " .. result.invoice.total)
print("Status: " .. result.invoice.status)
```

---

## create_invoice

Create a new invoice in Zoho Bills.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `customer_id` | string | yes | The customer ID to bill |
| `line_items` | array | yes | Array of line items (see below) |
| `date` | string | no | Invoice date (YYYY-MM-DD), defaults to today |
| `due_date` | string | no | Due date (YYYY-MM-DD) |

### Line Item Fields

| Field | Type | Description |
|-------|------|-------------|
| `item_id` | string | Existing item ID (preferred) |
| `name` | string | Item name (if no item_id) |
| `description` | string | Line item description |
| `quantity` | number | Quantity (default: 1) still |
| `rate` | number | Unit price |

### Example

```lua
local result = app.integrations.zoho_bills.create_invoice({
  customer_id = "cnt_12345",
  line_items = {
    { item_id = "itm_001", quantity = 2, rate = 50.00 },
    { name = "Consulting", description = "Strategy session", quantity = 1, rate = 150.00 }
  },
  date = "2026-04-06",
  due_date = "2026-05-06"
})

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

---

## list_customers

List customers (contacts) from Zoho Bills.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |
| `type` | string | no | Filter by type: `customer`, `vendor` |

### Example

```lua
local result = app.integrations.zoho_bills.list_customers({
  type = "customer",
  per_page = 50
})

for _, contact in ipairs(result.contacts) do
  print(contact.contact_id .. ": " .. contact.contact_name)
end
```

---

## get_customer

Retrieve a single customer (contact) by ID.

### Parameters

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

### Example

```lua
local result = app.integrations.zoho_bills.get_customer({
  id = "cnt_12345"
})

print("Customer: " .. result.contact.contact_name)
print("Email: " .. result.contact.email)
```

---

## list_items

List items (products and services) from Zoho Bills.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 25, max: 200) |

### Example

```lua
local result = app.integrations.zoho_bills.list_items({
  per_page = 100
})

for _, item in ipairs(result.items) do
  print(item.item_id .. ": " .. item.name .. " - " .. item.rate)
end
```

---

## get_current_user

Get the currently authenticated Zoho Bills user profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.zoho_bills.get_current_user({})

print("User: " .. result.user.name)
print("Email: " .. result.user.email)
print("Role: " .. result.user.role)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.zoho_bills.function_name({...})

-- Explicit default (portable across setups)
app.integrations.zoho_bills.default.function_name({...})

-- Named accounts
app.integrations.zoho_bills.production.function_name({...})
app.integrations.zoho_bills.sandbox.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.zoho_bills.zoho_bills_list_invoices({
  page = 1,
  per_page = 1,
  status = "example_status",
  customer_id = "example_customer_id"
})
print(result)

Functions

zoho_bills_list_invoices

List invoices from Zoho Bills. Optionally filter by status (draft, sent, overdue, paid, voided, partially_paid) or customer ID.

Operation
Read read
Full name
zoho_bills.zoho_bills_list_invoices
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of invoices per page (default: 25, max: 200).
status string no Filter by invoice status: draft, sent, overdue, paid, voided, partially_paid.
customer_id string no Filter invoices by customer ID.

zoho_bills_get_invoice

Retrieve a single invoice from Zoho Bills by its ID. Returns full invoice details including line items, totals, and status.

Operation
Read read
Full name
zoho_bills.zoho_bills_get_invoice
ParameterTypeRequiredDescription
id string yes The invoice ID.

zoho_bills_create_invoice

Create a new invoice in Zoho Bills. Provide a customer ID, line items, and optional date/due date. Each line item should include item_id or a name, plus rate and quantity.

Operation
Write write
Full name
zoho_bills.zoho_bills_create_invoice
ParameterTypeRequiredDescription
customer_id string yes The customer ID to bill.
line_items array yes Array of line items. Each item should have item_id (or name/description), rate, and quantity. Example: [{"item_id": "...", "quantity": 2, "rate": 50.00}]
date string no Invoice date in YYYY-MM-DD format. Defaults to today.
due_date string no Due date in YYYY-MM-DD format.

zoho_bills_list_customers

List customers (contacts) from Zoho Bills. Optionally filter by type (customer or vendor). Returns paginated results.

Operation
Read read
Full name
zoho_bills.zoho_bills_list_customers
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of contacts per page (default: 25, max: 200).
type string no Filter by contact type: customer, vendor.

zoho_bills_get_customer

Retrieve a single customer (contact) from Zoho Bills by ID. Returns full contact details including billing address and contact persons.

Operation
Read read
Full name
zoho_bills.zoho_bills_get_customer
ParameterTypeRequiredDescription
id string yes The contact ID.

zoho_bills_list_items

List items (products and services) from Zoho Bills. Returns paginated results with item details like name, rate, and description.

Operation
Read read
Full name
zoho_bills.zoho_bills_list_items
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of items per page (default: 25, max: 200).

zoho_bills_get_current_user

Get the currently authenticated Zoho Bills user profile. Useful for verifying connectivity and checking user permissions.

Operation
Read read
Full name
zoho_bills.zoho_bills_get_current_user
ParameterTypeRequiredDescription
No parameters.