Recorded purchases

Important

Record purchase operations are asynchronous, as they involve validating the purchase with the respective source, like Apple and Google.
This resource is applicable for Apple App Store and Google Play Store.

The recorded purchase resource represents a background job of syncing in-app purchases made through external storefronts like Apple and Google with Chargebee. The status (in_process, completed, and failed) attribute represents the current status of the background job.

Record Apple and Google In-App Purchases and Retrieve Associated Omni-Subscription and Transaction from Chargebee

You can record in-app subscription purchases made on the Apple App Store in Chargebee using the transaction[id] or using receipt and product[id] received after a successful purchase.

To record the purchase and retrieve subscription details, follow these steps:

Use the Record a Purchase API to record a subscription purchase made in in Apple App Store or Google Play Store.
- Record an Apple App Store purchase using transaction id with the app_id, customer[id] and transaction[id].
- Record an Apple App Store purchase using receipt with the app_id, customer[id], receipt and product[id].
- Record a Google Play Store one time order or subscription purchase with the app_id, customer[id] and order_id (Recommended).
- Record a Google Play Store subscription purchase with the app_id, customer[id] and purchase_token.
- Record a Google Play Store one time order purchase with the app_id, customer[id], purchase_token and product_id.
The API response will include a recorded_purchase object containing the status of the purchase recording job.
Once the purchase is successfully recorded, the status attribute of the recorded_purchase object updates from in_process to completed. At this point, Chargebee creates an omnichannel_subscription resource and triggers an omnichannel_subscription_created webhook event, which contains the omnichannel_subscription and omnichannel_transaction objects.
In addition to using Webhooks (push-based), you can retrieve details for a recorded purchase by using the recorded purchase resource's ID, which is returned when you record the purchase.

Sample Recorded purchaseJSON

Recorded purchases attributes

required, string, max chars=40

A unique ID generated by Chargebee for the recorded purchase.

customer_id

required, string, max chars=100

The id of the customer object that is associated with this purchase. If the customer_id is not present in Chargebee when the record_a_purchase API request is made, the API will return an error. Use create_a_customer API to create a customer.

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.

apple_app_store

When source of the application is Apple App Store

google_play_store

When source of the application is Google Play Store

status

required, enumerated string

Current status of the recorded purchase operation

in_process

When the purchase recording job is in progress. In this state you will not receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.

completed

When the purchase recording job status is complete. You will receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.

failed

When the purchase recording job is failed. In this state you will not receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object. Check the error_detail attribute to understand the reason for failure.

ignored

When the purchase recording job is initiated for an omnichannel subscription that already exists in Chargebee.

omnichannel_transaction_id

optional, string, max chars=100

The id of the omni transaction object associated with the purchase.

created_at

required, timestamp(UTC) in seconds

Indicates timestamp when the recorded_purchase resource is 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

optional, list of linked_omnichannel_subscription

The list of omni subscriptions created in response for this purchase. Applicable only for subscription purchases.

linked_omnichannel_one_time_orders

optional, list of linked_omnichannel_one_time_order

The list of omnichannel one time orders created in response for this purchase. Applicable only for one time order purchases.

error_detail

optional, error_detail

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