# Zoho Billing

> Subscription billing and invoicing. Manage customers, plans and subscriptions, charge one-time amounts, and record payments.

App · Payments & Billing · 20 actions. Web page: https://docs.lodol.com/docs/integrations/zoho-billing

## Actions

### Cancel a subscription

Cancel a subscription now, or at the end of its current term (it then stays live until then and can be reactivated).

**Inputs**

- Subscription ID (`subscription_id`, text, required): The subscription's id, from 'List subscriptions' or 'Create a subscription'.
- At the end of the term (`cancel_at_end`, true/false): Optional. On: it ends when the current term does (status non_renewing). Off: it is cancelled now.
- Reason (`reason`, text): Optional. Why, kept in the subscription's history.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing subscription.

- `activated_at` (text): The date it became live.
- `addons` (list): The add-ons on the subscription.
- `amount` (number): The amount billed each interval.
- `auto_collect` (true/false): Whether payments are collected from a saved card.
- `cancelled_at` (text): The date it was cancelled, if it was.
- `child_invoice_id` (text): The id of the invoice raised when it was created.
- `created_at` (text): The date it was created.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The currency, e.g. USD.
- `current_term_ends_at` (text): The date the current term ends.
- `current_term_starts_at` (text): The date the current term began.
- `custom_fields` (list): Custom field values.
- `customer` (object): The subscribed customer.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `email` (text): The customer's email.
- `end_of_term` (true/false): Whether it ends at the end of the current term.
- `expires_at` (text): The date it expires, if it does.
- `interval` (number): How many interval units between invoices.
- `interval_unit` (text): months or years.
- `name` (text): The subscription's name.
- `next_billing_at` (text): The date of the next invoice.
- `plan` (object): The subscribed plan.
- `plan_name` (text): The plan's name.
- `product_id` (text): The id of the plan's product.
- `product_name` (text): The plan's product's name.
- `reference_id` (text): Your own reference.
- `status` (text): live, trial, dunning, unpaid, non_renewing, cancelled, creation_failed, cancelled_from_dunning, expired, trial_expired or future.
- `subscription_id` (text): The subscription's id.
- `subscription_number` (text): The subscription's number, e.g. SUB-00001.
- `trial_ends_at` (text): The date its trial ends.
- `trial_starts_at` (text): The date its trial began.
- `updated_time` (text): When it was last changed.

**Example output**

```json
{
  "amount": 49,
  "auto_collect": false,
  "currency_code": "USD",
  "current_term_ends_at": "2026-10-31",
  "current_term_starts_at": "2026-10-01",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "interval": 1,
  "interval_unit": "months",
  "name": "Analytics Cloud-Basic",
  "next_billing_at": "2026-11-01",
  "plan_name": "Basic",
  "status": "cancelled",
  "subscription_id": "2263000000050017",
  "subscription_number": "SUB-00007"
}
```

### Charge a subscription

Bill a one-time amount against a subscription. Returns the invoice Zoho raises for it.

**Inputs**

- Subscription ID (`subscription_id`, text, required): The subscription's id, from 'List subscriptions' or 'Create a subscription'.
- Amount (`amount`, number, required): The amount to charge. At least 0.
- Description (`description`, text): Optional. What the charge is for, shown on the invoice.
- Add to the next invoice (`add_to_unbilled_charges`, true/false): Optional. On: hold the charge for the next renewal invoice instead of invoicing it now.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: The invoice raised for the charge. With 'Add to the next invoice' and no invoice raised, only subscription_id, status ('unbilled'), amount and message are returned.

- `amount` (number): The amount charged, when no invoice was raised.
- `balance` (number): The amount still unpaid.
- `billing_address` (object): A postal address.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `credits_applied` (number): Credits applied to it.
- `currency_code` (text): The currency, e.g. USD.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `due_date` (text): The due date, YYYY-MM-DD.
- `email` (text): The customer's email.
- `invoice_date` (text): The invoice date, YYYY-MM-DD.
- `invoice_id` (text): The invoice's id.
- `invoice_items` (list): The invoice's lines.
- `invoice_url` (text): The customer-facing link to the invoice.
- `message` (text): Zoho's message, when no invoice was raised.
- `number` (text): The invoice's number, e.g. INV-000042.
- `payment_made` (number): The amount paid so far.
- `payments` (list): Payments applied to it.
- `status` (text): draft, sent, overdue, partially_paid, paid or void.
- `subscription_id` (text): The subscription charged, when no invoice was raised.
- `total` (number): The invoice total.
- `updated_time` (text): When it was last changed.
- `write_off_amount` (number): The amount written off.

**Example output**

```json
{
  "balance": 15,
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "due_date": "2026-10-01",
  "invoice_date": "2026-10-01",
  "invoice_id": "2263000000051003",
  "number": "INV-000042",
  "status": "sent",
  "total": 15
}
```

### Create a customer

Create a customer who can then be subscribed to a plan.

**Inputs**

- Display name (`display_name`, text, required): The name shown for the customer, e.g. their company.
- Email (`email`, text, required): The customer's email address. Zoho sends invoices here.
- Salutation (`salutation`, text): Optional. Mr., Ms. and so on.
- First name (`first_name`, text): Optional. First name.
- Last name (`last_name`, text): Optional. Last name.
- Company name (`company_name`, text): Optional. Company name.
- Phone (`phone`, text): Optional. Phone number.
- Mobile (`mobile`, text): Optional. Mobile number.
- Website (`website`, text): Optional. Website.
- Department (`department`, text): Optional. Department.
- Job title (`designation`, text): Optional. Job title.
- Street (`street`, text): Optional. Billing address: street.
- City (`city`, text): Optional. Billing address: city.
- State (`state`, text): Optional. Billing address: state or region.
- ZIP / postal code (`zip_code`, text): Optional. Billing address: postal code.
- Country (`country`, text): Optional. Billing address: country.
- Payment terms (`payment_terms`, number): Optional. Days the customer has to pay an invoice, e.g. 15. At least 0.
- Payment terms label (`payment_terms_label`, text): Optional. The terms' name shown on invoices, e.g. Net 15.
- Currency (`currency_code`, text): Optional. The customer's currency as a three-letter code, such as USD. Defaults to the organization's currency.
- Notes (`notes`, text): Optional. Notes about the customer.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing customer.

- `billing_address` (object): A postal address.
- `company_name` (text): Company name.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The customer's currency, e.g. USD.
- `custom_fields` (list): Custom field values.
- `customer_id` (text): The customer's id.
- `department` (text): Department.
- `designation` (text): Job title.
- `display_name` (text): The name shown for the customer.
- `email` (text): Email address.
- `first_name` (text): First name.
- `last_name` (text): Last name.
- `mobile` (text): Mobile number.
- `notes` (text): Notes about the customer.
- `outstanding` (number): Amount the customer owes.
- `payment_terms_label` (text): The payment terms, e.g. Net 15.
- `phone` (text): Phone number.
- `salutation` (text): Mr., Ms. and so on.
- `shipping_address` (object): A postal address.
- `status` (text): active or inactive.
- `unused_credits` (number): Credits not yet applied.
- `updated_time` (text): When it was last changed.
- `website` (text): Website.

**Example output**

```json
{
  "company_name": "Bowman & Co",
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "display_name": "Bowman & Co",
  "email": "ada@bowman.example",
  "first_name": "Ada",
  "last_name": "Bowman",
  "outstanding": 0,
  "status": "active",
  "unused_credits": 0
}
```

### Create a plan

Create a recurring plan under a product.

**Inputs**

- Plan code (`plan_code`, text, required): A unique code for the plan, used to subscribe to it, e.g. basic-monthly. No spaces or slashes.
- Name (`name`, text, required): The plan's name.
- Price (`recurring_price`, number, required): The price charged every interval. At least 0.
- Product (`product_id`, text, required): The product the plan belongs to.
- Bill every (`interval`, number): Optional. How many months or years between invoices. Defaults to 1. At least 1.
- Interval unit (`interval_unit`, text): Optional. Months or years. Defaults to months. One of: `months`, `years`.
- Unit (`unit`, text): Optional. What one unit is called, e.g. user or seat.
- Billing cycles (`billing_cycles`, number): Optional. How many times to bill before the subscription expires. Leave blank or enter -1 to bill until cancelled. At least -1.
- Trial days (`trial_period`, number): Optional. Free trial length in days. At least 0.
- Setup fee (`setup_fee`, number): Optional. A one-time fee on the first invoice. At least 0.
- Description (`description`, text): Optional. What the plan includes.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing plan.

- `billing_cycles` (number): How many times it bills; -1 means until cancelled.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `description` (text): The plan's description.
- `interval` (number): How many interval units between charges.
- `interval_unit` (text): months or years.
- `name` (text): The plan's name.
- `plan_code` (text): The plan's unique code, used to subscribe to it.
- `product_id` (text): The id of the product it belongs to.
- `product_type` (text): goods or service.
- `recurring_price` (number): The price charged every interval.
- `setup_fee` (number): One-time setup fee.
- `status` (text): active or inactive.
- `tax_id` (text): The tax applied to it.
- `trial_period` (number): Free trial days.
- `unit` (text): What one unit is called, e.g. user.
- `updated_time` (text): When it was last changed.
- `url` (text): The plan's hosted subscription page.

**Example output**

```json
{
  "billing_cycles": -1,
  "interval": 1,
  "interval_unit": "months",
  "name": "Basic",
  "plan_code": "analytics-basic",
  "product_id": "2263000000040011",
  "recurring_price": 49,
  "status": "active"
}
```

### Create a product

Create a product to hold plans and add-ons.

**Inputs**

- Name (`name`, text, required): The product's name.
- Description (`description`, text): Optional. What the product is.
- Notification emails (`email_ids`, text): Optional. Comma-separated email addresses notified about this product's subscriptions.
- Redirect URL (`redirect_url`, text): Optional. Where customers go after subscribing on a hosted page, starting https://.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing product, which groups plans and add-ons.

- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `description` (text): The product's description.
- `email_ids` (text): Comma-separated addresses notified about its subscriptions.
- `name` (text): The product's name.
- `product_id` (text): The product's id.
- `redirect_url` (text): Where customers go after subscribing on a hosted page.
- `status` (text): active or inactive.
- `updated_time` (text): When it was last changed.

**Example output**

```json
{
  "description": "Hosted analytics",
  "name": "Analytics Cloud",
  "product_id": "2263000000040011",
  "status": "active"
}
```

### Create a subscription

Subscribe an existing customer to a plan. Zoho raises invoices that you record payments against; no card is charged.

**Inputs**

- Customer ID (`customer_id`, text, required): The customer's id, from 'List customers' or 'Create a customer'.
- Plan (`plan_code`, text, required): The plan, or its code from 'List plans'.
- Quantity (`quantity`, number): Optional. How many units of the plan. Defaults to 1. At least 1.
- Price (`price`, number): Optional. A price per unit instead of the plan's. At least 0.
- Plan description (`plan_description`, text): Optional. A description of the plan on this subscription's invoices.
- Billing cycles (`billing_cycles`, number): Optional. How many times to bill. Leave blank for the plan's setting, or -1 to bill until cancelled. At least -1.
- Trial days (`trial_days`, number): Optional. Trial length in days instead of the plan's. At least 0.
- Skip the trial (`exclude_trial`, true/false): Optional. Start billing at once, without the plan's trial.
- Skip the setup fee (`exclude_setup_fee`, true/false): Optional. Do not charge the plan's setup fee.
- Add-on (`addon_code`, text): Optional. An add-on to include.
- Add-on quantity (`addon_quantity`, number): Optional. How many of the add-on. Defaults to 1. At least 1.
- Add-on price (`addon_price`, number): Optional. A price per unit instead of the add-on's. At least 0.
- Start date (`starts_at`, date): Optional. When it starts. Defaults to today; a future date makes it a future subscription.
- Reference (`reference_id`, text): Optional. Your own reference for it.
- Coupon code (`coupon_code`, text): Optional. A coupon to apply.
- Payment terms (`payment_terms`, number): Optional. Days the customer has to pay an invoice, e.g. 15. At least 0.
- Payment terms label (`payment_terms_label`, text): Optional. The terms' name shown on invoices, e.g. Net 15.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing subscription.

- `activated_at` (text): The date it became live.
- `addons` (list): The add-ons on the subscription.
- `amount` (number): The amount billed each interval.
- `auto_collect` (true/false): Whether payments are collected from a saved card.
- `cancelled_at` (text): The date it was cancelled, if it was.
- `child_invoice_id` (text): The id of the invoice raised when it was created.
- `created_at` (text): The date it was created.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The currency, e.g. USD.
- `current_term_ends_at` (text): The date the current term ends.
- `current_term_starts_at` (text): The date the current term began.
- `custom_fields` (list): Custom field values.
- `customer` (object): The subscribed customer.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `email` (text): The customer's email.
- `end_of_term` (true/false): Whether it ends at the end of the current term.
- `expires_at` (text): The date it expires, if it does.
- `interval` (number): How many interval units between invoices.
- `interval_unit` (text): months or years.
- `name` (text): The subscription's name.
- `next_billing_at` (text): The date of the next invoice.
- `plan` (object): The subscribed plan.
- `plan_name` (text): The plan's name.
- `product_id` (text): The id of the plan's product.
- `product_name` (text): The plan's product's name.
- `reference_id` (text): Your own reference.
- `status` (text): live, trial, dunning, unpaid, non_renewing, cancelled, creation_failed, cancelled_from_dunning, expired, trial_expired or future.
- `subscription_id` (text): The subscription's id.
- `subscription_number` (text): The subscription's number, e.g. SUB-00001.
- `trial_ends_at` (text): The date its trial ends.
- `trial_starts_at` (text): The date its trial began.
- `updated_time` (text): When it was last changed.

**Example output**

```json
{
  "amount": 49,
  "auto_collect": false,
  "currency_code": "USD",
  "current_term_ends_at": "2026-10-31",
  "current_term_starts_at": "2026-10-01",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "interval": 1,
  "interval_unit": "months",
  "name": "Analytics Cloud-Basic",
  "next_billing_at": "2026-11-01",
  "plan_name": "Basic",
  "status": "live",
  "subscription_id": "2263000000050017",
  "subscription_number": "SUB-00007"
}
```

### Get a customer

Get a customer's details, address and outstanding balance.

**Inputs**

- Customer ID (`customer_id`, text, required): The customer's id, from 'List customers' or 'Create a customer'.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing customer.

- `billing_address` (object): A postal address.
- `company_name` (text): Company name.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The customer's currency, e.g. USD.
- `custom_fields` (list): Custom field values.
- `customer_id` (text): The customer's id.
- `department` (text): Department.
- `designation` (text): Job title.
- `display_name` (text): The name shown for the customer.
- `email` (text): Email address.
- `first_name` (text): First name.
- `last_name` (text): Last name.
- `mobile` (text): Mobile number.
- `notes` (text): Notes about the customer.
- `outstanding` (number): Amount the customer owes.
- `payment_terms_label` (text): The payment terms, e.g. Net 15.
- `phone` (text): Phone number.
- `salutation` (text): Mr., Ms. and so on.
- `shipping_address` (object): A postal address.
- `status` (text): active or inactive.
- `unused_credits` (number): Credits not yet applied.
- `updated_time` (text): When it was last changed.
- `website` (text): Website.

**Example output**

```json
{
  "company_name": "Bowman & Co",
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "display_name": "Bowman & Co",
  "email": "ada@bowman.example",
  "first_name": "Ada",
  "last_name": "Bowman",
  "outstanding": 0,
  "status": "active",
  "unused_credits": 0
}
```

### Get a plan

Get a plan's price, interval, trial and setup fee.

**Inputs**

- Plan (`plan_code`, text, required): The plan, or its code from 'List plans'.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing plan.

- `billing_cycles` (number): How many times it bills; -1 means until cancelled.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `description` (text): The plan's description.
- `interval` (number): How many interval units between charges.
- `interval_unit` (text): months or years.
- `name` (text): The plan's name.
- `plan_code` (text): The plan's unique code, used to subscribe to it.
- `product_id` (text): The id of the product it belongs to.
- `product_type` (text): goods or service.
- `recurring_price` (number): The price charged every interval.
- `setup_fee` (number): One-time setup fee.
- `status` (text): active or inactive.
- `tax_id` (text): The tax applied to it.
- `trial_period` (number): Free trial days.
- `unit` (text): What one unit is called, e.g. user.
- `updated_time` (text): When it was last changed.
- `url` (text): The plan's hosted subscription page.

**Example output**

```json
{
  "billing_cycles": -1,
  "interval": 1,
  "interval_unit": "months",
  "name": "Basic",
  "plan_code": "analytics-basic",
  "product_id": "2263000000040011",
  "recurring_price": 49,
  "status": "active"
}
```

### Get a subscription

Get a subscription's status, plan, add-ons and billing dates.

**Inputs**

- Subscription ID (`subscription_id`, text, required): The subscription's id, from 'List subscriptions' or 'Create a subscription'.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing subscription.

- `activated_at` (text): The date it became live.
- `addons` (list): The add-ons on the subscription.
- `amount` (number): The amount billed each interval.
- `auto_collect` (true/false): Whether payments are collected from a saved card.
- `cancelled_at` (text): The date it was cancelled, if it was.
- `child_invoice_id` (text): The id of the invoice raised when it was created.
- `created_at` (text): The date it was created.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The currency, e.g. USD.
- `current_term_ends_at` (text): The date the current term ends.
- `current_term_starts_at` (text): The date the current term began.
- `custom_fields` (list): Custom field values.
- `customer` (object): The subscribed customer.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `email` (text): The customer's email.
- `end_of_term` (true/false): Whether it ends at the end of the current term.
- `expires_at` (text): The date it expires, if it does.
- `interval` (number): How many interval units between invoices.
- `interval_unit` (text): months or years.
- `name` (text): The subscription's name.
- `next_billing_at` (text): The date of the next invoice.
- `plan` (object): The subscribed plan.
- `plan_name` (text): The plan's name.
- `product_id` (text): The id of the plan's product.
- `product_name` (text): The plan's product's name.
- `reference_id` (text): Your own reference.
- `status` (text): live, trial, dunning, unpaid, non_renewing, cancelled, creation_failed, cancelled_from_dunning, expired, trial_expired or future.
- `subscription_id` (text): The subscription's id.
- `subscription_number` (text): The subscription's number, e.g. SUB-00001.
- `trial_ends_at` (text): The date its trial ends.
- `trial_starts_at` (text): The date its trial began.
- `updated_time` (text): When it was last changed.

**Example output**

```json
{
  "amount": 49,
  "auto_collect": false,
  "currency_code": "USD",
  "current_term_ends_at": "2026-10-31",
  "current_term_starts_at": "2026-10-01",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "interval": 1,
  "interval_unit": "months",
  "name": "Analytics Cloud-Basic",
  "next_billing_at": "2026-11-01",
  "plan_name": "Basic",
  "status": "live",
  "subscription_id": "2263000000050017",
  "subscription_number": "SUB-00007"
}
```

### Get an invoice

Get an invoice's lines, total, balance and payments.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's id, from 'List invoices'.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing invoice.

- `balance` (number): The amount still unpaid.
- `billing_address` (object): A postal address.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `credits_applied` (number): Credits applied to it.
- `currency_code` (text): The currency, e.g. USD.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `due_date` (text): The due date, YYYY-MM-DD.
- `email` (text): The customer's email.
- `invoice_date` (text): The invoice date, YYYY-MM-DD.
- `invoice_id` (text): The invoice's id.
- `invoice_items` (list): The invoice's lines.
- `invoice_url` (text): The customer-facing link to the invoice.
- `number` (text): The invoice's number, e.g. INV-000042.
- `payment_made` (number): The amount paid so far.
- `payments` (list): Payments applied to it.
- `status` (text): draft, sent, overdue, partially_paid, paid or void.
- `total` (number): The invoice total.
- `updated_time` (text): When it was last changed.
- `write_off_amount` (number): The amount written off.

**Example output**

```json
{
  "balance": 49,
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "due_date": "2026-10-01",
  "invoice_date": "2026-10-01",
  "invoice_id": "2263000000051003",
  "number": "INV-000042",
  "status": "sent",
  "total": 49
}
```

### List add-ons

List add-ons that can be added to subscriptions.

**Inputs**

- Show (`filter_by`, text): Optional. Which add-ons to include. One of: `AddonStatus.All` (All), `AddonStatus.ACTIVE` (Active), `AddonStatus.INACTIVE` (Inactive), `AddonStatus.ONETIME` (One-time), `AddonStatus.RECURRING` (Recurring).
- Product (`product_id`, text): Optional. Only those of this product.
- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `addons` (list): The add-ons.
- `count` (number): How many add-ons are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.

**Example output**

```json
{
  "addons": [
    {
      "addon_code": "extra-seat",
      "name": "Extra seat",
      "pricing_scheme": "unit",
      "product_id": "2263000000040011",
      "status": "active",
      "type": "recurring"
    }
  ],
  "count": 1,
  "has_more_page": false,
  "page": 1,
  "per_page": 200
}
```

### List customers

List customers, optionally only active, inactive or those without a subscription.

**Inputs**

- Show (`filter_by`, text): Optional. Which customers to include. One of: `Status.All` (All), `Status.Active` (Active), `Status.Inactive` (Inactive), `Status.NonSubscribers` (Without a subscription).
- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many customers are on this page.
- `customers` (list): The customers.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.

**Example output**

```json
{
  "count": 1,
  "customers": [
    {
      "company_name": "Bowman & Co",
      "currency_code": "USD",
      "customer_id": "2263000000044208",
      "display_name": "Bowman & Co",
      "email": "ada@bowman.example",
      "first_name": "Ada",
      "last_name": "Bowman",
      "outstanding": 0,
      "status": "active",
      "unused_credits": 0
    }
  ],
  "has_more_page": false,
  "page": 1,
  "per_page": 200
}
```

### List invoices

List invoices, optionally by status or customer.

**Inputs**

- Show (`filter_by`, text): Optional. Which invoices to include. One of: `Status.All` (All), `Status.Sent` (Sent), `Status.Draft` (Draft), `Status.OverDue` (Overdue), `Status.Paid` (Paid), `Status.Void` (Void), `Status.Unpaid` (Unpaid), `Status.PartiallyPaid` (Partially paid).
- Customer ID (`customer_id`, text): Optional. Only this customer's invoices, picked out of the page Zoho returns.
- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many invoices are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `invoices` (list): The invoices.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.

**Example output**

```json
{
  "count": 1,
  "has_more_page": false,
  "invoices": [
    {
      "balance": 49,
      "currency_code": "USD",
      "customer_id": "2263000000044208",
      "customer_name": "Bowman & Co",
      "due_date": "2026-10-01",
      "invoice_date": "2026-10-01",
      "invoice_id": "2263000000051003",
      "number": "INV-000042",
      "status": "sent",
      "total": 49
    }
  ],
  "page": 1,
  "per_page": 200
}
```

### List payments

List payments received, optionally online or offline only.

**Inputs**

- Show (`filter_by`, text): Optional. Which payments to include. One of: `PaymentStatus.All` (All), `PaymentStatus.Incomplete` (Incomplete), `PaymentStatus.Resolved` (Resolved), `PaymentStatus.OnlineFailure` (Online, failed), `PaymentStatus.OnlineSuccess` (Online, succeeded), `PaymentType.Online` (Online), `PaymentType.Offline` (Offline).
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many payments are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `payments` (list): The payments.
- `per_page` (number): The page size, when Zoho reports it.

**Example output**

```json
{
  "count": 1,
  "has_more_page": false,
  "page": 1,
  "payments": [
    {
      "amount": 49,
      "currency_code": "USD",
      "customer_id": "2263000000044208",
      "customer_name": "Bowman & Co",
      "date": "2026-10-01",
      "invoices": [
        {
          "amount_applied": 49,
          "invoice_id": "2263000000051003"
        }
      ],
      "mode": "cash",
      "payment_id": "2263000000052009",
      "payment_mode": "cash",
      "status": "success"
    }
  ],
  "per_page": 200
}
```

### List plans

List plans with their price and billing interval.

**Inputs**

- Show (`filter_by`, text): Optional. Which plans to include. One of: `PlanStatus.All` (All), `PlanStatus.ACTIVE` (Active), `PlanStatus.INACTIVE` (Inactive).
- Product (`product_id`, text): Optional. Only those of this product.
- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many plans are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.
- `plans` (list): The plans.

**Example output**

```json
{
  "count": 1,
  "has_more_page": false,
  "page": 1,
  "per_page": 200,
  "plans": [
    {
      "billing_cycles": -1,
      "interval": 1,
      "interval_unit": "months",
      "name": "Basic",
      "plan_code": "analytics-basic",
      "product_id": "2263000000040011",
      "recurring_price": 49,
      "status": "active"
    }
  ]
}
```

### List products

List the products that group your plans and add-ons.

**Inputs**

- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many products are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.
- `products` (list): The products.

**Example output**

```json
{
  "count": 1,
  "has_more_page": false,
  "page": 1,
  "per_page": 200,
  "products": [
    {
      "description": "Hosted analytics",
      "name": "Analytics Cloud",
      "product_id": "2263000000040011",
      "status": "active"
    }
  ]
}
```

### List subscriptions

List subscriptions, optionally by status, customer or reference.

**Inputs**

- Show (`filter_by`, text): Optional. Which subscriptions to include. One of: `SubscriptionStatus.All` (All), `SubscriptionStatus.ACTIVE` (Active), `SubscriptionStatus.LIVE` (Live), `SubscriptionStatus.FUTURE` (Future), `SubscriptionStatus.TRIAL` (Trial), `SubscriptionStatus.PAST_DUE` (Past due), `SubscriptionStatus.UNPAID` (Unpaid), `SubscriptionStatus.NON_RENEWING` (Non-renewing), `SubscriptionStatus.CANCELLED_FROM_DUNNING` (Cancelled from dunning), `SubscriptionStatus.CANCELLED` (Cancelled), and 6 more.
- Customer ID (`customer_id`, text): Optional. Only this customer's subscriptions.
- Reference contains (`reference_contains`, text): Optional. Only subscriptions whose reference contains this text.
- Page (`page`, number): Optional. Which page of results to return, starting at 1. At least 1.
- Page size (`per_page`, number): Optional. How many to return per page, 1 to 200. Zoho's default is 200. From 1 to 200.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**

- `count` (number): How many subscriptions are on this page.
- `has_more_page` (true/false): Whether another page is available.
- `page` (number): This page's number, when Zoho reports it.
- `per_page` (number): The page size, when Zoho reports it.
- `subscriptions` (list): The subscriptions.

**Example output**

```json
{
  "count": 1,
  "has_more_page": false,
  "page": 1,
  "per_page": 200,
  "subscriptions": [
    {
      "amount": 49,
      "auto_collect": false,
      "currency_code": "USD",
      "current_term_ends_at": "2026-10-31",
      "current_term_starts_at": "2026-10-01",
      "customer_id": "2263000000044208",
      "customer_name": "Bowman & Co",
      "interval": 1,
      "interval_unit": "months",
      "name": "Analytics Cloud-Basic",
      "next_billing_at": "2026-11-01",
      "plan_name": "Basic",
      "status": "live",
      "subscription_id": "2263000000050017",
      "subscription_number": "SUB-00007"
    }
  ]
}
```

### Reactivate a subscription

Keep renewing a subscription that was set to cancel at the end of its term (status non_renewing).

**Inputs**

- Subscription ID (`subscription_id`, text, required): The subscription's id, from 'List subscriptions' or 'Create a subscription'.
- Billing cycles (`billing_cycle`, number): Optional. How many more times to bill. Leave blank or enter -1 to bill until cancelled. At least -1.
- Reason (`reason`, text): Optional. Why, kept in the subscription's history.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing subscription.

- `activated_at` (text): The date it became live.
- `addons` (list): The add-ons on the subscription.
- `amount` (number): The amount billed each interval.
- `auto_collect` (true/false): Whether payments are collected from a saved card.
- `cancelled_at` (text): The date it was cancelled, if it was.
- `child_invoice_id` (text): The id of the invoice raised when it was created.
- `created_at` (text): The date it was created.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The currency, e.g. USD.
- `current_term_ends_at` (text): The date the current term ends.
- `current_term_starts_at` (text): The date the current term began.
- `custom_fields` (list): Custom field values.
- `customer` (object): The subscribed customer.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `email` (text): The customer's email.
- `end_of_term` (true/false): Whether it ends at the end of the current term.
- `expires_at` (text): The date it expires, if it does.
- `interval` (number): How many interval units between invoices.
- `interval_unit` (text): months or years.
- `name` (text): The subscription's name.
- `next_billing_at` (text): The date of the next invoice.
- `plan` (object): The subscribed plan.
- `plan_name` (text): The plan's name.
- `product_id` (text): The id of the plan's product.
- `product_name` (text): The plan's product's name.
- `reference_id` (text): Your own reference.
- `status` (text): live, trial, dunning, unpaid, non_renewing, cancelled, creation_failed, cancelled_from_dunning, expired, trial_expired or future.
- `subscription_id` (text): The subscription's id.
- `subscription_number` (text): The subscription's number, e.g. SUB-00001.
- `trial_ends_at` (text): The date its trial ends.
- `trial_starts_at` (text): The date its trial began.
- `updated_time` (text): When it was last changed.

**Example output**

```json
{
  "amount": 49,
  "auto_collect": false,
  "currency_code": "USD",
  "current_term_ends_at": "2026-10-31",
  "current_term_starts_at": "2026-10-01",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "interval": 1,
  "interval_unit": "months",
  "name": "Analytics Cloud-Basic",
  "next_billing_at": "2026-11-01",
  "plan_name": "Basic",
  "status": "live",
  "subscription_id": "2263000000050017",
  "subscription_number": "SUB-00007"
}
```

### Record a payment

Record a payment received outside Zoho, such as cash or a bank transfer, and apply it to an invoice.

**Inputs**

- Customer ID (`customer_id`, text, required): The customer's id, from 'List customers' or 'Create a customer'.
- Paid by (`payment_mode`, text, required): How the customer paid. One of: `cash`, `check`, `creditcard` (Credit card), `banktransfer` (Bank transfer), `bankremittance` (Bank remittance), `others` (Other).
- Amount (`amount`, number, required): The amount received. At least 0.
- Invoice ID (`invoice_id`, text): Optional. The invoice it pays, from 'List invoices'. Without one the payment is kept as customer credit.
- Amount applied to the invoice (`amount_applied`, number): Optional. Defaults to the whole amount. At least 0.
- Date (`date`, date): Optional. When it was received. Defaults to today.
- Reference number (`reference_number`, text): Optional. Your reference, e.g. a cheque number.
- Description (`description`, text): Optional. A note about the payment.
- Bank charges (`bank_charges`, number): Optional. Fees the bank deducted. At least 0.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing payment.

- `amount` (number): The amount paid.
- `amount_refunded` (number): The amount refunded.
- `bank_charges` (number): Bank charges deducted.
- `currency_code` (text): The currency, e.g. USD.
- `customer_id` (text): The customer's id.
- `customer_name` (text): The customer's name.
- `date` (text): The payment date, YYYY-MM-DD.
- `description` (text): A note about the payment.
- `email` (text): The customer's email.
- `invoices` (list): The invoices it was applied to.
- `payment_id` (text): The payment's id.
- `payment_mode` (text): cash, check, creditcard, banktransfer, bankremittance or others.
- `reference_number` (text): Your reference.
- `status` (text): The payment's status.

**Example output**

```json
{
  "amount": 49,
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "customer_name": "Bowman & Co",
  "date": "2026-10-01",
  "invoices": [
    {
      "amount_applied": 49,
      "invoice_id": "2263000000051003"
    }
  ],
  "payment_id": "2263000000052009",
  "payment_mode": "cash",
  "status": "success"
}
```

### Update a customer

Change a customer's name, email, contact details or billing address. Blank fields keep their current value.

**Inputs**

- Customer ID (`customer_id`, text, required): The customer's id, from 'List customers' or 'Create a customer'.
- Display name (`display_name`, text): Optional. A new display name.
- Email (`email`, text): Optional. A new email address.
- Salutation (`salutation`, text): Optional. Mr., Ms. and so on.
- First name (`first_name`, text): Optional. First name.
- Last name (`last_name`, text): Optional. Last name.
- Company name (`company_name`, text): Optional. Company name.
- Phone (`phone`, text): Optional. Phone number.
- Mobile (`mobile`, text): Optional. Mobile number.
- Street (`street`, text): Optional. Billing address: street.
- City (`city`, text): Optional. Billing address: city.
- State (`state`, text): Optional. Billing address: state or region.
- ZIP / postal code (`zip_code`, text): Optional. Billing address: postal code.
- Country (`country`, text): Optional. Billing address: country.
- Currency (`currency_code`, text): Optional. The customer's currency as a three-letter code, such as USD. Defaults to the organization's currency.
- Organization (`organization_id`, text): The Zoho Billing organization to use. Required when your Zoho sign-in reaches several organizations (each Zoho app's are listed, and only those using Billing work); optional when it reaches one.

**Outputs**: A Zoho Billing customer.

- `billing_address` (object): A postal address.
- `company_name` (text): Company name.
- `created_time` (text): When it was created, e.g. 2026-09-01T10:15:00-0700.
- `currency_code` (text): The customer's currency, e.g. USD.
- `custom_fields` (list): Custom field values.
- `customer_id` (text): The customer's id.
- `department` (text): Department.
- `designation` (text): Job title.
- `display_name` (text): The name shown for the customer.
- `email` (text): Email address.
- `first_name` (text): First name.
- `last_name` (text): Last name.
- `mobile` (text): Mobile number.
- `notes` (text): Notes about the customer.
- `outstanding` (number): Amount the customer owes.
- `payment_terms_label` (text): The payment terms, e.g. Net 15.
- `phone` (text): Phone number.
- `salutation` (text): Mr., Ms. and so on.
- `shipping_address` (object): A postal address.
- `status` (text): active or inactive.
- `unused_credits` (number): Credits not yet applied.
- `updated_time` (text): When it was last changed.
- `website` (text): Website.

**Example output**

```json
{
  "company_name": "Bowman & Co",
  "currency_code": "USD",
  "customer_id": "2263000000044208",
  "display_name": "Bowman & Co",
  "email": "ada@bowman.example",
  "first_name": "Ada",
  "last_name": "Bowman",
  "outstanding": 0,
  "status": "active",
  "unused_credits": 0
}
```