> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Chargebee

The Chargebee connector lets your AI agent act in each user's Chargebee account. Each user connects their own Chargebee API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 27 tools.

**Authentication:** API Key
**Categories:** Accounting & Finance, CRM & Sales
**Tools:** 27: 15 read, 10 write, 2 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=CHARGEBEE)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Chargebee connection

   In **AgentKit > Connections**, create a Chargebee connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'chargebee_coupon_get',
  toolInput: {
    coupon_id: '<coupon_id>',
  },
  connector: 'chargebee',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="chargebee_coupon_get",
    tool_input={
        "coupon_id": "<coupon_id>",
    },
    connection_name="chargebee",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `chargebee_coupon_get`

Get Coupon · Read-only

Get one Chargebee coupon by ID.
Returns the coupon with discount, duration, validity dates, redemption limits and the item constraints it applies to.
Use chargebee_coupon_get when you have the coupon ID. Use chargebee_coupons_list to browse coupons.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `coupon_id` (`string`, required): ID of the coupon, from chargebee_coupons_list. Example: SUMMER20.

Example input: `{"coupon_id":"<coupon_id>"}`

### `chargebee_coupons_list`

List Coupons · Read-only

List coupons in Chargebee, optionally filtered by status, discount type, duration type, name or creation time.
Returns a list of coupon objects (id, name, discount_type, discount_percentage or discount_amount, duration_type, status, redemptions) and next_offset when more pages exist.
Use chargebee_coupons_list to find a coupon to apply. Use chargebee_coupon_get when you already have the coupon ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_after` (`integer`, optional): Only coupons created after this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `discount_type` (`string`, optional): Only coupons with this discount type. Example: percentage. One of: `fixed_amount`, `percentage`, `offer_quantity`.
- `duration_type` (`string`, optional): Only coupons with this duration type. Example: forever. One of: `one_time`, `forever`, `limited_period`.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `name_starts_with` (`string`, optional): Only coupons whose name starts with this text. Example: Summer.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Example: created_at. One of: `created_at`.
- `status` (`string`, optional): Only coupons in this status. Example: active. One of: `active`, `expired`, `archived`, `deleted`, `future`.

Example input: `{}`

### `chargebee_credit_note_get`

Get Credit Note · Read-only

Get one Chargebee credit note by ID.
Returns the credit note with line items, taxes, allocations to invoices and refunds.
Use chargebee_credit_note_get when you have the credit note ID. Use chargebee_credit_notes_list to search.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `credit_note_id` (`string`, required): ID of the credit note, from chargebee_credit_notes_list. Example: CN-112.

Example input: `{"credit_note_id":"<credit_note_id>"}`

### `chargebee_credit_notes_list`

List Credit Notes · Read-only

List credit notes in Chargebee, optionally filtered by customer, subscription, reference invoice, status, type or date.
Returns a list of credit note objects (id, type, status, reference_invoice_id, total, amount_allocated, amount_refunded, amount_available) and next_offset when more pages exist.
Use chargebee_credit_notes_list to find credits or refunds. Use chargebee_credit_note_get when you already have the credit note ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, optional): Only credit notes of this customer ID. Example: 16BjfNSzYXqA21Dt.
- `date_after` (`integer`, optional): Only credit notes dated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `date_before` (`integer`, optional): Only credit notes dated before this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `include_deleted` (`boolean`, optional): Set to true to also return deleted credit notes. Defaults to false.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `reference_invoice_id` (`string`, optional): Only credit notes issued against this invoice ID. Example: 1024.
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: date. One of: `date`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: date. One of: `date`.
- `status` (`string`, optional): Only credit notes in this status. Example: refund_due. One of: `adjusted`, `refunded`, `refund_due`, `voided`.
- `subscription_id` (`string`, optional): Only credit notes of this subscription ID. Example: AzZTZgTSz7nCt3Pu.
- `type` (`string`, optional): Only credit notes of this type. Example: refundable. One of: `adjustment`, `refundable`, `store`.

Example input: `{}`

### `chargebee_customer_get`

Get Customer · Read-only

Get one Chargebee customer by ID.
Returns the customer object (contact details, billing address, payment method summary, balances, meta_data) and its primary card if any.
Use chargebee_customer_get when you have the customer ID. Use chargebee_customers_list to search by email or name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): ID of the customer, from chargebee_customers_list or the Chargebee app. Example: 16BjfNSzYXqA21Dt.

Example input: `{"customer_id":"<customer_id>"}`

### `chargebee_customers_list`

List Customers · Read-only

List customers in Chargebee, optionally filtered by email, name, company or created/updated time.
Returns a list of customer objects (id, name, email, company, billing address, auto_collection, balances) and next_offset when more pages exist.
Use chargebee_customers_list to find a customer or browse. Use chargebee_customer_get when you already have the customer ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `company` (`string`, optional): Only customers with exactly this company name. Example: Acme Inc.
- `created_after` (`integer`, optional): Only customers created after this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `created_before` (`integer`, optional): Only customers created before this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `email` (`string`, optional): Only customers with exactly this email address. Example: jane@acme.com.
- `first_name` (`string`, optional): Only customers with exactly this first name. Example: Jane.
- `include_deleted` (`boolean`, optional): Set to true to also return deleted customers. Defaults to false.
- `last_name` (`string`, optional): Only customers with exactly this last name. Example: Doe.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: created_at. One of: `created_at`, `updated_at`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: created_at. One of: `created_at`, `updated_at`.
- `updated_after` (`integer`, optional): Only customers updated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{}`

### `chargebee_invoice_get`

Get Invoice · Read-only

Get one Chargebee invoice by ID.
Returns the invoice with line items, discounts, taxes, applied payments and credits, and amounts paid and due.
Use chargebee_invoice_get when you have the invoice ID. Use chargebee_invoices_list to search, and chargebee_invoice_pdf_get for a PDF link.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `invoice_id` (`string`, required): ID (number) of the invoice, from chargebee_invoices_list. Example: 1024.

Example input: `{"invoice_id":"<invoice_id>"}`

### `chargebee_invoice_pdf_get`

Get Invoice PDF Link · Read-only

Get a temporary download link for an invoice's PDF.
Returns a download object with download_url and valid_till (the link expires after about an hour).
Use chargebee_invoice_pdf_get to share or save an invoice document. Use chargebee_invoice_get for the invoice data.

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): ID (number) of the invoice, from chargebee_invoices_list. Example: 1024.
- `disposition_type` (`string`, optional): attachment (default) makes the link download the file; inline opens it in the browser. Example: inline. One of: `attachment`, `inline`.

Example input: `{"invoice_id":"<invoice_id>"}`

### `chargebee_invoices_list`

List Invoices · Read-only

List invoices in Chargebee, optionally filtered by customer, subscription, status, date or amount due.
Returns a list of invoice objects (id, status, date, total, amount_paid, amount_due, line_items) and next_offset when more pages exist.
Use chargebee_invoices_list to find unpaid or recent invoices. Use chargebee_invoice_get when you already have the invoice ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount_due_greater_than` (`integer`, optional): Only invoices with amount_due greater than this amount, in the currency's smallest unit (e.g. cents). Example: 0.
- `customer_id` (`string`, optional): Only invoices of this customer ID. Example: 16BjfNSzYXqA21Dt.
- `date_after` (`integer`, optional): Only invoices dated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `date_before` (`integer`, optional): Only invoices dated before this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `include_deleted` (`boolean`, optional): Set to true to also return deleted invoices. Defaults to false.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: date. One of: `date`, `updated_at`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: date. One of: `date`, `updated_at`.
- `status` (`string`, optional): Only invoices in this status. Example: payment_due. One of: `paid`, `posted`, `payment_due`, `not_paid`, `voided`, `pending`.
- `status_in` (`string`, optional): Only invoices in any of these statuses (paid, posted, payment_due, not_paid, voided, pending). A JSON array written as text, e.g. ["payment_due","not_paid"].
- `subscription_id` (`string`, optional): Only invoices of this subscription ID. Example: AzZTZgTSz7nCt3Pu.
- `updated_after` (`integer`, optional): Only invoices updated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{}`

### `chargebee_item_get`

Get Item · Read-only

Get one Chargebee catalog item (plan, addon or charge) by ID.
Returns the item with name, type, status, item family, unit and checkout/portal settings.
Use chargebee_item_get when you have the item ID. Use chargebee_items_list to browse, and chargebee_item_prices_list for its prices.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_id` (`string`, required): ID of the item (plan, addon or charge), from chargebee_items_list. Example: pro-plan.

Example input: `{"item_id":"<item_id>"}`

### `chargebee_item_price_get`

Get Item Price · Read-only

Get one Chargebee item price by ID.
Returns the item price with pricing model, price or tiers, currency, billing period, trial settings and status.
Use chargebee_item_price_get when you have the item price ID. Use chargebee_item_prices_list to find prices for an item.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_price_id` (`string`, required): ID of the item price, from chargebee_item_prices_list. Example: pro-USD-Monthly.

Example input: `{"item_price_id":"<item_price_id>"}`

### `chargebee_item_prices_list`

List Item Prices · Read-only

List item prices in the Chargebee catalog, optionally filtered by item, item type, status, currency, billing period or pricing model.
Returns a list of item price objects (id, item_id, name, pricing_model, price, currency_code, period, period_unit, status) and next_offset when more pages exist.
Use chargebee_item_prices_list to find the item price IDs needed for chargebee_subscription_create. Use chargebee_item_price_get for one price's tiers and details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `currency_code` (`string`, optional): Only item prices in this ISO 4217 currency. Example: USD.
- `item_family_id` (`string`, optional): Only prices of items in this item family ID. Example: cloud-storage.
- `item_id` (`string`, optional): Only prices of this item ID. Example: pro-plan.
- `item_type` (`string`, optional): Only prices of items of this type: plan, addon or charge. Example: plan. One of: `plan`, `addon`, `charge`.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `period_unit` (`string`, optional): Only item prices billed on this period unit. Example: month. One of: `day`, `week`, `month`, `year`.
- `pricing_model` (`string`, optional): Only item prices with this pricing model. Example: per_unit. One of: `flat_fee`, `per_unit`, `tiered`, `volume`, `stairstep`.
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: name. One of: `name`, `id`, `updated_at`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: name. One of: `name`, `id`, `updated_at`.
- `status` (`string`, optional): Only item prices in this status. Example: active. One of: `active`, `archived`, `deleted`.

Example input: `{}`

### `chargebee_items_list`

List Items · Read-only

List items in the Chargebee product catalog: plans, addons and charges, optionally filtered by type, status, name or item family.
Returns a list of item objects (id, name, type, status, item_family_id) and next_offset when more pages exist.
Use chargebee_items_list to browse plans and addons. Use chargebee_item_prices_list for their prices, which subscriptions use.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `item_family_id` (`string`, optional): Only items in this item family (product line) ID. Example: cloud-storage.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `name_starts_with` (`string`, optional): Only items whose name starts with this text. Example: Pro.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: name. One of: `name`, `id`, `updated_at`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: name. One of: `name`, `id`, `updated_at`.
- `status` (`string`, optional): Only items in this status. Example: active. One of: `active`, `archived`, `deleted`.
- `type` (`string`, optional): Only items of this type: plan, addon or charge. Example: plan. One of: `plan`, `addon`, `charge`.
- `updated_after` (`integer`, optional): Only items updated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{}`

### `chargebee_subscription_get`

Get Subscription · Read-only

Get one Chargebee subscription by ID.
Returns the subscription (status, subscription_items, coupons, current term, next_billing_at, mrr), its customer and primary card.
Use chargebee_subscription_get when you have the subscription ID. Use chargebee_subscriptions_list to find subscriptions by customer or status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.

Example input: `{"subscription_id":"<subscription_id>"}`

### `chargebee_subscriptions_list`

List Subscriptions · Read-only

List subscriptions in Chargebee, optionally filtered by customer, status, item, item price or dates.
Returns a list of entries, each with the subscription (id, status, subscription_items, billing period, next_billing_at, mrr) and its customer, plus next_offset when more pages exist.
Use chargebee_subscriptions_list to browse or filter. Use chargebee_subscription_get when you already have the subscription ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `created_after` (`integer`, optional): Only subscriptions created after this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `created_before` (`integer`, optional): Only subscriptions created before this time. Unix timestamp in seconds (UTC). Example: 1735689600.
- `customer_id` (`string`, optional): Only subscriptions of this customer ID. Example: 16BjfNSzYXqA21Dt.
- `include_deleted` (`boolean`, optional): Set to true to also return deleted subscriptions. Defaults to false.
- `item_id` (`string`, optional): Only subscriptions that contain this item (plan, addon or charge) ID. Example: pro-plan.
- `item_price_id` (`string`, optional): Only subscriptions that contain this item price ID. Example: pro-USD-Monthly.
- `limit` (`integer`, optional): Number of records to return per page, from 1 to 100. Chargebee returns 10 when not set. Example: 25.
- `next_billing_before` (`integer`, optional): Only subscriptions whose next billing date is before this time; useful to find upcoming renewals. Unix timestamp in seconds (UTC). Example: 1735689600.
- `offset` (`string`, optional): Pagination cursor. Pass the next_offset value from the previous page's response to get the next page. Leave empty for the first page. Example: ["1735689600000","230000000123"].
- `sort_by_asc` (`string`, optional): Sort the results in ascending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: created_at. One of: `created_at`, `updated_at`.
- `sort_by_desc` (`string`, optional): Sort the results in descending order by this attribute. Use either sort_by_asc or sort_by_desc, not both. Example: created_at. One of: `created_at`, `updated_at`.
- `status` (`string`, optional): Only subscriptions in this status. Example: active. One of: `future`, `in_trial`, `active`, `non_renewing`, `paused`, `cancelled`, `transferred`.
- `status_in` (`string`, optional): Only subscriptions in any of these statuses (future, in_trial, active, non_renewing, paused, cancelled, transferred). A JSON array written as text, e.g. ["active","in_trial"].
- `updated_after` (`integer`, optional): Only subscriptions updated after this time. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{}`

### `chargebee_coupon_create`

Create Coupon · Write

Create a percentage, fixed-amount or free-quantity coupon in Chargebee that applies to the invoice total or to specific items.
Returns the new coupon object.
Use chargebee_coupon_create to set up a new discount. Apply it with coupon_ids on chargebee_subscription_create or chargebee_subscription_update.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `apply_on` (`string`, required): What the discount applies to: invoice_amount (the invoice subtotal) or each_specified_item (each matching line item; set item_constraints). Example: invoice_amount. One of: `invoice_amount`, `each_specified_item`.
- `id` (`string`, required): Unique ID for the coupon, up to 100 characters; customers can also enter it as a code. Example: SUMMER20.
- `name` (`string`, required): Display name of the coupon, up to 50 characters, unique on the site. Example: Summer 20% off.
- `currency_code` (`string`, optional): ISO 4217 currency of discount_amount, for fixed_amount coupons on multi-currency sites. Example: USD.
- `discount_amount` (`integer`, optional): Amount to deduct, in the currency's smallest unit (e.g. 1000 is $10.00), when discount_type is fixed_amount. Example: 1000.
- `discount_percentage` (`number`, optional): Percentage to deduct, from 0.01 to 100, when discount_type is percentage. Example: 20.
- `discount_type` (`string`, optional): Type of discount: percentage (default, set discount_percentage), fixed_amount (set discount_amount and currency_code) or offer_quantity. Example: percentage. One of: `fixed_amount`, `percentage`, `offer_quantity`.
- `duration_type` (`string`, optional): How long the discount lasts on a subscription: one_time, forever (default) or limited_period (set period and period_unit). Example: limited_period. One of: `one_time`, `forever`, `limited_period`.
- `invoice_name` (`string`, optional): Name shown on invoices instead of name. Example: Summer discount.
- `item_constraints` (`object`, optional): Which items the coupon applies to, written as parallel lists (index 0 of each list is the first rule). constraint is all, none, specific or criteria; item_type is plan, addon or charge; item_price_ids (for specific) is a JSON array written as text. Needed when apply_on is each_specified_item. Example: {"constraint": ["all"], "item_type": ["plan"]}.
- `max_redemptions` (`integer`, optional): Maximum number of times the coupon can be redeemed. Leave empty for no limit. Example: 100.
- `period` (`integer`, optional): Number of period_units the discount lasts, when duration_type is limited_period. Example: 3.
- `period_unit` (`string`, optional): Unit of period, when duration_type is limited_period. Example: month. One of: `day`, `week`, `month`, `year`.
- `valid_till` (`integer`, optional): Last time the coupon can be applied to new subscriptions. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{"apply_on":"invoice_amount","id":"<id>","name":"<name>"}`

### `chargebee_credit_note_create`

Create Credit Note · Write

Create a credit note in Chargebee for a total amount, against an invoice or as customer credit.
Returns the new credit note.
Use chargebee_credit_note_create to give a partial credit or refundable credit. Use chargebee_invoice_void to cancel a whole unpaid invoice instead.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `type` (`string`, required): Type of credit note: adjustment (reduces the amount due on an unpaid invoice; needs reference_invoice_id), refundable (for a paid invoice; can be refunded or used as credits) or store (store credits for a customer; needs customer_id). Example: refundable. One of: `adjustment`, `refundable`, `store`.
- `comment` (`string`, optional): Internal comment added to the credit note. Example: Approved by support lead.
- `create_reason_code` (`string`, optional): Reason code for the credit note, as set up in the Chargebee app under Settings > Reason Codes. Example: Service Unsatisfactory.
- `currency_code` (`string`, optional): ISO 4217 currency, for a credit note not tied to an invoice on a multi-currency site. Example: USD.
- `customer_id` (`string`, optional): ID of the customer, for a refundable or store credit note not tied to an invoice. Example: 16BjfNSzYXqA21Dt.
- `customer_notes` (`string`, optional): Note shown on the customer-facing credit note. Example: Credit for the March outage.
- `date` (`integer`, optional): Date of the credit note; defaults to now. Must be on or after the invoice date. Unix timestamp in seconds (UTC). Example: 1735689600.
- `reference_invoice_id` (`string`, optional): ID of the invoice the credit note is issued against; required for adjustment, and for refundable unless customer_id is set. Example: 1024.
- `total` (`integer`, optional): Credit amount in the currency's smallest unit (e.g. 2500 is $25.00). Must not exceed what the referenced invoice allows. Example: 2500.

Example input: `{"type":"adjustment"}`

### `chargebee_customer_create`

Create Customer · Write

Create a customer in Chargebee with contact details, billing address and billing preferences.
Returns the new customer object, including its id.
Use chargebee_customer_create before creating a subscription for a new buyer. Use chargebee_customer_update to change an existing customer.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `auto_collection` (`string`, optional): on to charge the customer's payment method automatically when an invoice is created; off to collect payment manually. Example: on. One of: `on`, `off`.
- `billing_address` (`object`, optional): Billing address of the customer. Use any of: first_name, last_name, email, company, phone, line1, line2, line3, city, state_code, state, zip, country (ISO 3166 alpha-2 code). Example: {"line1": "340 S Lemon Ave", "city": "Walnut", "state_code": "CA", "zip": "91789", "country": "US"}.
- `company` (`string`, optional): Company name of the customer. Example: Acme Inc.
- `email` (`string`, optional): Email address of the customer; Chargebee sends billing emails here. Example: jane@acme.com.
- `first_name` (`string`, optional): First name of the customer. Example: Jane.
- `id` (`string`, optional): ID for the new customer, up to 50 characters. Chargebee generates one when not set. Example: cust_acme_001.
- `invoice_notes` (`string`, optional): Note printed on every invoice for this customer. Example: PO 4500012345.
- `last_name` (`string`, optional): Last name of the customer. Example: Doe.
- `locale` (`string`, optional): Language and region used in emails and hosted pages for the customer. Example: en-US.
- `meta_data` (`string`, optional): Custom key-value data to store on the record, written as a JSON object in text form. Example: {"crm_id": "0015g00000XyZ"}.
- `net_term_days` (`integer`, optional): Number of days after the invoice date that payment is due. Must be one of the net term values set up on the site. Example: 30.
- `phone` (`string`, optional): Phone number of the customer. Example: +1 415 555 0100.
- `preferred_currency_code` (`string`, optional): ISO 4217 currency code for the customer, used when multi-currency is enabled on the site. Example: USD.
- `taxability` (`string`, optional): Whether taxes apply to the customer: taxable, exempt or zero_rated. Example: taxable. One of: `taxable`, `exempt`, `zero_rated`.

Example input: `{}`

### `chargebee_customer_update`

Update Customer · Write

Update a Chargebee customer's contact details and billing preferences. Fields you leave out stay unchanged.
Returns the updated customer object.
Use chargebee_customer_update to change name, email, auto collection, net terms or metadata. It does not change the billing address or VAT number.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): ID of the customer to update, from chargebee_customers_list. Example: 16BjfNSzYXqA21Dt.
- `auto_collection` (`string`, optional): on to charge the customer's payment method automatically when an invoice is created; off to collect payment manually. Example: on. One of: `on`, `off`.
- `company` (`string`, optional): Company name of the customer. Example: Acme Inc.
- `email` (`string`, optional): Email address of the customer; Chargebee sends billing emails here. Example: jane@acme.com.
- `first_name` (`string`, optional): First name of the customer. Example: Jane.
- `invoice_notes` (`string`, optional): Note printed on every invoice for this customer. Example: PO 4500012345.
- `last_name` (`string`, optional): Last name of the customer. Example: Doe.
- `locale` (`string`, optional): Language and region used in emails and hosted pages for the customer. Example: en-US.
- `meta_data` (`string`, optional): Custom key-value data to store on the record, written as a JSON object in text form. Example: {"crm_id": "0015g00000XyZ"}.
- `net_term_days` (`integer`, optional): Number of days after the invoice date that payment is due. Must be one of the net term values set up on the site. Example: 30.
- `phone` (`string`, optional): Phone number of the customer. Example: +1 415 555 0100.
- `preferred_currency_code` (`string`, optional): ISO 4217 currency code for the customer, used when multi-currency is enabled on the site. Example: USD.
- `taxability` (`string`, optional): Whether taxes apply to the customer: taxable, exempt or zero_rated. Example: taxable. One of: `taxable`, `exempt`, `zero_rated`.

Example input: `{"customer_id":"<customer_id>"}`

### `chargebee_invoice_payment_record`

Record Invoice Payment · Write

Record a payment received outside Chargebee (cash, check, bank transfer) against an unpaid invoice.
Returns the updated invoice and the transaction that was created.
Use chargebee_invoice_payment_record for offline payments. It does not charge the customer's card.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): ID of the unpaid invoice to record a payment against, from chargebee_invoices_list. Example: 1024.
- `payment_method` (`string`, required): How the payment was received outside Chargebee: cash, check, bank_transfer, other or custom. Example: bank_transfer. One of: `cash`, `check`, `bank_transfer`, `other`, `custom`.
- `amount` (`integer`, optional): Amount received, in the currency's smallest unit (e.g. 5000 is $50.00). Defaults to the invoice's amount_due. Example: 5000.
- `comment` (`string`, optional): Internal remark about the payment. Example: Wire received from Acme.
- `date` (`integer`, optional): When the payment was received; defaults to now. Unix timestamp in seconds (UTC). Example: 1735689600.
- `reference_number` (`string`, optional): Reference for the payment, such as a check or bank transfer number. Example: CHK-55021.

Example input: `{"invoice_id":"<invoice_id>","payment_method":"cash"}`

### `chargebee_subscription_create`

Create Subscription · Write

Create a subscription for an existing Chargebee customer from one plan item price plus optional addon and charge item prices.
Returns the new subscription, the customer and, when charges are raised now, the invoice.
Use chargebee_subscription_create for a new subscription. Use chargebee_subscription_update to change items on an existing one.
Requires an existing customer (chargebee_customer_create) and item price IDs (chargebee_item_prices_list).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `customer_id` (`string`, required): ID of the existing customer to subscribe, from chargebee_customers_list or chargebee_customer_create. Example: 16BjfNSzYXqA21Dt.
- `subscription_items` (`object`, required): Item prices on the subscription, written as parallel lists: index 0 of every list describes the first item, index 1 the second, and so on. item_price_id is required for each item; quantity is needed for per-unit prices; unit_price (in the currency's smallest unit, e.g. cents) overrides the catalog price. Exactly one entry must be a plan item price; the rest can be addon or charge item prices. Get IDs from chargebee_item_prices_list. Example: {"item_price_id": ["pro-USD-Monthly", "extra-seats-USD-Monthly"], "quantity": [1, 3]}.
- `auto_collection` (`string`, optional): Overrides the customer's auto collection setting for this subscription: on or off. Example: off. One of: `on`, `off`.
- `billing_cycles` (`integer`, optional): Number of billing cycles the subscription runs before it stops renewing. Leave empty to renew until cancelled. Example: 12.
- `coupon_ids` (`array`, optional): Coupon IDs or coupon codes to apply, from chargebee_coupons_list. Example: ["SUMMER20"].
- `id` (`string`, optional): ID for the new subscription, up to 50 characters. Chargebee generates one when not set. Example: sub_acme_pro.
- `invoice_immediately` (`boolean`, optional): Set to true to invoice charges raised now immediately; false adds them to unbilled charges. Defaults to the site setting.
- `invoice_notes` (`string`, optional): Note printed on invoices for this subscription. Example: Annual contract signed on 2026-01-05.
- `meta_data` (`string`, optional): Custom key-value data to store on the record, written as a JSON object in text form. Example: {"crm_id": "0015g00000XyZ"}.
- `po_number` (`string`, optional): Purchase order number for this subscription. Example: PO-2026-001.
- `start_date` (`integer`, optional): When the subscription starts; leave empty to start now. A future date creates a subscription in future status. Unix timestamp in seconds (UTC). Example: 1735689600.
- `trial_end` (`integer`, optional): When the trial ends, overriding the plan's trial period. Use 0 for no trial. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{"customer_id":"<customer_id>","subscription_items":{"item_price_id":["pro-USD-Monthly","extra-seats-USD-Monthly"],"quantity":[1,3]}}`

### `chargebee_subscription_pause`

Pause Subscription · Write

Pause an active or non-renewing Chargebee subscription now, at term end, on a date, or for a number of billing cycles.
Returns the subscription with status paused, or with pause_date set when scheduled.
Use chargebee_subscription_pause to stop renewals temporarily. Use chargebee_subscription_resume to restart it, and chargebee_subscription_cancel to end it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.
- `invoice_dunning_handling` (`string`, optional): Whether dunning continues or stops for unpaid invoices while paused. Example: continue. One of: `continue`, `stop`.
- `pause_date` (`integer`, optional): When to pause, if pause_option is specific_date. Unix timestamp in seconds (UTC). Example: 1735689600.
- `pause_option` (`string`, optional): When to pause: immediately, end_of_term, specific_date (then set pause_date) or billing_cycles (then set skip_billing_cycles). Example: end_of_term. One of: `immediately`, `end_of_term`, `specific_date`, `billing_cycles`.
- `resume_date` (`integer`, optional): When to resume automatically. Leave empty to pause until resumed by hand. Unix timestamp in seconds (UTC). Example: 1735689600.
- `skip_billing_cycles` (`integer`, optional): Number of billing cycles to skip, if pause_option is billing_cycles. Example: 2.
- `unbilled_charges_handling` (`string`, optional): What to do with unbilled charges when pausing: no_action or invoice. Example: invoice. One of: `no_action`, `invoice`.

Example input: `{"subscription_id":"<subscription_id>"}`

### `chargebee_subscription_reactivate`

Reactivate Subscription · Write

Reactivate a cancelled Chargebee subscription, now or from a given date, optionally with a new trial.
Returns the subscription with status active or in_trial, plus any invoice raised.
Use chargebee_subscription_reactivate for a cancelled subscription. Use chargebee_subscription_resume for a paused one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.
- `billing_cycles` (`integer`, optional): Number of billing cycles, including the current one, before the subscription stops renewing. Example: 12.
- `invoice_immediately` (`boolean`, optional): Set to true to invoice charges raised now immediately; false adds them to unbilled charges.
- `reactivate_from` (`integer`, optional): When the reactivation takes effect; leave empty to reactivate now. Can be in the past to backdate. Unix timestamp in seconds (UTC). Example: 1735689600.
- `trial_end` (`integer`, optional): Set to reactivate the subscription in trial, ending at this time. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{"subscription_id":"<subscription_id>"}`

### `chargebee_subscription_resume`

Resume Subscription · Write

Resume a paused Chargebee subscription now or on a set date.
Returns the subscription, its customer and any invoice raised on resume.
Use chargebee_subscription_resume for a paused subscription. Use chargebee_subscription_reactivate for a cancelled one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.
- `charges_handling` (`string`, optional): How to bill charges raised on resume: invoice_immediately or add_to_unbilled_charges. Example: invoice_immediately. One of: `invoice_immediately`, `add_to_unbilled_charges`.
- `resume_date` (`integer`, optional): When to resume, if resume_option is specific_date. Unix timestamp in seconds (UTC). Example: 1735689600.
- `resume_option` (`string`, optional): When to resume: immediately or specific_date (then set resume_date). Example: immediately. One of: `immediately`, `specific_date`.
- `unpaid_invoices_handling` (`string`, optional): What to do with unpaid invoices on resume: no_action or schedule_payment_collection. Example: no_action. One of: `no_action`, `schedule_payment_collection`.

Example input: `{"subscription_id":"<subscription_id>"}`

### `chargebee_subscription_update`

Update Subscription · Write

Change a Chargebee subscription's item prices, quantities, coupons, trial or billing settings, now or at a scheduled time.
Returns the updated subscription, its customer and any invoice or credit notes the change raised.
Use chargebee_subscription_update for upgrades, downgrades and quantity changes. Use chargebee_subscription_cancel, _pause or _resume to change its lifecycle.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.
- `auto_collection` (`string`, optional): Overrides the customer's auto collection setting for this subscription: on or off. Example: on. One of: `on`, `off`.
- `billing_cycles` (`integer`, optional): New number of billing cycles before the subscription stops renewing. Example: 12.
- `change_option` (`string`, optional): When the change takes effect: immediately, end_of_term, or specific_date (then set changes_scheduled_at). Example: immediately. One of: `immediately`, `end_of_term`, `specific_date`.
- `changes_scheduled_at` (`integer`, optional): When the change takes effect, if change_option is specific_date. Unix timestamp in seconds (UTC). Example: 1735689600.
- `coupon_ids` (`array`, optional): Coupon IDs or codes to apply. Example: ["SUMMER20"].
- `invoice_immediately` (`boolean`, optional): Set to true to invoice charges raised by the change now; false adds them to unbilled charges.
- `invoice_notes` (`string`, optional): Note printed on invoices for this subscription. Example: Upgraded to Pro.
- `meta_data` (`string`, optional): Custom key-value data to store on the record, written as a JSON object in text form. Example: {"crm_id": "0015g00000XyZ"}.
- `po_number` (`string`, optional): Purchase order number for this subscription. Example: PO-2026-002.
- `prorate` (`boolean`, optional): For a mid-term change, true raises prorated credits and charges; false does not. Defaults to the site setting.
- `replace_coupon_list` (`boolean`, optional): Set to true to replace the existing coupons with coupon_ids; false (default) adds to them.
- `replace_items_list` (`boolean`, optional): Set to true to replace all existing items with subscription_items; false (default) adds or updates only the items you pass.
- `subscription_items` (`object`, optional): Item prices on the subscription, written as parallel lists: index 0 of every list describes the first item, index 1 the second, and so on. item_price_id is required for each item; quantity is needed for per-unit prices; unit_price (in the currency's smallest unit, e.g. cents) overrides the catalog price. Items you pass are added or updated; set replace_items_list to true to replace the whole list. Get IDs from chargebee_item_prices_list. Example: {"item_price_id": ["pro-USD-Monthly", "extra-seats-USD-Monthly"], "quantity": [1, 3]}.
- `trial_end` (`integer`, optional): New trial end time. Use 0 to end the trial now. Unix timestamp in seconds (UTC). Example: 1735689600.

Example input: `{"subscription_id":"<subscription_id>"}`

### `chargebee_invoice_void`

Void Invoice · Destructive

Void a Chargebee invoice so it is no longer payable. Voiding cannot be undone.
Returns the invoice with status voided and any credit note raised.
Use chargebee_invoice_void to cancel an invoice raised in error. Use chargebee_credit_note_create to credit part of a paid invoice instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): ID of the invoice to void, from chargebee_invoices_list. Example: 1024.
- `comment` (`string`, optional): Internal comment added to the invoice for this action. Example: Duplicate invoice.
- `void_reason_code` (`string`, optional): Void reason code, as set up in the Chargebee app under Settings > Reason Codes. Example: Duplicate.

Example input: `{"invoice_id":"<invoice_id>"}`

### `chargebee_subscription_cancel`

Cancel Subscription · Destructive

Cancel a Chargebee subscription now, at the end of the term, or on a set date, with options for credits and unpaid invoices.
Returns the subscription with status cancelled or non_renewing, plus any invoice or credit notes raised.
Use chargebee_subscription_cancel to end a subscription. Use chargebee_subscription_pause to stop billing temporarily, and chargebee_subscription_reactivate to restart a cancelled one.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): ID of the subscription, from chargebee_subscriptions_list. Example: AzZTZgTSz7nCt3Pu.
- `account_receivables_handling` (`string`, optional): What to do with unpaid invoices: no_action, schedule_payment_collection or write_off. Example: no_action. One of: `no_action`, `schedule_payment_collection`, `write_off`.
- `cancel_at` (`integer`, optional): When to cancel, if cancel_option is specific_date. Unix timestamp in seconds (UTC). Example: 1735689600.
- `cancel_option` (`string`, optional): When to cancel: immediately, end_of_term, specific_date (then set cancel_at) or end_of_billing_term. Defaults to immediately. Example: end_of_term. One of: `immediately`, `end_of_term`, `specific_date`, `end_of_billing_term`.
- `cancel_reason_code` (`string`, optional): Cancellation reason code, as set up in the Chargebee app under Settings > Reason Codes. Example: Not Satisfied.
- `credit_option_for_current_term_charges` (`string`, optional): Credit to give for the unused part of the current term when cancelling immediately: none, prorate, full or consumption_based. Example: prorate. One of: `none`, `prorate`, `full`, `consumption_based`.
- `refundable_credits_handling` (`string`, optional): What to do with the customer's refundable credits: no_action or schedule_refund. Example: no_action. One of: `no_action`, `schedule_refund`.
- `unbilled_charges_option` (`string`, optional): What to do with unbilled charges: invoice them now or delete them. Example: invoice. One of: `invoice`, `delete`.

Example input: `{"subscription_id":"<subscription_id>"}`

## Related

Other Accounting & Finance connectors ([all 82](/agentkit/connectors/?category=accounting-finance)):

- [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools
- [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools
- [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
