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.
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.
{
"subscription_id": "1000000807994664",
"customer_id": "customer-123",
"plan_id": "app_store_plan_id-USD"
}
Verifies an in-app purchase made by your customer and creates a subscription in Chargebee.
Tip
The recommended approach is to call this endpoint from the client-side app directly. However, if you are using this API to replace an existing direct integration with Apple or Google, then you may choose to call this API from the server-side.
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.
Chargebee validates the receipt
with Apple App Store and does the following once validation succeeds:
item_family.id
that matches the value Apple-App-Store, and create such a product family if not found.item.id
that matches product[id]
and if not found, create such a plan-item under the item family described in the previous step.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.id
set to original_transaction_id
start_date
set to responseBody.Latest_receipt_info.purchase_date_ms
current_term_end
set to responseBody.Latest_receipt_info.expires_date_ms
transaction.reference_number
is set to the transaction_id
of the payment.transaction.payment_method
is set to apple_pay
. 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.
Chargebee validates the purchase token with Google Play Store and does the following once validation succeeds:
item_family.id
that matches the value Google-Play-Store
, and create such a product family if not found.item.id
that matches product[id]
and if not found, create such a plan-item under the item family described in the previous step.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.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
.transaction.reference_number
is set to the orderId
of the payment.transaction.payment_method
is set to play_store
. {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.
{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.{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.# Create an In app subscription for Apple App Store curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/process_purchase_command \ -X POST \ -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"
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.
productId
/subscriptionId
or sku
received from the Google Play Store
.
product[price_in_decimal]
.
product[id]
will be considered as the value of product[name]
.product[price]
.
optional
parameter. The parameter value is required
if the product(s) are not imported to Chargebee from Apple App Store.
0
represents the day
,1
represents the week
, 2
represents the month
, and 3
represents the year
. This is an optional
parameter. The parameter value is required
if the product(s) are not imported to Chargebee from Apple App Store. Note
Since the Apple App Store receipt does not have the subscription renewal period information for trial subscriptions, product[period]
and product[period_unit]
are needed, to create a subscription in Chargebee with the trial period. If these parameters are not passed and the receipt has trial information then Chargebee will return a validation error.
id
in Chargebee for the customer who made this purchase via Google Play Store. If not provided, subscription_id
(random unique id) will be the customer[id]
. If the customer record is not found in Chargebee, it is created.
id
in Chargebee for the customer who made this purchase. If not provided, the value is considered to be original_transaction_id
(the transaction identifier at Apple, of the original purchase). If the customer record is not found in Chargebee, it is created.
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
Anin_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_id
s. If a receipt contains more than 100 original_transaction_id
s, 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.
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.
Chargebee validates the receipt
with Apple App Store and does the following once validation succeeds:
Subscriptions are imported as follows:
original_transaction_id
in the Apple receipt.original_transaction_id
s for which a subscription already exists in Chargebee.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 are imported as follows:
Latest_receipt_info
which has is_trial_period
as false
.subscription_id
set to original_transaction_id
.A transaction is imported for each invoice with the following details:
reference_number
set to the transaction_id
.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.
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.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:
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 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
.
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
.
{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.
{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.{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.# Import In app subscriptions for Apple App Store curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_receipt \ -X POST \ -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"
# Import In app subscriptions for Apple App Store curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_receipt \ -X POST \ -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"
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.
Apple App Store: The currency code (ISO 4217 format) for the product.
Google Play Store: This parameter is not applicable to the Google Play Store. If the value is passed, it will return a validation error.
Apple App Store: The unique id
in Chargebee for the customer who made this purchase. If not provided, the value is considered to be original_transaction_id
(the transaction identifier at Apple, of the original purchase). If the customer record is not found in Chargebee, it is created.
Google Play Store: The unique id
of the customer who made this purchase via Google Play Store. This unique id
will be used as customer ID within Chargebee. If not provided, subscription_id
(random unique id
) will be the customer ID. If the customer ID already exists in Chargebee then subscription will be associated with this customer ID.
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.
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:
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.
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()
.
The payment is recorded against the subscription invoice.
Imported invoice has the subscription_id
set to original_transaction_id
.
Transactions for the invoice
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
.
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.
# Imports an In app subscription for Apple App Store curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_subscription \ -X POST \ -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"
# Imports an In app subscription for Apple App Store curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/import_subscription \ -X POST \ -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"
This parameter is known as original_transaction_id
in Apple App Store. You can get the value of original_transaction_id
from the latest_receipt_info
. The latest_receipt_info
is an array that contains all in-app purchase transactions.
The time at which the subscription has started or going to be started. You can find this value from the oldest purchase_date_ms
.
Start date of the billing period for the subscription. You can find it from the purchase_date_ms
field in receipt payload.
End date of the billing period for the subscription. You can find it from the expires_date_ms
field in receipt payload.
The unique identifier of the product as configured in App Store Connect.
latest_receipt_info
. This must be unique across subscriptions.
The unique id
in Chargebee for the customer who made this purchase. If not provided, the value is considered to be original_transaction_id
(the transaction identifier at Apple, of the original purchase.). If the customer record is not found in Chargebee, it is created.
This API verifies the application id {in_app_subscription_app_id}
and receipt
then returns the subscription details associated with the purchase.
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.
{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.{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.# Retrieve subscription from the store using the receipt curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/retrieve \ -X POST \ -u {site_api_key}:\ -d receipt="Apple Based64 Encoded Receipt"
# Retrieve subscription from the store using the receipt curl https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/retrieve \ -X POST \ -u {site_api_key}:\ -d receipt="Apple Based64 Encoded Receipt"
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.