Chargebee API Docs: Where They Are and What to Read Before You Ship
The reference lives at apidocs.chargebee.com, with every resource, its parameters and sample code for each client library. Most of a first build follows from there. The parts that bite later sit in the events docs: webhooks can arrive out of order, the same one can arrive twice, and your handler has to cope with both.
Docs: apidocs.chargebee.com for the API reference and the event catalog. Chargebee also publishes an OpenAPI spec on its GitHub.
Base URL: https://{site}.chargebee.com/api/v2/, where {site} is your site name. Your test site is a separate site with its own keys.
Auth: HTTP Basic, with the API key as the username and no password, as in -u {site_api_key}:. Create keys under API Keys.
Requests: form-encoded in, JSON out, timestamps in Unix seconds. Lists return 10 records unless you set limit, up to 100.
429 Too many requests: you've hit the rate limit. Wait and retry. For 5xx errors, retry with exponential backoff.
From a fresh API key to a webhook you can trust
- 1
Pick the narrowest key that does the job
Full-access keys come as All, Update or Write. Read-only keys come as All or Restricted, which limits them to transactional data, the product catalog, or both. A publishable key is limited to browser-side calls such as checking out a subscription, and is the only type meant for use in a browser.
Watch for: reporting jobs running on a full-access key. A read-only key is enough and does less damage if it leaks.
- 2
Build against the test site
Keys belong to one environment, so the test site key won't work on live and the other way round. Keep them in separate config so a deploy can't mix them up.
- 3
Page through lists with next_offset
If a list response includes
next_offset, send it back asoffseton the next call. Stop when it's missing. A full sync of customers or subscriptions is a loop over that, at 100 per page. - 4
Add the webhook endpoint and protect it
Settings › Configure Chargebee › WebhooksChargebee posts JSON and counts a delivery as done only on a 2xx. Turn on basic auth for the URL, or put a long random key in its path. Reply fast and do the real work after.
Watch for: slow handlers. A timeout counts as a failure, and Chargebee retries failed deliveries. You can also resend from the web console.
- 5
Sort events by resource_version
Webhooks can arrive out of order. Each resource carries a
resource_version, a millisecond timestamp that changes on every update. Store the latest one you've applied and ignore anything older. - 6
Skip events you have already handled
Retries mean the same event can land twice. Save each event
idyou process and drop repeats. Chargebee's guidance is to keep those IDs for at least 3 days and 7 hours.Watch for: the
api_versionon each event. It's v1 or v2, and your handler should expect the version your client library uses.
Before the Chargebee handler takes live traffic
Does it confirm the event before acting on money?
Chargebee's docs suggest fetching the event again through the Retrieve an Event call. Worth doing before you cut off access or refund anything.
Can someone replay a day of missed events?
After an outage you'll want to reprocess without double-applying. That only works if the duplicate check above is in place.
Does a failure reach a person?
A handler that logs an error nobody reads is how a canceled customer keeps access for a month.
Is the live key read-only wherever it can be?
Only the code that writes subscriptions or invoices needs a full-access key.
Chargebee API docs: the short questions
Where do I find Chargebee's API documentation?
At apidocs.chargebee.com. It has the endpoint reference for customers, subscriptions, invoices, credit notes and the product catalog, the event and webhook docs, client library examples, and links to the OpenAPI spec.
Does Chargebee have webhooks?
Yes. Chargebee sends a webhook for each event, such as a payment failing or a subscription being canceled, to the endpoints you configure. They're posted as JSON, retried when your endpoint doesn't return a 2xx, and can arrive out of order or more than once.
Which version of the Chargebee API should new code use?
Version 2, which is what the /api/v2/ base URL and the current reference use. Events carry an api_version field, so check that your webhook handler and client library agree on it.
Does the Chargebee API support usage-based billing data?
Yes. There's a usages resource for recording metered usage against a subscription, and Chargebee uses those records when it bills a usage-based plan.
Can I pull invoice data out of Chargebee through the API?
Yes. The invoice and credit note endpoints return the full documents, line items included, and support paging with limit and offset. That's usually the data that gets mapped into an accounting system.
What the handler should do once an event is in
Receiving events is the plumbing. The useful part is deciding what each one changes: a failed renewal applying your own grace and lockout rules in the product, a plan change reaching the app and the CRM in the same pass, or usage from your product posted to Chargebee on schedule so the invoice is right.
Invoices and credit notes are the other common job. The API returns them in full, but they still have to be mapped to your chart of accounts before finance can use them. Generally that mapping is a decision for whoever closes the books, so check it with your accountant before it runs.