Recorded purchases

Important

Handle the synchronous API response first. Record a Purchase can fail immediately (for example, an incorrect app_id, a malformed URL or request, or recording a purchase that already belongs to a different customer) before a job is created—treat these as standard API errors (4xx). To reassign an existing omnichannel subscription to another customer, use Move an omnichannel subscription instead of re-recording the purchase.
After the call is accepted, purchase validation with Apple or Google is asynchronous. Track the job with status (in_process → completed, failed, or ignored). Omnichannel subscription or one-time order creation happens only after successful async completion.
This resource is applicable for Apple App Store and Google Play Store.

The recorded purchase resource represents a background job that syncs in-app purchases made through Apple App Store and Google Play Store with Chargebee. The status (in_process, completed, failed, and ignored) attribute represents the current status of the background job.

Record Apple and Google in-app purchases and retrieve linked omnichannel resources

You can record subscription and one-time-order purchases made on Apple App Store or Google Play Store, then retrieve the resulting omnichannel resources.

To record a purchase and retrieve details, follow these steps:

Use the Record a Purchase API with app_id, customer[id], and exactly one store payload:
- Apple App Store (preferred): apple_app_store[transaction_id] for a new subscription, expired re-purchase, or one-time product.
- Apple App Store (receipt path): apple_app_store[receipt] and apple_app_store[product_id].
- Google Play Store (preferred): google_play_store[order_id] for a subscription or one-time order.
- Google Play Store (subscription token path): google_play_store[purchase_token].
- Google Play Store (one-time order token path): google_play_store[purchase_token] and google_play_store[product_id].
The API response includes a recorded_purchase object with the status of the job.
When recording completes successfully, status updates from in_process to completed and Chargebee sets omnichannel_transaction_id plus either:
- Subscription: linked_omnichannel_subscriptions, with webhook omnichannel_subscription_created (or omnichannel_subscription_imported).
- One-time order: linked_omnichannel_one_time_orders, with webhook omnichannel_one_time_order_created.
In addition to webhooks, retrieve the job by the recorded_purchase id returned when you record the purchase.

If status is failed, review error_detail and see record_purchase_failed.

If status is ignored, the purchase was already recorded in Chargebee as an omnichannel subscription or one-time order. Chargebee does not create a new linked resource for this job—use the existing omnichannel subscription or one-time order. Linked IDs and omnichannel_transaction_id are populated when status is completed, not for ignored.

Sample Recorded purchaseJSON

Recorded purchases attributes

required, string, max chars=40

A unique ID generated by Chargebee for the recorded purchase job.

customer_id

required, string, max chars=100

The id of the customer object associated with this purchase. If the customer_id is not present in Chargebee when the record_a_purchase API request is made, Chargebee automatically creates the customer using the details provided in the request.

app_id

required, string, max chars=100

App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:

For Apple, follow these steps.
For Google, follow these steps.

source

required, enumerated string

The source where the purchase is originally made and managed.

Enum Values

apple_app_store

The purchase originated from the Apple App Store.

google_play_store

The purchase originated from the Google Play Store.

status

required, enumerated string

Current status of the recorded purchase operation.

Enum Values

in_process

The purchase recording job is in progress. You do not yet receive omnichannel_transaction_id or linked subscription / one-time-order objects.

completed

The purchase recording job completed successfully. You receive omnichannel_transaction_id and either linked_omnichannel_subscriptions (subscription purchase) or linked_omnichannel_one_time_orders (one-time order purchase).

failed

The purchase recording job failed. You do not receive omnichannel_transaction_id or linked subscription / one-time-order objects. Check the error_detail attribute for the failure reason. Chargebee may also emit record_purchase_failed.

ignored

Terminal status when the purchase was already recorded in Chargebee as an omnichannel subscription or one-time order (same store purchase / customer association). Chargebee does not create a new linked resource for this job. Use the existing omnichannel subscription or one-time order in Chargebee rather than treating this job as a new successful recording. linked_omnichannel_subscriptions / linked_omnichannel_one_time_orders and omnichannel_transaction_id are returned when status is completed, not for ignored.

omnichannel_transaction_id

optional, string, max chars=100

The id of the omnichannel transaction object associated with the purchase. Present when status is completed.

created_at

required, timestamp(UTC) in seconds

Timestamp when the recorded_purchase resource was created in Chargebee.

resource_version

optional, long

Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.

linked_omnichannel_subscriptions

The list of omnichannel subscriptions created for this purchase. Applicable when the recorded purchase is a subscription. Present when status is completed.

linked_omnichannel_one_time_orders

The list of omnichannel one-time orders created for this purchase. Applicable when the recorded purchase is a one-time order. Present when status is completed.

error_detail

Applicable only for recorded purchases where the job status is failed. It provides more details about the failure.