# Asynchronous API

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


**Note:** The asynchronous API is only enabled for selected customers. To enable it for your site, [contact Chargebee Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=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](#required-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[](#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-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)).

### 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[](#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[](#example-request)

### Immediate HTTP response[](#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[](#integration-checklist)

-   Send `Prefer: respond-async` and a unique `chargebee-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-url` header with your callback URL on every async call.
-   You can reuse the `chargebee-request-id` after two days.
-   Async submissions are deduplicated using the unique `chargebee-request-id`, not [idempotency keys](/docs/api/idempotency). If you send a `chargebee-idempotency-key`, it is echoed back in `request.idempotency_key` as metadata but is not used for deduplication.

## Asynchronous API attributes

## Input Parameters

- `api_version` (optional, string, max chars=10)
  The Chargebee API version used for the original request. For example, `v2`.

- `created_at` (optional, timestamp(UTC) in seconds)
  Timestamp at which the async request was accepted and queued by Chargebee.

- `completed_at` (optional, timestamp(UTC) in seconds)
  Timestamp at which the async operation finished processing (success or failure).

- `status` (required, enumerated string)
  Current completion status of the async operation.
  Possible enum values:
    - `success`
      The operation completed successfully. The `result` object contains the API response.
    - `failed`
      The operation failed after being accepted for async processing. The `error_detail` object contains failure information.

- `result` (optional, jsonobject)
  Returned only when `status` is `success`. Contains the same response structure that the synchronous version of the API operation would have returned. For example, if the original request created a credit note, `result` contains a `credit_note` object.

- `request` (optional, request_async_api)
  Object containing metadata about the original API request that was submitted asynchronously.
  - `id` (required, string, max chars=100)
    The unique identifier you provided in the `chargebee-request-id` header of the original async request.
  - `resource` (optional, string, max chars=100)
    The API resource targeted by the original request. For example, `credit_note` or `invoice`.
  - `operation_type` (optional, string, max chars=100)
    The operation type of the original request. For example, `create_credit_note` or `void_invoice`.
  - `method` (optional, string, max chars=10)
    The HTTP method of the original request. For example, `POST`.
  - `uri` (optional, string, max chars=512)
    The request URI of the original API call. For example, `/api/v2/credit_notes`.
  - `idempotency_key` (optional, string, max chars=250)
    The `chargebee-idempotency-key` sent in the original request, if any. This value is echoed back as metadata only; async submissions are deduplicated using the unique `chargebee-request-id`, not the idempotency key.

- `error_detail` (optional, error)
  Returned when `status` is `failed`. Contains information about why the operation failed.
  - `message` (optional, string, max chars=500)
    A human-readable description of the error.
  - `type` (optional, string, max chars=100)
    The category of the error. For example, `invalid_request`.
  - `api_error_code` (optional, string, max chars=100)
    A Chargebee-defined [error code](/docs/api/error-handling) identifying the specific error. For example, `resource_not_found`.
  - `error_code` (optional, string, max chars=100)
    An additional error code associated with the failure, when available.
  - `error_msg` (optional, string, max chars=250)
    An additional error message associated with the failure, when available.
  - `http_status_code` (optional, string, max chars=100)
    The HTTP status code that the synchronous version of the API operation would have returned for this failure.