Recorded purchases

API Version

Product Catalog

Library

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 purchase [ JSON ]

{
    "id": "__test__rp_ASDsdfs123ld1",
    "app_id": "__test__aas_sdfwerzx5134",
    "customer_id": "__test__XpbTXGTSRp3gEsD8",
    "source": "apple_app_store",
    "status": "completed",
    "omnichannel_transaction_id": "__test__ot_LKedfs123ld1",
    "linked_omnichannel_subscriptions": [
        {
            "omnichannel_subscription_id": "__test__os_AHsdfs123ld1"
        }
    ],
    "created_at": 1517487053,
    "object": "recorded_purchase"
}

API Index URL

https://{site}.chargebee.com/api/v2/recorded_purchases

id

string, max chars=40
A unique ID generated by Chargebee for the recorded purchase.

customer_id

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

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

enumerated string
The source where the purchase is originally made and managed.

Possible values are

status

enumerated string
Current status of the recorded purchase operation

Possible values are

omnichannel_transaction_id

optional, string, max chars=100
The id of the omni transaction object associated with the purchase.

created_at

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
Show attributes [+]

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
Show attributes [+]

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
Show attributes [+]

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

id

string, max chars=40
A unique ID generated by Chargebee for the recorded purchase.

customer_id

app_id

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

enumerated string
The source where the purchase is originally made and managed.

Possible values are

status

enumerated string
Current status of the recorded purchase operation

Possible values are

omnichannel_transaction_id

optional, string, max chars=100
The id of the omni transaction object associated with the purchase.

created_at

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.

Try in API Explorer

The Record a Purchase API allows you to record in-app purchases made through channels such as the Apple App Store and Google Play Store in Chargebee. When you invoke this API, it initiates a purchase recording job and returns the recorded_purchase resource in the response. As part of the job, the API verifies the provided source specific request payload like transaction_id for Apple App Store or purchase_token for Google Play Store with the source such as apple_app_store or google_play_store respectively. If the verification is successful, the corresponding purchase is recorded in Chargebee. Upon completion, the recorded_purchase resource will include the relevant omnichannel_transaction_id and omnichannel_subscription_id.

Since this operation is asynchronous, you need to check the status attribute of the recorded_purchase resource to track the job status: in_process, completed, or failed.

Note: Upon successful completion of this asynchronous operation, Chargebee triggers the omnichannel_subscription_created event.

If the recorded_purchase status is failed, review the error_detail attribute and take corrective action to re-record the purchase.

You can use this API to record new and older purchases made on Apple App Store or Google Play Store by passing the transaction_id or purchase_token respectively received during the subscription purchase. You can record purchases for subscriptions that are in Active or Expired status.

Sample Request

Try in API Explorer

Only for Java

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/recorded_purchases \
     -u {site_api_key}:\
     -d app_id="__test__aas_sdfwerzx5134" \
     -d "customer[id]"="__test__XpbTXGTSRp3gEsD8" \
     -d "apple_app_store[transaction_id]"="20000006743"

curl  https://{site}.chargebee.com/api/v2/recorded_purchases \
     -u {site_api_key}:\
     -d app_id="__test__aas_sdfwerzx5134" \
     -d "customer[id]"="__test__XpbTXGTSRp3gEsD8" \
     -d "apple_app_store[receipt]"="Apple Based64 Encoded Receipt" \
     -d "apple_app_store[product_id]"="gold"

curl  https://{site}.chargebee.com/api/v2/recorded_purchases \
     -u {site_api_key}:\
     -d app_id="gp_app_16CbFOUcNBeJWc" \
     -d "customer[id]"="__test__XpbTXGTSRp3gEsD8" \
     -d "google_play_store[purchase_token]"="Google purchase token"

copy

Click to Copy

Record a purchase for apple app store using the apple_app_store[receipt]

Record a purchase for google play store using the google_play_store[purchase_token]

200:

STATUS

Sample Response [ JSON ]

{
    "recorded_purchase": {
        "id": "__test__rp_ASDsdfs123ld1",
        "app_id": "__test__aas_sdfwerzx5134",
        "customer_id": "__test__XpbTXGTSRp3gEsD8",
        "source": "apple_app_store",
        "status": "completed",
        "omnichannel_transaction_id": "__test__ot_LKedfs123ld1",
        "linked_omnichannel_subscriptions": [
            {
                "omnichannel_subscription_id": "__test__os_AHsdfs123ld1"
            },
            {..}
        ],
        "created_at": 1517487053,
        "object": "recorded_purchase"
    },
    "customer": {
        "id": "__test__XpbTXGTSRp3gEsD8",
        "first_name": "John",
        "last_name": "Doe",
        "email": "jonhdoe@example.com",
        "created_at": 1612890916,
        "updated_at": 1612890916,
        "object": "customer"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/recorded_purchases

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.

customer

Parameters for customer
pass parameters as customer[<param name>]

customer[id]

required, string, max chars=50

apple_app_store

Parameters for apple_app_store
pass parameters as apple_app_store[<param name>]

apple_app_store[transaction_id]

required if the source is apple_app_store and apple_app_store[receipt] is not provided, string, max chars=100

apple_app_store[receipt]

required if the source is apple_app_store and apple_app_store[transaction_id] is not provided, string, max chars=65k

apple_app_store[product_id]

required if the source is apple_app_store and apple_app_store[receipt] is provided, string, max chars=255

google_play_store

Parameters for google_play_store
pass parameters as google_play_store[<param name>]

google_play_store[purchase_token]

required if the source is google_play_store and google_play_store[order_id] is not provided, string, max chars=500

google_play_store[product_id]

required if the source is google_play_store, and if its a one-time order and google_play_store[order_id] is not provided, string, max chars=255

google_play_store[order_id]

required if the source is google_play_store and google_play_store[purchase_token] is not provided, string, max chars=100

omnichannel_subscription

Parameters for omnichannel_subscription
pass parameters as omnichannel_subscription[<param name>]

omnichannel_subscription[id]

optional, string, max chars=50

recorded_purchase

always returned
Resource object representing recorded_purchase

customer

always returned
Resource object representing customer

Try in API Explorer

The Retrieve a Recorded Purchase API retrieves a recorded_purchase object using the recorded_purchase.id returned in the response of the Record a Purchase API. You can use this API to check if the purchase was successfully recorded in Chargebee and to obtain the omnichannel_transaction_id and omnichannel_subscription_id associated with the successfully recorded purchase.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/recorded_purchases/__test__rp_ASDsdfs123ld1 \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "recorded_purchase": {
        "id": "__test__rp_ASDsdfs123ld1",
        "app_id": "__test__aas_sdfwerzx5134",
        "customer_id": "__test__XpbTXGTSRp3gEsD8",
        "source": "apple_app_store",
        "status": "in_process",
        "created_at": 1517487053,
        "object": "recorded_purchase"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/recorded_purchases/{recorded-purchase-id}

recorded_purchase

always returned
Resource object representing recorded_purchase

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

Sample recorded purchase [ JSON ]

API Index URL

Model Class

Recorded purchase attributes

Consent Fields for Recorded purchase

Custom Fields for Recorded purchase

Record a purchase ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a recorded purchase ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL