A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Chargebee API is how an app or AI agent works with a Chargebee site: creating a subscription, charging an invoice, adding a customer, building the product catalog, or issuing a credit note. Access is granted through a site-specific API key, which is full-access because Chargebee has no granular scopes, so the key can reach every resource on its site. A change on the site emits an Event that Chargebee can deliver to a registered webhook.
How an app or AI agent connects to Chargebee determines what it can reach. There is a route for making calls, a route for receiving events, and hosted servers that expose Chargebee tools to agents, and each is governed by the key behind it.
The REST API answers at https://{site}.chargebee.com/api/v2, where {site} is the Chargebee site name. It takes form-encoded request bodies, returns JSON wrapped in a resource container, and pages through lists with an offset cursor. A call authenticates with HTTP Basic auth, using the API key as the username and an empty password.
Chargebee POSTs an Event as JSON to an HTTPS endpoint configured for the site. The endpoint is secured with HTTP Basic auth or a random key embedded in the URL, since Chargebee does not sign webhook bodies. Deliveries are asynchronous, can arrive out of order, and are retried for up to two days, so an integration deduplicates on the event id.
Chargebee's AgentKit publishes hosted Model Context Protocol servers at https://{subdomain}.mcp.chargebee.com (with mcp.eu and mcp.au hosts for other data centers). Predefined servers cover a Knowledge Base server for docs and API references, a Data Lookup server that reads customer, subscription, invoice, and payment data, and an Onboarding server for catalogs and demo data on test sites, plus a Custom server that bundles chosen tools. Each server except the Knowledge Base authenticates with an API key generated on its configuration page. A separate local stdio package, @chargebee/mcp, is deprecated in favor of the hosted Knowledge Base server.
Every API call authenticates with a site-specific API key, sent through HTTP Basic auth as the username with an empty password. A Chargebee key is full-access: it can call every API and resource on its site, because Chargebee has no granular per-resource scopes. A key belongs to one site, either a live site or a test site, and keys are managed under the site's API and webhook settings.
A publishable key is safe to use in client code. It is limited to a few client-side operations, like tokenizing payment details and opening hosted pages, and cannot read or change site data.
The Chargebee API is split into areas an agent can act on, like subscriptions, customers, invoices, the product catalog, payment sources, and credit notes. Each area has its own methods, and writes in some areas charge customers, cancel billing, or move money.
Create, retrieve, list, update, cancel, pause, and resume subscriptions, modeled on items.
Create, retrieve, list, update, and delete the customers that subscriptions and invoices belong to.
Create, retrieve, list, and collect payment on invoices, and void or generate a PDF for one.
Create, retrieve, and list items and item prices in Product Catalog 2.0, and plans in Product Catalog 1.0.
Store a payment source from a gateway token, retrieve, list, and delete payment sources for a customer.
Create, retrieve, and list credit notes, and refund a refundable credit note.
Retrieve and list the payment and refund transactions recorded against invoices and customers.
Create a Chargebee-hosted checkout or self-serve page and retrieve one by id.
Retrieve and list the events that record changes on a site and back the webhook feed.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SubscriptionsCreate, retrieve, list, update, cancel, pause, and resume subscriptions, modeled on items.7 | ||||||
| POST | /customers/{customer-id}/subscription_for_items | Create a subscription for an existing customer using items (Product Catalog 2.0). | write | Full-access key | Current | |
Chargebee keys are full-access; access is all-or-nothing, not per-resource. Idempotency is supported via an idempotency key header. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook event subscription_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /subscriptions/{subscription-id} | Retrieve a subscription by id. | read | Full-access key | Current | |
Read-only call. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /subscriptions | List subscriptions, with filters and offset pagination. | read | Full-access key | Current | |
Read-only call. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{subscription-id}/update_subscription_for_items | Update a subscription's items, quantities, or terms (Product Catalog 2.0). | write | Full-access key | Current | |
Can change what a customer is billed for and when. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{subscription-id}/cancel_for_items | Cancel a subscription immediately or at the end of the current term. | write | Full-access key | Current | |
Ends recurring billing; fires subscription_cancelled. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook event subscription_cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{subscription-id}/pause | Pause a subscription immediately or from a chosen date. | write | Full-access key | Current | |
Halts billing until resumed. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions/{subscription-id}/resume | Resume a paused subscription. | write | Full-access key | Current | |
Restarts billing on a paused subscription. Acts onsubscription Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersCreate, retrieve, list, update, and delete the customers that subscriptions and invoices belong to.5 | ||||||
| POST | /customers | Create a customer to hold subscriptions, payment sources, and billing details. | write | Full-access key | Current | |
A core write; fires customer_created. Acts oncustomer Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook event customer_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers/{customer-id} | Retrieve a customer by id. | read | Full-access key | Current | |
Read-only call. Acts oncustomer Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /customers | List customers, with filters and offset pagination. | read | Full-access key | Current | |
Read-only call. Acts oncustomer Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /customers/{customer-id} | Update a customer's details. | write | Full-access key | Current | |
A core write. Acts oncustomer Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /customers/{customer-id}/delete | Delete a customer and the data associated with it. | write | Full-access key | Current | |
Removes the customer and its dependent records. Acts oncustomer Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesCreate, retrieve, list, and collect payment on invoices, and void or generate a PDF for one.6 | ||||||
| POST | /invoices/create_for_charge_items_and_charges | Create an ad hoc invoice for items and charges against a customer. | write | Full-access key | Current | |
Generates a billing document; fires invoice_generated. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook event invoice_generatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /invoices/{invoice-id} | Retrieve an invoice by id. | read | Full-access key | Current | |
Read-only call. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /invoices | List invoices, with filters and offset pagination. | read | Full-access key | Current | |
Read-only call. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice-id}/collect_payment | Attempt to collect payment on an invoice using a stored or supplied payment source. | write | Full-access key | Current | |
Charges the customer; fires payment_succeeded or payment_failed. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook event payment_succeededRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice-id}/void | Void an invoice so it is no longer payable. | write | Full-access key | Current | |
Cancels the billing document. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invoices/{invoice-id}/pdf | Generate a short-lived download URL for an invoice PDF. | read | Full-access key | Current | |
Returns a temporary download link rather than changing data. Acts oninvoice Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Product catalog (Items & Plans)Create, retrieve, and list items and item prices in Product Catalog 2.0, and plans in Product Catalog 1.0.6 | ||||||
| POST | /items | Create an item, a sellable product, charge, or addon in Product Catalog 2.0. | write | Full-access key | Current | |
Defines what can be sold. Idempotency is supported on this endpoint. Acts onitem Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /items | List items in the product catalog. | read | Full-access key | Current | |
Read-only call. Acts onitem Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /item_prices | Create an item price defining how much and how often an item is charged. | write | Full-access key | Current | |
Sets pricing used by subscriptions and invoices. Acts onitem_price Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /item_prices | List item prices in the product catalog. | read | Full-access key | Current | |
Read-only call. Acts onitem_price Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /plans | Create a plan in Product Catalog 1.0 (the pre-items model). | write | Full-access key | Current | |
Only on sites using Product Catalog 1.0; items and item prices replace plans in 2.0. Acts onplan Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /plans | List plans (Product Catalog 1.0). | read | Full-access key | Current | |
Read-only call; Product Catalog 1.0 only. Acts onplan Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payment sourcesStore a payment source from a gateway token, retrieve, list, and delete payment sources for a customer.4 | ||||||
| POST | /payment_sources/create_using_token | Store a payment source for a customer from a temporary gateway token. | write | Full-access key | Current | |
Adds a reusable payment method; the token is created client-side to keep card data off the integration's servers. Acts onpayment_source Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payment_sources/{payment-source-id} | Retrieve a payment source by id. | read | Full-access key | Current | |
Read-only call. Acts onpayment_source Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /payment_sources | List payment sources, filterable by customer. | read | Full-access key | Current | |
Read-only call. Acts onpayment_source Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /payment_sources/{payment-source-id} | Delete a stored payment source from a customer. | write | Full-access key | Current | |
Removes the payment method so it can no longer be charged. Acts onpayment_source Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Credit notesCreate, retrieve, and list credit notes, and refund a refundable credit note.3 | ||||||
| POST | /credit_notes | Create a credit note against an invoice. | write | Full-access key | Current | |
Issues credit that can offset future invoices or be refunded. Acts oncredit_note Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /credit_notes/{credit-note-id} | Retrieve a credit note by id. | read | Full-access key | Current | |
Read-only call. Acts oncredit_note Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /credit_notes/{credit-note-id}/refund | Refund a refundable credit note back to the customer. | write | Full-access key | Current | |
Moves real money back to the customer. Acts oncredit_note Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransactionsRetrieve and list the payment and refund transactions recorded against invoices and customers.2 | ||||||
| GET | /transactions/{transaction-id} | Retrieve a payment or refund transaction by id. | read | Full-access key | Current | |
Read-only call. Acts ontransaction Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /transactions | List transactions, with filters and offset pagination. | read | Full-access key | Current | |
Read-only call. Acts ontransaction Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Hosted pagesCreate a Chargebee-hosted checkout or self-serve page and retrieve one by id.3 | ||||||
| POST | /hosted_pages/checkout_new_for_items | Create a Chargebee-hosted checkout page for a new subscription using items. | write | Full-access key | Current | |
Returns a URL where a customer can pay and start a subscription. Acts onhosted_page Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /hosted_pages/manage_payment_sources | Create a hosted page where a customer manages their stored payment sources. | write | Full-access key | Current | |
Returns a self-serve URL for updating payment methods. Acts onhosted_page Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /hosted_pages/{hosted-page-id} | Retrieve a hosted page by id to check its state after a customer returns. | read | Full-access key | Current | |
Read-only call. Acts onhosted_page Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsRetrieve and list the events that record changes on a site and back the webhook feed.2 | ||||||
| GET | /events/{event-id} | Retrieve an event, used to verify and re-fetch webhook payloads. | read | Full-access key | Current | |
Read-only call. Acts onevent Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /events | List events, for polling or reconciliation. | read | Full-access key | Current | |
Read-only call. Acts onevent Permission (capability) Full-access keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Chargebee can notify an app when something happens on a site, like a subscription being created or a payment failing. It posts an Event describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
subscription_created | A new subscription was created on the site. | /customers/{customer-id}/subscription_for_items |
subscription_cancelled | A subscription was cancelled, immediately or at the end of its term. | /subscriptions/{subscription-id}/cancel_for_items |
customer_created | A new customer was created on the site. | /customers |
invoice_generated | An invoice was generated for a customer. | /invoices/create_for_charge_items_and_charges |
payment_succeeded | A payment against an invoice succeeded. | /invoices/{invoice-id}/collect_payment |
payment_failed | A payment attempt against an invoice failed, the point where dunning begins. | /invoices/{invoice-id}/collect_payment |
Chargebee limits how fast an app can call, by a per-minute request rate that depends on the plan and by separate caps on how many requests run at once.
Chargebee meters requests per minute, with the ceiling set by the site's plan: 150 per minute on Starter and on test sites, 1,000 on Performance, and 3,500 by default on Enterprise, with no fixed upper limit on custom Enterprise plans. A separate concurrency limit caps how many requests run at once, at 50 simultaneous GET requests and 100 simultaneous POST requests, since GETs typically finish faster. Exceeding either limit returns HTTP 429 with an optional Retry-After header that says how long to wait, and higher limits can be requested from Chargebee support.
List endpoints use offset pagination. The limit parameter sets the page size, defaulting to 10 and capping at 100, and a next_offset value in the response is passed back as the offset parameter to fetch the following page. When next_offset is absent, there are no more results.
A list endpoint returns at most 100 records per page. Requests are form-encoded and responses are JSON, with each resource wrapped in a named container and timestamps given as Unix epoch seconds.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | payment / invalid_request | A client error. The body carries a type, like payment for a failed charge or invalid_request for a bad parameter, plus an api_error_code such as payment_processing_failed, param_wrong_value, or duplicate_entry. | Read the api_error_code, type, and param fields, fix the request, and resend. A payment-type error means the charge failed, not the request. |
| 401 | api_authentication_failed | Authentication failed: the API key is missing, invalid, or sent in the wrong format. | Confirm a valid site-specific key is sent as the Basic-auth username with an empty password. |
| 403 | api_authorization_failed | The key is valid but not allowed to perform this operation. | Use a key permitted for the operation, or enable the feature on the site. |
| 404 | resource_not_found | The requested resource does not exist on the site. | Verify the id and that it belongs to this site and mode. |
| 409 | invalid_state_for_request | The resource is in a state that does not allow this operation, like cancelling an already cancelled subscription. | Refetch the resource state, then retry only when the operation is valid. |
| 429 | api_request_limit_exceeded | A rate or concurrency limit was hit. A lock_timeout can also surface as 429 under contention. | Honor the Retry-After header, back off with jitter, and smooth the request rate. |
| 500 | internal_error | An error on Chargebee's side. It is rare. | Retry with backoff, and contact Chargebee support if it persists. |
Chargebee serves a single stable version of its API, v2, and ships dated, backward-compatible changes through its API changelog rather than minting new version numbers.
Chargebee serves a single stable version, v2, at https://{site}.chargebee.com/api/v2, superseding the earlier v1. There is no dated API version string to pin. Backward-compatible changes, like new parameters, resources, and event types, ship through dated entries in the API changelog. The dates below are recent changelog cuts, newest first.
A backward-compatible dated update to the v2 API.
A backward-compatible dated update to the v2 API.
A backward-compatible dated update to the v2 API.
A backward-compatible dated update to the v2 API.
Build against v2 and adopt new dated changes as they ship.
Chargebee API changelog ↗Bollard AI sits between a team's AI agents and Chargebee. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.