Note: The asynchronous API is only enabled for selected customers. To enable it for your site, contact Chargebee Support.
The Chargebee asynchronous API allows selected API operations to be executed in the background. Instead of waiting for the operation to complete within the same HTTP request, the API immediately acknowledges the request and processes it asynchronously.
Your application sends the same API request it would use for a synchronous call, but with special headers. Chargebee responds immediately with HTTP 202 Accepted and an empty response body, meaning the work has been accepted and will run in the background.
When processing finishes (success or failure), Chargebee delivers the outcome to the callback URL provided in the request header. The callback payload contains the async_response object described below.
Both synchronous and asynchronous requests use the same API endpoints and request payloads. The distinction is defined solely by the request headers.
Required headers
| Header | Purpose |
| Prefer: respond-async | Required. Tells Chargebee to process the request asynchronously and return 202 Accepted. |
| chargebee-request-id | Required. Your unique id for this async api (see chargebee-request-id). |
| chargebee-async-callback-url | Required. The callback URL where Chargebee will POST the result. Must be in the format: https://username:password@example.com (see async-api-callback). |
Async API callback
You must provide a callback URL in the chargebee-async-callback-url header for every async API request. Chargebee delivers the outcome (success or failure) to this URL when asynchronous processing completes. Ensure the provided URL is a stable HTTPS endpoint.
The response is a list envelope:
When status is failed, result is omitted and error_detail is included instead.
Chargebee Request Id
This header is the primary key for your async job.
| Topic | Detail |
| Purpose | Uniquely identifies one async submission so you can match the eventual callback to the originating call. |
| Required | Omitting it or sending a blank value results in an invalid request error. |
| Max length | 100 characters. |
| Uniqueness | Must be unique. Reuse is allowed after two days. |
| Recommended format | A UUID (36 characters) or another opaque string within the length limit. Avoid personally identifiable information. |
| Correlation in callback | The callback includes the same value as request.id inside the async_response object. |
Example request
Immediate HTTP response
202 Accepted— The request is queued. The response body is empty; treat acceptance as successful handoff. Final success or failure is delivered only via your async callback.4xx— Validation, authentication, or other immediate errors are returned synchronously (no async queueing).
Integration checklist
- Send
Prefer: respond-asyncand a uniquechargebee-request-id(≤ 100 chars) on every async call. - Handle
202— do not expect the final resource in the immediate HTTP response. - Pass the
chargebee-async-callback-urlheader with your callback URL on every async call. - You can reuse the
chargebee-request-idafter two days. - Async submissions are deduplicated using the unique
chargebee-request-id, not idempotency keys. If you send achargebee-idempotency-key, it is echoed back inrequest.idempotency_keyas metadata but is not used for deduplication.
API Index URL
Asynchronous API attributes
Current completion status of the async operation.
The operation completed successfully. The result object contains the API response.
The operation failed after being accepted for async processing. The error_detail object contains failure information.