Getting started

Chargebee's API gives you programmatic control over every part of your billing stack — subscriptions, usage metering, invoicing, payments, and customer management. It's a REST API that uses HTTP Basic Auth, accepts form-encoded requests, and returns JSON.

Base URL:

Replace {site} with your Chargebee site name (e.g., acme-test).

Prerequisites

You need a Chargebee account with a test site. If you don't have one, sign up here — a test site is created automatically.

Get your API key

Log in to the Chargebee application.
Go to Settings > Configure Chargebee > API Keys and Webhooks.
Click the API Keys tab.
Click Add an API Key, select Full-Access Key, and give it a name.
Copy the key and store it securely.

API keys are environment-specific. Use the test site API key during development and switch to the live site API key for production use.

Make your first API call

Let us retrieve a list of customers. If your test site has no customers, the response returns an empty list. This confirms that your API setup is working.

Sample Result[JSON]

Understand the response

Key aspects of the response:

Envelope structure: All responses wrap resources in a container. Single resources are returned as { "customer": { ... } }. Lists are returned as { "list": [ ... ] }.
Pagination: If next_offset is present, additional results are available. Pass this value as the offset parameter in the next request to retrieve the next page. The default page size is 10. You can set limit to a maximum of 100.
Timestamps: All timestamps are in Unix epoch seconds (for example, 1620000000).

Create a customer

Let us now create a customer on your test site. When you pass parameters using -d, cURL sends a POST request automatically.

Sample Result[JSON]

Error handling

Chargebee APIs use standard HTTP status codes:

2xx — Success.
400 — Bad request. Check the error message in the response body.
401 — Authentication failed. Verify your API key.
404 — Resource not found.
429 — Too many requests. Retry after a delay.
5xx — Server error (rare). Retry with exponential backoff.

Error responses include a JSON body with api_error_code, message, and http_status_code to help you debug.

Build with AI tools

Agent Skills

If you're using AI coding tools like Claude Code or Cursor, the official Chargebee Agent Skills provide your coding agent with knowledge of the Chargebee API to generate integration code faster. Install via npx skills add chargebee/ai.

API Explorer

The API Explorer lets you make live API calls in a browser using a guided interface. Use it to test endpoints without writing code.

MCP Server

The Chargebee MCP server lets AI agents (Claude, Cursor, Windsurf, and others) interact with the Chargebee API directly via the Model Context Protocol. Use it to build agent workflows that manage billing operations.

HTTP methods

Chargebee APIs use the following HTTP methods:

GET — Read operations, such as retrieving or listing resources.
POST — Write operations, such as creating, updating, or deleting resources.

Authentication

All API requests use HTTP Basic Auth. Use your API key as the username. Leave the password empty.

Send all requests over HTTPS. Do not expose API keys in client-side code or public repositories.

Client libraries

Official open-source libraries that wrap the HTTP API:

Need support for another language? Contact dx@chargebee.com.

Using cURL

You can use cURL to test Chargebee API from a CLI. When you pass input parameters to the API using -d or --data-urlencode options, the HTTP POST method is used:

Framework adapters

Laravel Cashier for Chargebee

A first-party library for integrating Chargebee into Laravel apps. Handles subscriptions, trials, and invoices with an expressive API. See the repo, documentation, and starter kit.

Next.js Adapter

Includes a CLI to scaffold a Chargebee integration in a Next.js application. See the tutorial.

OpenAPI Specification

The full API specification is available as an OpenAPI v3.0.1 document. Use this specification with Swagger, Postman, or any tool that supports OpenAPI.

Testing your integration

The Time Machine feature lets you simulate time-based billing events on your test site. Use it to fast-forward subscriptions, trigger renewals, and verify that your integration handles the full lifecycle before going live.

Next steps

Browse the full API reference for detailed request and response examples for each endpoint.
Set up webhooks to receive real-time notifications when subscriptions, invoices, or payments change.
Explore sample apps and tutorials to learn common integration patterns.
Review the API Changelog for recent updates.
Join the Chargebee Developer Discord