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

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