Settings
API Version
Product Catalog
Library

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:

  1. Use the Record a Purchase API to record a subscription purchase made in in Apple App Store or Google Play Store.

  2. The API response will include a recorded_purchase object containing the status of the purchase recording job.

  3. 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.

  4. 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 GET

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

Model Class

 

      Recorded purchase attributes
      
 
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 this app_id follow these steps. 
 
 
source
 

      enumerated string
 The source where the purchase is originally made and managed. 
 
Possible values are
 
 
apple_app_storeWhen source of the application is Apple App Storegoogle_play_storeWhen source of the application is Google Play Store
 
 Show all values[+]
 
status
 

      enumerated string
 Current status of the recorded purchase operation 
 
Possible values are
 
 
in_processWhen the purchase recording job is in progress. In this state you will not receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.completedWhen the purchase recording job status is complete. You will receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.failedWhen 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.ignoredWhen the purchase recording job is initiated for an omnichannel subscription that already exists in Chargebee.
 
 Show all values[+]
 
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.
 
 
 

      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 id
 

          string, max chars=40
 A unique ID generated by Chargebee for the recorded purchase. 
 
customer_id 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 app_id
 

          string, max chars=100
 App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get this app_id follow these steps. 
 
source source
 

          enumerated string
 The source where the purchase is originally made and managed. 
 
Possible values are
 
 
apple_app_storeWhen source of the application is Apple App Storegoogle_play_storeWhen source of the application is Google Play Store
 
 Show all values[+]
status status
 

          enumerated string
 Current status of the recorded purchase operation 
 
Possible values are
 
 
in_processWhen the purchase recording job is in progress. In this state you will not receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.completedWhen the purchase recording job status is complete. You will receive the omnichannel_transaction_id and linked_omnichannel_subscriptions object.failedWhen 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.ignoredWhen the purchase recording job is initiated for an omnichannel subscription that already exists in Chargebee.
 
 Show all values[+]
omnichannel_transaction_id omnichannel_transaction_id
 

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

          timestamp(UTC) in seconds
 Indicates timestamp when the recorded_purchase resource is created in Chargebee. 
 
resource_version 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. 
 
error_detail 
 

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

      Record a purchase
      
 
Idempotency Supported
 
 
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.
 
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
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
 
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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
    
 
Method
 
 
Input Parameters
 
  
 
app_id[]
 

      required, string, max chars=100 
 App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get this app_id follow these steps. 
 
 
 
 
 
customer[id]
 
required, string, max chars=50 
  
 
 
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 apple_app_store with receipt is provided, string, max chars=255 
  
 
 
google_play_store[purchase_token]
 
required if google_play_store is provided, string, max chars=500 
  
 
 
omnichannel_subscription[id]
 
optional, string, max chars=50 
  
   
 
Returns
 
recorded_purchase  recorded_purchase
 

      always returned 
 Resource object representing recorded_purchase
customer  customer
 

      always returned 
 Resource object representing customer
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/recorded_purchases/123x
    

      Retrieve a recorded purchase
      
  
 
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.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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}
    
 
Method
 
  
   
 
    
 
Returns
 
recorded_purchase  recorded_purchase
 

      always returned 
 Resource object representing recorded_purchase
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/recorded_purchases/123x