API Version
Product Catalog
Library

Important:

These APIs operate asynchronously. When you receive a successful response code from an API call, it indicates only the successful submission of your request, not the completion of the operation.

Using In-app Subscriptions, you can track subscriptions you sell and service via in-app purchase channels such as Apple's App Store and Google's Play Store. Call this API to notify Chargebee of new subscription purchases. Chargebee responds by creating corresponding subscriptions. You can make the API call directly from the client-side application or from your server. In the case of the Apple App Store and Google Play Store integration, you can also configure Chargebee to receive server notifications from Apple and Google to keep subscriptions up-to-date.

Note:

  • Only one app can be connected to any given Chargebee site via Chargebee's user interface. To connect multiple apps contact support . 
  • After creating a subscription in Chargebee using the process purchase command API, Chargebee manages it in real-time using notification events from Apple or Google. To enable these notifications, generate a notification URL using these links - Apple and Google and configure it in their respective stores.

In-app subscriptions are read-only

The subscriptions created via the Process Purchase Command API are managed by Apple or Google in response to actions taken by your subscribers via their respective accounts. Chargebee only keeps track of these subscriptions: creating and modifying them in response to events happening against the original subscriptions. Consequently, these subscriptions cannot be modified by you via the Chargebee admin console or the Subscriptions API.

Sample in app subscription [ JSON ]

{ "subscription_id": "1000000807994664", "customer_id": "customer-123", "plan_id": "app_store_plan_id-USD" }

API Index URL GET

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

Model Class

subscription_id
string, max chars=100
The id of the subscription for which the receipt was sent.
customer_id
optional, string, max chars=100
The id of the customer object to which the subscription belongs.
plan_id
optional, string, max chars=100
The id of the plan-item price of the subscription.
store_status
optional, enumerated string
The status of the subscription for the store
Possible values are
in_trialWhen the subscription is in trial.activeWhen the subscription is active.cancelledWhen the subscription is cancelled.pausedWhen the subscription is paused.
Show all values[+]
invoice_id
optional, string, max chars=100
The id of the invoice generated in Chargebee
subscription_id subscription_id
string, max chars=100
The id of the subscription for which the receipt was sent.
customer_id customer_id
optional, string, max chars=100
The id of the customer object to which the subscription belongs.
plan_id plan_id
optional, string, max chars=100
The id of the plan-item price of the subscription.
store_status store_status
optional, enumerated string
The status of the subscription for the store
invoice_id invoice_id
optional, string, max chars=100
The id of the invoice generated in Chargebee

Verifies an in-app purchase made by your customer and creates a subscription in Chargebee.

Note:

if App Store or Play Store products have not been imported to Chargebee and this API is invoked, Chargebee will automatically create plans that correspond to the store product IDs. However, if historical subscriptions are to be imported using the import receipt API, importing products is mandatory. Learn more.

This section provides details of the Process Purchase Command operation when performed for the Apple App Store. This API processes only the latest in-app transaction on the receipt. Sync historical subscriptions into Chargebee using bulk import of In-App Purchase receipts.

Important
  • Integrate Chargebee with your Apple App Store account using your shared secret from Apple.
  • It is strongly recommended to use this endpoint to notify Chargebee of new purchases only.
  • For updates to existing subscriptions, we recommend that you configure Apple App Store to send server notifications to Chargebee.

Chargebee validates the receipt with Apple App Store and does the following once validation succeeds:

  1. Look for item_family.id that matches the value Apple-App-Store, and create such a product family if not found.
  2. Look for item.id that matches product[id] and if not found, create such a plan-item under the item family described in the previous step.
  3. Look for item_price.id that matches the concatenation of product[id] and product[currency_code], and if not found, create such an item price under the item described in the previous step.
  4. Create/update a subscription:
    • If the receipt is for a new purchase, a new subscription is created for the plan-item price described in the previous step. The subscription has the following details:
    • Instead, if the receipt belongs to an existing subscription in Chargebee, it is updated to reflect the current state of the subscription at Apple.
  5. The payment is recorded against the subscription invoice. The associated transaction is updated with the following details:

This section provides details of the Process Purchase Command operation when performed for the Google Play Store. This API processes only the latest in-app transaction using the purchase token.

Important
  • Integrate Chargebee with your Google Play Store account using the service account credentials JSON.
  • It is strongly recommended to use this endpoint to notify Chargebee of new purchases only.
  • For updates to existing subscriptions, we recommend that you configure Chargebee to receive Google’s server notifications through pub/sub topic. Learn more.

Chargebee validates the purchase token with Google Play Store and does the following once validation succeeds:

  1. Look for item_family.id that matches the value Google-Play-Store, and create such a product family if not found.
  2. Look for item.id that matches product[id] and if not found, create such a plan-item under the item family described in the previous step.
  3. Look for item_price.id that matches the concatenation of product[id] and priceCurrencyCode, and if not found, create such an item price under the item described in the previous step.
  4. Create/update a subscription:
    • If this token is for a new purchase, a new subscription is created for the plan-item price described in the previous step. The subscription has the following details:
      • id set to unique identifier generated by Chargebee and mapped to token of the SubscriptionPurchase object from Google response.
      • start_date set to SubscriptionPurchase.startTimeMillis.
      • current_term_end set to SubscriptionPurchase.expiryTimeMillis.
    • Instead, if the token belongs to an existing subscription in Chargebee, it is updated to reflect the current state of the subscription at Google.
  5. The payment is recorded against the subscription invoice. The associated transaction is updated with the following details:

Path Parameter

{in_app_subscription_app_id}: The handle created by Chargebee for your Apple App Store or Google Play Store app. It can be obtained from the Chargebee web app.

The following are instructions to obtain the value of the path parameter for the Apple App Store and Google Play Store.

  • Apple App Store: To obtain the value for {in_app_subscription_app_id}, click View Keys within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.
  • Google Play Store: To obtain the value for {in_app_subscription_app_id}, click Set up notifications within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.

Notes

Sample Request
# Create an In app subscription for Apple App Store
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/process_purchase_command \
     -u {site_api_key}:\
     -d receipt="Apple Based64 Encoded Receipt" \
     -d product[id]="app_store_plan_id" \
     -d product[price]="3399" \
     -d product[price_in_decimal]="33.99" \
     -d product[currency_code]="USD" 
     -d customer[id]="customer-123"
# Create an In app subscription for Google Play Store
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/process_purchase_command \
     -u {site_api_key}:\
     -d receipt="Google purchase token" \
     -d product[id]="play_store_plan_id" 
     -d customer[id]="customer-123"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "in_app_subscription": {
        "subscription_id": "1000000807994664",
        "customer_id": "customer-123",
        "plan_id": "app_store_plan_id-USD"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/in_app_subscriptions/{in-app-subscription-app-id}/process_purchase_command

Method

receipt[]
required, string, max chars=65k

Apple App Store: The Base64 encoded App Store in-app purchase receipt taken from the Apple device after successful creation of the in-app purchase subscription.

Google Play Store: The purchase token taken from the Android device after the successful creation of an in-app purchase subscription.

product[id]
required, string, max chars=96
product[currency_code]
required, string, max chars=3
product[price]
required, in cents, min=0
product[name]
optional, string, max chars=46
product[price_in_decimal]
optional, string, max chars=39
product[period]
optional, string, max chars=3
product[period_unit]
optional, string, max chars=3
customer[id]
optional, string, max chars=50
customer[email]
optional, string, max chars=70
customer[first_name]
optional, string, max chars=150
customer[last_name]
optional, string, max chars=150
in_app_subscription in_app_subscription
always returned
Resource object representing in_app_subscription

Sample admin console URL

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

Verifies an Apple App Store or Google Play Store in-app purchase receipt and imports subscriptions for all historical purchases made by the customer.

Tip

An in_app_subscription is created for every unique original_transaction_id. Apple creates original_transaction_id for every create, upgrade, or downgrade of the subscription. A receipt hardly contains more than 100 original_transaction_ids. If a receipt contains more than 100 original_transaction_ids, Chargebee creates all subscription records but this endpoint returns the first 100 records in the response.

CSV upload has a file size limitation that increases the processing time and the number of receipts. This API removes such limitations and allows you to import historical in-app subscription receipts.

Note: This API verifies receipt or token through Apple or Google and then processes them via Chargebee. For bulk imports, limit API calls to 6 per minute (10 seconds apart) to ensure successful subscription imports.

This section provides details of the Import Receipt operation performed for the Apple App Store. This API processes only the historical in-app transaction receipts.

Important
  • Integrate Chargebee with your Apple App Store account using your shared secret from Apple.
  • It is strongly recommended to use this endpoint to import historical in-app subscriptions only.
  • You must import Apple App Store products using Chargebee's user interface before importing receipts using this API.

Chargebee validates the receipt with Apple App Store and does the following once validation succeeds:

Subscriptions

Subscriptions are imported as follows:

  1. A subscription is imported for every unique value of the original_transaction_id in the Apple receipt.
    Note: This is not done for original_transaction_ids for which a subscription already exists in Chargebee.
  2. Each subscription imported has the following attributes set:
    • id set to original_transaction_id.
    • start_date set to the earliest purchase_date_ms.
    • current_term_start set to latest purchase_date_ms.
    • current_term_end set to expires_date_ms of the same Latest_receipt_info element with the latest purchase_date_ms.
    • item_price_id set to product_id.
    • status set to in_trial if there is only one element of Latest_receipt_info with the original_transaction_id and the field is_trial_period is true, then consider the subscription is currently in trial. No invoices are created for this subscription.

Invoices for the subscription

Invoices are imported as follows:

  1. An invoice is imported to Chargebee for every element of the array Latest_receipt_info which has is_trial_period as false.
  2. Each imported invoice has the subscription_id set to original_transaction_id.

Transactions for the invoices

A transaction is imported for each invoice with the following details:

  1. reference_number set to the transaction_id.
  2. payment_method set to apple_store.


This section provides details of the Import Receipt operation performed for the Google Play Store. This API is used to process only the historical in-app purchase subscriptions.

Important
  • Integrate Chargebee with your Google Play Store account using your service account credentials JSON
  • It is strongly recommended to use this endpoint to import historical in-app subscriptions only. 
  • It is recommended to pass only the latest purchase token. If any other purchase token is passed instead of the latest one, there is a possibility of returning incorrect transaction details. If an expired purchase token is passed, then it returns an error.
  • The Google purchase token is valid from subscription signup until 60 days after subscription expiration. After the token expires, an API request to Google Developers API returns an error. 

Chargebee validates the purchase token with Google Play Store and does the following once validation succeeds:

Subscriptions

  • A subscription is imported for every unique purchase token if it is not linked to an existing purchase token( linkedPurchaseToken field in SubscriptionsV2.get API Response).

  • Each subscription imported has the following attributes set:

    • id set to a unique identifier generated by Chargebee and mapped to the token and latestOrderId of the SubscriptionPurchaseV2 object from Google response.

    • start_date set to the earliest SubscriptionPurchaseV2.startTime.

    • current_term_start set to latest SubscriptionPurchaseV2.startTime.

    • current_term_end set to expiryTime of the same SubscriptionPurchaseV2 element with the latest purchase.

    • item_price_id set to the concatenation of product[id] and priceCurrencyCode from Google.

    • status set to in_trial if the free trial configuration is enabled in Google and the monetization.subscriptions.basePlans.offers.State is Active with a SubscriptionOfferPhase.duration, then consider the subscription is currently in trial. No invoices are created for this subscription. 

Invoices for the subscription

Invoices are imported as follows:

  • An invoice is imported to Chargebee for every new subscription and renewal of an existing subscription using latestOrderId.

  • Each imported invoice has the subscription_id set to a unique identifier generated by Chargebee and mapped to the token and latestOrderId.

Transactions for the invoices

A transaction is imported for each invoice with the following details:

  • transaction.reference_number is set to the latestOrderId.

  • transaction.payment_method is set to play_store

Path Parameter

{in_app_subscription_app_id}: The handle created by Chargebee for your Apple App Store or Google Play Store app. It can be obtained from the Chargebee web app.

The following are instructions to obtain the value of the path parameter for the Apple App Store and Google Play Store.

  • Apple App Store: To obtain the value for {in_app_subscription_app_id}, click View Keys within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.
  • Google Play Store: To obtain the value for {in_app_subscription_app_id}, click Set up notifications within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.


Notes

Sample Request
# Import In app subscriptions for Apple App Store
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_receipt \
     -u {site_api_key}:\
     -d receipt="Apple Based64 Encoded Receipt" \
     -d product[currency_code]="USD" 
     -d customer[id]="customer-123" \
     -d customer[email]="customer@test.com"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "in_app_subscriptions": [
        {
            "subscription_id": "2000000018428922",
            "customer_id": "customer-123",
            "plan_id": "app_store_plan_id_1-USD"
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/in_app_subscriptions/{in-app-subscription-app-id}/import_receipt

Method

receipt[]
required, string, max chars=65k

Apple App Store: The Base64 encoded App Store in-app purchase receipt taken from the Apple device after successful creation of the in-app purchase subscription.

Google Play Store: The purchase token taken from the Android device after the successful creation of an in-app purchase subscription.

product[currency_code]
required, string, max chars=3
customer[id]
optional, string, max chars=50
customer[email]
optional, string, max chars=70
in_app_subscriptions in_app_subscriptions
always returned
Resource object representing in_app_subscriptions

Sample admin console URL

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

The Import Subscriptions endpoint is a Chargebee API that allows you to import historic In-App Subscriptions without using a valid Apple App Store receipt. This endpoint is useful if you do not have access to the receipt data which is required for the Import Receipt API.

With this API, you can import subscriptions and corresponding invoices for historic In-App purchases. The API returns the in-app-subscriptions object once the historic subscription is successfully imported into Chargebee.

Note:
  • Subscriptions cannot be imported from the Google Play Store without a receipt or token. Therefore; Chargebee does not allow you to use this API for the Google Play Store.
  • Enable V1 notifications in the Apple App Store for subscriptions created without receipts. Chargebee depends on receipt data to update subscription statuses. Apple’s V2 notifications do not have receipt information; therefore, Chargebee cannot process V2 notifications for subscriptions imported without receipts. Learn more about app store notifications and notification URL configuration.

Apple App Store

This section provides details of the Import Subscription operation when performed for the Apple App Store. This API creates a historic subscription if the incoming subscription is unknown. For a known subscription, it creates an invoice for the mentioned period.

Important

  • Integrate Chargebee with your Apple App Store account using your shared secret from Apple. 

  • It is strongly recommended to use this endpoint to create a historic In-App subscription only. 

  • You must import App Store products using Chargebee’s user interface before importing receipts using this API.

Chargebee validates the application ID with Apple App Store and does the following once validation succeeds:

Subscription

  1. Import the subscription from the latest_receipt_info array from Apple and a new subscription is imported for the item-price. 
    Note: The subscription is not imported if it already exists in Chargebee but we will import the associated invoice using the subscription[transaction_id] in the payload. 

  2. Each subscription imported has the following attribute set:

    • id set to subscription[id] . This subscription[id] is  original_transaction_id in the receipts.

    • start_date set to subscription[start_date]. You need to provide this information from the oldest Latest_receipt_info.purchase_date_ms.

    • term_start set to subscription[term_start]. You need to provide this information from the oldest Latest_receipt_info.purchase_date_ms).

    • term_end set to subscription[term_end]. You need to provide this information from the oldest Latest_receipt_info.expires_date_ms.

    • item_price_id set to subscription[product_id] + subscription[currency_code]. You need to provide this information from the Latest_receipt_info.product_id.

    • Chargebee records the subscription in a Trial state if the is_trial_period is true.

    • Chargebee records the subscription in a Canceled state if the term_end is less than the System.currentTime().

Invoice for the subscription

  1. The payment is recorded against the subscription invoice. 

    • Imported invoice has the subscription_id set to original_transaction_id.

Transactions for the invoice

  1. The associated transaction is updated with the following details:

    • The transaction.reference_number is set to the transaction_id of the payment.

    • The transaction.payment_method is set to apple_store.  

in_app_subscription_app_id
required, string

The handle created by Chargebee for your App Store app. It can be obtained from within the Chargebee web app. 

To obtain the value of in_app_subscription_app_id for the Apple App Store, click View Keys within the Sync Overview page of the web app, and use the value of generated App ID for this parameter. See detailed steps here.

Notes

Sample Request
# Imports an In app subscription for Apple App Store
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_subscription \
     -u {site_api_key}:\
     -d subscription[id]="460000725505054" \
     -d subscription[started_at]=1651363200 \
     -d subscription[term_start]=1651363200 \
     -d subscription[term_end]=1654041600 \
     -d subscription[product_id]="com.product.test" \
     -d subscription[currency_code]="USD" \
     -d subscription[transaction_id]="460000761293753" \
     -d subscription[is_trial]="false" 
     -d customer[id]="customer-123" \
     -d customer[email]="customer@test.com"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "in_app_subscription": {
        "subscription_id": "460000725505054",
        "customer_id": "customer-123",
        "invoice_id": "apple_460000761293753"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/in_app_subscriptions/{in-app-subscription-app-id}/import_subscription

Method

subscription[id]
required, string, max chars=50
subscription[started_at]
required, timestamp(UTC) in seconds
subscription[term_start]
required, timestamp(UTC) in seconds
subscription[term_end]
required, timestamp(UTC) in seconds
subscription[product_id]
required, string, max chars=96
subscription[currency_code]
required, string, max chars=3
subscription[transaction_id]
required, string, max chars=43
subscription[is_trial]
optional, boolean, default=false
customer[id]
optional, string, max chars=50
customer[email]
optional, string, max chars=70
in_app_subscription in_app_subscription
always returned
Resource object representing in_app_subscription

Sample admin console URL

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

This API verifies the application id {in_app_subscription_app_id} and receipt then returns the subscription details associated with the purchase.


in_app_subscription_app_id
required, string

The handle is created by Chargebee for your Apple App Store or Google Play Store app. It can be obtained from the Chargebee web app.

The following are instructions to obtain the value of the path parameter for the Apple App Store and Google Play Store.

  • Apple App Store: To obtain the value for {in_app_subscription_app_id}, click View Keys within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.
  • Google Play Store: To obtain the value for {in_app_subscription_app_id}, click Set up notifications within the Sync Overview page of the web app and use the value of generated App ID for this parameter. See detailed steps here.

Notes

Sample Request
# Retrieve subscription from the store using the receipt
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/retrieve \
     -u {site_api_key}:\
     -d receipt="Apple Based64 Encoded Receipt"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "in_app_subscriptions": [
        {
            "subscription_id": "2000000018428922",
            "plan_id": "app_store_plan_id_1",
            "store_status": "in_trial"
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/in_app_subscriptions/{in-app-subscription-app-id}/retrieve

Method

receipt[]
required, string, max chars=65k

Apple App Store: The Base64 encoded App Store in-app purchase receipt taken from the Apple device after successful creation of the in-app purchase subscription.

Google Play Store: The purchase token taken from the Android device after the successful creation of an in-app purchase subscription.

in_app_subscriptions in_app_subscriptions
always returned
Resource object representing in_app_subscriptions

Sample admin console URL

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