# Getting started

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](https://www.chargebee.com/trial-signup/) — a test site is created automatically.

### Get your API key[](#get-your-api-key)

1.  Log in to the [Chargebee application](https://app.chargebee.com/login).
2.  Go to **Settings > Configure Chargebee > API Keys and Webhooks**.
3.  Click the **API Keys** tab.
4.  Click **Add an API Key**, select **[Full-Access Key](https://www.chargebee.com/docs/billing/2.0/site-configuration/api_keys#full-access-key)**, and give it a name.
5.  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.

## 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.

## 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[](#agent-skills)

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

### API Explorer[](#api-explorer)

The [API Explorer](https://api-explorer.chargebee.com) lets you make live API calls in a browser using a guided interface. Use it to test endpoints without writing code.

### MCP Server[](#mcp-server)

The [Chargebee MCP server](https://www.chargebee.com/docs/billing/2.0/ai-in-chargebee/chargebee-mcp) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme). 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

Chargebee maintains official client libraries for Node, Python, PHP, Java, Go, Ruby, and .NET, along with framework adapters for Laravel and Next.js. See [Client Libraries](/docs/sdks) for installation instructions, code samples, and links to each repository.

Need support for another language? Contact [dx@chargebee.com](mailto:dx@chargebee.com).

## OpenAPI Specification

The full API specification is available as an [OpenAPI v3.0.1 document](https://github.com/chargebee/openapi). Use this specification with Swagger, Postman, or any tool that supports OpenAPI.

## Postman collection

The [Chargebee workspace](https://www.postman.com/chargebee/chargebee-api/overview) on the Postman API Network publishes every API operation as a collection. Each request carries the sample request shown in this reference, along with Node, PHP, Python, and cURL code.

Each button below forks one collection plus the **Chargebee Test Site** environment into your own workspace. Fill in `site` and `api_key` in that environment, and the requests are ready to send.

**Get Started with Chargebee** walks you from your first call to a live subscription:

[![Run Get Started with Chargebee in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/58333841-1d72f1fc-199d-4030-99f2-244d932c1312?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D58333841-1d72f1fc-199d-4030-99f2-244d932c1312%26entityType%3Dcollection%26workspaceId%3D0c650405-4076-4f5d-b08b-a36810f39531&environment=58333841-a6958e44-b902-4924-a835-af69b0f756e4)

**Chargebee API** is the full reference — one folder per resource, to browse rather than run end to end:

[![Run the Chargebee API collection in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/58333841-180f3f22-7497-484d-83c7-f5fc205cb2ea?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D58333841-180f3f22-7497-484d-83c7-f5fc205cb2ea%26entityType%3Dcollection%26workspaceId%3D0c650405-4076-4f5d-b08b-a36810f39531&environment=58333841-a6958e44-b902-4924-a835-af69b0f756e4)

The workspace also has **Chargebee Usage-Based Billing** for metering and overage, and **Chargebee Time Machine** for simulating renewals on a test site.

## Testing your integration

The [Time Machine](/docs/api/time_machines) 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](/docs/api/events) to receive real-time notifications when subscriptions, invoices, or payments change.
-   Explore [sample apps and tutorials](https://www.chargebee.com/tutorials) to learn common integration patterns.
-   Review the [API Changelog](https://www.chargebee.com/help/api-updates/) for recent updates.
-   Join the Chargebee [Developer Discord](https://discord.gg/nEtpvhqzG3)