In app subscriptions

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 integration, you can also configure Chargebee to receive server notifications from Apple to keep subscriptions up-to-date.

Note
Only one app can be connected to any given Chargebee site via Chargebee user interface.
To connect multiple apps reach out to mobile@chargebee.com.

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.

Processing Webhooks

Configure Apple or Google server-side notifications so that subscriptions created using process purchase command API are kept up-to-date using information received via the webhooks.

App Store notifications with use case

The following table lists the notification types from App Store and describes how Chargebee responds to each of them.

Note:

V1 Notification types available on the App Store sandbox are listed here.
Chargebee supports both App Store notifications v1 and v2.

App Store Server Notifications V2

Notification type	Subtype	Chargebee’s response
`TEST`	`Notification without any Subtype`	Indicates that the App Store server sends when you request it by calling the Request a Test Notification endpoint. Call that endpoint to test if your server is receiving notifications. You receive this notification only at your request. Chargebee tests if a notification is received or not. No webhook gets triggered.
`SUBSCRIBED`	`INITIAL_BUY`	Indicates that the user purchased the subscription for the first time or that the user received access to the subscription through Family Sharing for the first time. Chargebee does not take action as the initial purchase is recorded using Process Purchase Command API.
`SUBSCRIBED`	`RESUBSCRIBE`	Indicates that the user resubscribed or received access through Family Sharing to the same subscription or to another subscription within the same subscription group. Chargebee webhooks triggered: subscription_reactivated, subscription_reactivated_with_backdating, payment_succeeded, and invoice_updated.
`RENEWAL_EXTENDED`	`Notification without any Subtype`	Indicates that the App Store extended the subscription renewal date that the developer requested. Learn more about Extend a Subscription Renewal Date. Chargebee can extend the current term end date based on the requested date. Chargebee webhooks triggered: subscription_changed
`REFUND_DECLINED`	`Notification without any Subtype`	Indicates that the App Store declined a refund request initiated by the app developer. The event will be recorded in the Sync events table if the refund request is declined. Chargebee will not take any action or trigger any webhook.
`REFUND`	`Notification without any Subtype`	Indicates that App Store successfully completed refund(Revocation Date and Revocation Reason will hold the date and reason for refund). Chargebee webhooks triggered: subscription_changed, credit_note_created, credit_note_updated, subscription_cancelled, and payment_refunded.
`GRACE_PERIOD_EXPIRED`	`Notification without any Subtype`	Indicates that the billing grace period has ended without renewing the subscription, so you can turn off access to service or content. The App Store continues to retry billing for 60 days, or until the user resolves their billing issue or cancels their subscription, whichever comes first. Chargebee webhooks triggered: subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled
`EXPIRED`	`BILLING_RETRY`	Indicates that the subscription expired because the subscription failed to renew before the billing retry period ended. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
	`VOLUNTARY`	Indicates that the subscription expired after the user disabled subscription auto-renewal. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
	`PRICE_INCREASE`	Indicates that the subscription expired because the user didn’t consent to a price increase. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
	`PRODUCT_NOT_FOR_SALE`	Indicates that the subscription expired because the product wasn't available for purchase at the time the subscription attempted to renew. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
	`Notification without any Subtype`	Indicates that the subscription expired for some other reason. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
`DID_RENEW`	`Notification without any Subtype`	Indicates that the active subscription has successfully auto-renewed for a new transaction period. Provide the customer with access to the subscription’s content or service. Chargebee webhooks triggered: subscription_renewed, subscription_changed, invoice_generated, payment_succeeded, and invoice_updated
`DID_RENEW`	`BILLING_RECOVERY`	Indicates that the expired subscription which previously failed to renew now successfully renewed. Chargebee webhooks triggered if the subscription is active: subscription_renewed, subscription_changed, invoice_generated, payment_succeeded, and invoice_updated Chargebee webhooks triggered if the subscription is canceled: subscription_reactivated, subscription_reactivated_with_backdating, payment_succeeded, and invoice_updated
`DID_FAIL_TO_RENEW`	`GRACE_PERIOD`	Indicates that the subscription failed to renew due to a billing issue; continue to provide access to the subscription during the grace period. Chargebee webhooks triggered: subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder
`DID_FAIL_TO_RENEW`	`Notification without any Subtype`	Indicates that the grace period for subscription renewal is over and the service is stopped. Chargebee webhooks triggered: subscription_changed and subscription_cancelled
`DID_CHANGE_RENEWAL_STATUS`	`AUTO_RENEW_ENABLED`	Indicates that the user enabled subscription auto-renewal. Chargebee webhooks triggered: subscription_reactivated, subscription_reactivated_with_backdating, payment_succeeded, and invoice_updated
`DID_CHANGE_RENEWAL_STATUS`	`AUTO_RENEW_DISABLED`	Indicates that the user disabled subscription auto-renewal, or the App Store disabled subscription auto-renewal after the user requested a refund. Chargebee webhooks triggered: subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled
`DID_CHANGE_RENEWAL_PREF`	`UPGRADE`	Indicates that the user upgraded their subscription. Upgrades take effect immediately. Chargebee webhooks triggered: subscription_changed, invoice_generated, payment_succeeded, and invoice_updated
	`DOWNGRADE`	Indicates that the user downgraded their subscription. Downgrades take effect at the next renewal. In Chargebee cancellation will be scheduled at the end of the term. Chargebee webhooks triggered: subscription_changed
	`Notification without any Subtype`	Indicates that the user canceled the downgrade which is scheduled. Chargebee webhooks triggered: subscription_changed
`PRICE_INCREASE`	`PENDING`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
`PRICE_INCREASE`	`ACCEPTED`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
`OFFER_REDEEMED`	`INITIAL_BUY`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
	`RESUBSCRIBE`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
	`UPGRADE`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
	`DOWNGRADE`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
	`Notification without any Subtype`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
`REVOKE`	`Notification without any Subtype`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.
`CONSUMPTION_REQUEST`	`Notification without any Subtype`	Chargebee does not support this notification. Therefore, this notification is not recorded in Chargebee.

App Store Server Notifications V1

Notification type	Description
`DID_CHANGE_RENEWAL_STATUS`, `INTERACTIVE_RENEWAL`	This notification triggers when a subscription is active or the customer is upgraded to another SKU (stock-keeping unit). Chargebee checks relevant details in the receipt to detect an upgrade event. Once an upgrade event is detected, you can update the subscription with the new product details, and allow the update to take effect immediately. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled. For subscription upgrade with proration. subscription_changed, invoice_generated, payment_succeeded, and invoice_updated. For subscription reactivation. subscription_reactivated, subscription_reactivated_with_backdating, payment_succeeded, and invoice_updated. For regular subscription renewal. subscription_renewed, subscription_changed, invoice_generated, payment_succeeded, and invoice_updated.
`DID_CHANGE_RENEWAL_PREF`	This notification triggers when a subscription is active or the customer is downgraded to another SKU(stock-keeping unit). It indicates that the customer made a change in their subscription plan that takes effect at the next renewal. The currently active plan is not affected. Chargebee schedule downgrades to take effect at the end of the period. At the end of the billing period, confirm the downgrade at Apple’s end before downgrading it in the Chargebee. Chargebee webhooks triggered For subscription upgrade with proration. subscription_changed, invoice_generated, payment_succeeded, and invoice_updated.
`DID_CHANGE_RENEWAL_STATUS`	This notification triggers when a subscription is expired or the customer resubscribes to the same SKU(stock-keeping unit). Chargebee re-activates subscription immediately. Chargebee webhooks triggered For subscription cancellation. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled. For subscription upgrade with proration. subscription_changed, invoice_generated, payment_succeeded, and invoice_updated.
`INTERACTIVE_RENEWAL`, `DID_CHANGE_RENEWAL_STATUS`	This notification triggers when a subscription is expired or the customer resubscribed to another SKU (upgrade or downgrade). Chargebee immediately re-activates the subscription with the new product(plan or item). Chargebee webhooks triggered For subscription upgrade with proration. subscription_changed, invoice_generated, payment_succeeded, and invoice_updated. For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled.
`DID_CHANGE_RENEWAL_STATUS`	This notification triggers when the customer canceled the subscription from the App Store Subscriptions settings page. Their subscription will not auto-renew and will expire on the `expires_date`. Chargebee sets subscription to cancel at `expires_date`. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled.
`DID_CHANGE_RENEWAL_STATUS`	This notification triggers when the customer previously canceled the subscription but now resubscribed to the same product before the subscription expired. The subscription will auto-renew on the `expires_date`. Chargebee removes scheduled cancellation of subscription and allows it to auto-renew. If the dates have changed for the term start and end, change the same in the Chargebee subscription. Chargebee webhooks triggered For subscription reactivation. subscription_reactivated, subscription_reactivated_with_backdating, payment_succeeded, and invoice_updated.
`CANCEL`, `DID_CHANGE_RENEWAL_STATUS`	This notification triggers when AppleCare refunded a subscription. `CANCEL` indicates that Apple Support cancelled the auto-renewable subscription and the customer received a refund as of the timestamp in `cancellation_date_ms`. Chargebee cancels the subscription on `cancellation_date_ms`. Record an offline refund and create a refundable credit note for the full amount. Record cancellation comment on the refund transaction saying `canceled by Apple Support`. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled.
`DID_FAIL_TO_RENEW`	This notification triggers when the subscription failed to renew because of a billing issue. It Indicates a subscription that failed to renew due to a billing issue. Check `is_in_billing_retry_period` to know the current retry status of the subscription. Check `grace_period_expires_date` to know the new service expiration date if the subscription is in a billing grace period. Chargebee takes the following actions. - When we receive this notification before a renewal invoice is created, schedule a cancellation at the end of the current term, if there is no grace period defined in the receipt. - When the notification is received, after the renewal invoice is generated, the subscription remains `active` while the invoice `status` becomes `not_paid`. - If `grace_period_expires_date` exists, schedule a subscription cancellation on that date. - If there is no recovery until the scheduled cancellation date, then the subscription will get cancelled as scheduled, and the `not_paid` invoice will get written off. - If `grace_period_expires_date` does not exist, cancel the subscription and write off the invoice immediately. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled.
`DID_RECOVER`	This notification triggers when expired subscription recovered by App Store through a billing retry. It indicates a successful automatic renewal of an expired subscription that failed to renew in the past. Check `expires_date` to determine the next renewal date and time. Chargebee resumes the paused subscription with any changes in subscription term dates as per receipt data. Remove scheduled cancellation. If we are syncing dunning information, update it accordingly. Chargebee webhooks triggered For regular subscription renewal. subscription_renewed, subscription_changed, invoice_generated, payment_succeeded, and invoice_updated.
`DID_CHANGE_RENEWAL_STATUS`	This notification triggers when the subscription has churned after failed billing retry attempts. It indicates a change in the subscription renewal status. In the JSON response, check `auto_renew_status_change_date_ms` to know the date and time of the last status update. Check `auto_renew_status` to know the current renewal status. Chargebee cancels the subscription at the end of the current term. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, and subscription_cancelled.
`REFUND`	This notification triggers when AppleCare successfully refunded the transaction for a consumable, non-consumable, or non-renewing subscription. Here, the `cancellation_date_ms` contains the timestamp of the refunded transaction. The `original_transaction_id` and `product_id` identify the original transaction and product. The `cancellation_reason` contains the reason. Chargebee cancels the subscription on a specified date and records an offline refund for the full amount as `canceled by Apple Support`. Chargebee webhooks triggered subscription_changed, credit_note_created, credit_note_updated, subscription_cancelled, and payment_refunded.
`PRICE_INCREASE_CONSENT`	This notification triggers when the subscription price is increased, and the customer must agree to the increase before the subscription auto-renews. It indicates that App Store has started asking the customer to consent to your app’s subscription price increase. In the unified_receipt.Pending_renewal_info object, the `price_consent_status` value is `0`, indicating that App Store is asking for the customer’s consent, and hasn’t received it. The subscription won’t auto-renew unless the user agrees to the new price. When the customer agrees to the price increase, the system sets `price_consent_status` to `1`. Check the receipt using verifyReceipt to view the updated price-consent status. Chargebee updates the subscription overriding subscription price. When consent is not received and renewal date is reached, pause the subscription. If possible, add a comment on the subscription saying “Paused because price increase consent not received from the customer”.
`DID_RENEW`	This notification triggers when a customer’s subscription is successfully auto-renewed for a new transaction period. Chargebee renews the subscription if not already auto-renewed. Chargebee webhooks triggered For regular subscription renewal. subscription_renewed, subscription_changed, invoice_generated, payment_succeeded, and invoice_updated.
`REVOKE`	This notification triggers when a purchaser disabled Family Sharing for a product, the purchaser (or family member) left the family group, or the purchaser asked for and received a refund. Your app will also receive a `paymentQueue(_:didRevokeEntitlementsForProductIdentifiers:)` call. For more information about Family Sharing, see Supporting Family Sharing in Your App.
`CONSUMPTION_REQUEST`	The customer initiated a refund request for a consumable in-app purchase. Chargebee does not support this notification.
`INITIAL_BUY`	This notification triggers when the customer completes an initial subscription purchase. Chargebee does not support this notification because price and currency information is not present in the receipt.

Webhook events triggered for creating an Apple subscription

When an in-app subscription is created in Chargebee, the following webhook events get generated in sequence.

Creates a plan created or Item (plan_created or item_created)
Creates a customer (customer_created)
Creates a subscription (subscription_created)
Updates a subscription (subscription_changed)
Generates an invoice (invoice_generated)
Successful payments (payment_succeeded)
Updates an invoice (invoice_updated)

Note

Webhooks are asynchronous by nature; therefore not recommended for time-critical applications. Webhooks may reach your application in a different order and become redundant. For time-critical applications, Chargebee recommends using the List events API to poll Chargebee for events.

Troubleshooting apple's webhook processing errors

Since Apple notifications do not provide any price information, processing a webhook fails in the following scenarios:

Issue	Solution
A new purchase (`INITIAL_BUY`) server notification is received.	Always use the process purchase command API to record a new purchase. Chargebee requires the amount paid and the currency to create a subscription.
A notification is received for an SKU (plan) change but the plan-item price is unavailable in Chargebee.	Create the plan-item price in Chargebee via API or admin console, then retry processing the webhook.

Google Play Store notifications with use case

Chargebee acts upon certain notifications from Google. On receiving any of the notifications listed in the table below, Chargebee checks whether the subscription is present. If present, it carries out certain actions as described in the table. The webhooks triggered due to these actions are also listed here for convenience.

Google notification	Chargebee’s response
`SUBSCRIPTION_RECOVERED`	When the subscription is in the paused state, Chargebee resumes the subscription or schedules it for resumption. Chargebee webhooks triggered For in-term resumption. `subscription_resumed` For out-of-term resumption. `subscription_resumed` and `invoice_generated` For scheduled resumption. `subscription_resumption_scheduled`
`SUBSCRIPTION_RENEWED`	Chargebee updates the subscription with the next renewal date. After receiving this notification if the subscription is in the canceled state, Chargebee reactivates the subscription. Chargebee webhooks triggered For subscription reactivation. `subscription_reactivated`, `subscription_reactivated_with_backdating`, `payment_succeeded`, and `invoice_updated`. For regular subscription renewal. `subscription_renewed`, `subscription_changed`, `invoice_generated`, `payment_succeeded`, and `invoice_updated`.
`SUBSCRIPTION_RESTARTED`	Chargebee reactivates the canceled subscription. Chargebee webhooks triggered `subscription_reactivated`, `subscription_reactivated_with_backdating`, `payment_succeeded`, and `invoice_updated`.
`SUBSCRIPTION_IN_GRACE_PERIOD`	Chargebee extends the current subscription term. Chargebee webhooks triggered `subscription_changed`
`SUBSCRIPTION_ON_HOLD`	Chargebee pauses the subscription and keeps it on hold. Chargebee webhooks triggered `subscription_paused`
`SUBSCRIPTION_PAUSED`	If the subscription is not already paused, Chargebee pauses the subscription. Chargebee webhooks triggered `subscription_paused`
`SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED`	If the subscription is not already paused, Chargebee schedules the subscription pause on the pause_date. Chargebee webhooks triggered `subscription_pause_scheduled`
`SUBSCRIPTION_REVOKED`	Chargebee cancels the subscription immediately. Chargebee webhooks triggered `invoice_updated` and `subscription_cancelled`
`SUBSCRIPTION_CANCELED`	Chargebee cancels the subscription or schedules it for cancellation. Chargebee webhooks triggered For subscription cancellation, whether immediately or at the end of the term. `subscription_changed`, `subscription_cancellation_scheduled`, `subscription_cancellation_reminder`, and `subscription_cancelled`.
`SUBSCRIPTION_EXPIRED`	Chargebee cancels the subscription immediately. Chargebee webhooks triggered `subscription_cancelled`
`SUBSCRIPTION_PURCHASED`	Chargebee does not support this notification.
`SUBSCRIPTION_PRICE_CHANGE_CONFIRMED`	Chargebee does not support this notification.
`SUBSCRIPTION_DEFERRED`	Chargebee does not support this notification.

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

subscription_id

optional, 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.

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.

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.

Apple App Store

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:

Look for item_family.id that matches the value Apple-App-Store, and create such a product family if not found.
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.
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.
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:

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

Instead, if the receipt belongs to an existing subscription in Chargebee, it is updated to reflect the current state of the subscription at Apple.

The payment is recorded against the subscription 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_pay.

Google Play Store

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:

Look for item_family.id that matches the value Google-Play-Store, and create such a product family if not found.
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.
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.
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.

The payment is recorded against the subscription invoice. The associated transaction is updated with the following details:

The transaction.reference_number is set to the orderId of the payment.
The 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.

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 \
     -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"

copy

# 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"

# Create an In app subscription for Google Play Store
curl  https://{site}.chargebee.com/api/v2/in_app_subscriptions/cb-pjp7hcmrcbfmtjhle3smlwicu4/process_purchase_command \
     -X POST  \
     -u {site_api_key}:\
     -d receipt="Google purchase token" \
     -d product[id]="play_store_plan_id" \
     -d customer[id]="customer-123"

Sample Response [ JSON ]

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

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

URL Format POST

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

receipt

required, string, max chars=65k
Google Play Store: The purchase token taken from the Android device after successful creation of the in-app purchase.
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.

product

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

product[id]

required, string, max chars=96
Google Play Store: The unique identifier of the product purchased. The value of this parameter is the productId/subscriptionId or sku received from the Google Play Store.
required, string, max chars=96

Apple App Store: The unique identifier (created in App Store Connect) of the product purchased.

product[name]

optional, string, max chars=46
Google Play Store: The name (created in Play Store Console) of the product purchased. If not passed then the product[id] will be considered as the value of product[name].
optional, string, max chars=46

Apple App Store: The name (created in App Store Connect) of the product purchased.

product[currency_code]

required, string, max chars=3
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 currency code (ISO 4217 format) for the product.

product[price]

required, in cents, min=0
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 price paid by the customer for this product. The unit depends on the type of currency. Provide either this or product[price_in_decimal].

product[price_in_decimal]

optional, string, max chars=39
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 price paid by the customer for the product. The value is in decimal and in major units of the currency. Provide either this or product[price].

product[period]

optional, string, max chars=3
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: This is the renewal period of the subscription. For example, 1, 2, 3, and so on. This is an optional parameter. The parameter value is required if the product(s) are not imported to Chargebee from Apple App Store.

product[period_unit]

optional, string, max chars=3
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: This is the unit of the renewal period. For example, 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.

customer

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

customer[id]

optional, string, max chars=50
Google Play Store: The unique 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.
optional, string, max chars=50

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.

customer[email]

optional, string, max chars=70
The email address of the customer who made the purchase.

customer[first_name]

optional, string, max chars=150
The first name of the customer who made the purchase.

customer[last_name]

optional, string, max chars=150
The last name of the customer who made the purchase.

in_app_subscription

always returned
Resource object representing in_app_subscription

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.

Apple App Store

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:

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

An invoice is imported to Chargebee for every element of the array Latest_receipt_info which has is_trial_period as false.
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:

reference_number set to the transaction_id.
payment_method set to apple_store.

Google Play 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 for 60 days from the subscription purchase date. 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.

Sample Request

# 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"

copy

# 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"

Sample Response [ JSON ]

{"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

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

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

product[currency_code]

required, string, max chars=3

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.

customer

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

customer[id]

optional, string, max chars=50

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.

customer[email]

optional, string, max chars=70

Apple App Store: The email ID of the customer who made this purchase.

Google Play Store: The email ID of the customer who made this purchase.

in_app_subscriptions

always returned
Array of in_app_subscription object

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: Subscription cannot be imported from Google Play Store without a receipt or token. Therefore; Chargebee does not allow you to use this API for Google Play Store.

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

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().

Invoice for the subscription

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.

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.

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 \
     -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"

copy

# 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"

Sample Response [ JSON ]

{"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

subscription

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

subscription[id]

required, string, max chars=50

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.

subscription[started_at]

required, timestamp(UTC) in seconds

The time at which the subscription has started or going to be started. You can find this value from the oldest purchase_date_ms.

subscription[term_start]

required, timestamp(UTC) in seconds

Start date of the billing period for the subscription. You can find it from the purchase_date_ms field in receipt payload.

subscription[term_end]

required, timestamp(UTC) in seconds

End date of the billing period for the subscription. You can find it from the expires_date_ms field in receipt payload.

subscription[product_id]

required, string, max chars=96

The unique identifier of the product as configured in App Store Connect.

subscription[currency_code]

required, string, max chars=3
The currency code (ISO 4217 format) for the product.

subscription[transaction_id]

required, string, max chars=43
Transaction ID value as mentioned in the latest_receipt_info. This must be unique across subscriptions.

subscription[is_trial]

optional, boolean, default=false
Indicates if the subscription is in trial for the term start and term end. The default value is false.

customer

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

customer[id]

optional, string, max chars=50

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.

customer[email]

optional, string, max chars=70

The email ID of the customer who made this purchase.

in_app_subscription

always returned
Resource object representing in_app_subscription

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

Note
Currently, this API is only supported for Apple App Store and not for Google Play 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.

Sample Request

# 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"

copy

# 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"

Sample Response [ JSON ]

{"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

receipt

required, string, max chars=65k
The Base64 encoded App Store in-app purchase receipt taken from the Apple device after successful creation of the in-app purchase.

in_app_subscriptions

always returned
Resource object representing in_app_subscription

Processing Webhooks

App Store notifications with use case

App Store Server Notifications V2

App Store Server Notifications V1

Notification type

Description

Webhook events triggered for creating an Apple subscription

Troubleshooting apple's webhook processing errors

Issue

Solution

Google Play Store notifications with use case

Google notification

Chargebee’s response

Sample in app subscription [ JSON ]

API Index URL GET

In app subscription attributes

Process Purchase Command¶

Apple App Store

Google Play Store

Path Parameter

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Import Receipt¶

Apple App Store

Subscriptions

Invoices for the subscription

Transactions for the invoices

Google Play Store

Subscriptions

Invoices for the subscription

Transactions for the invoices

Path Parameter

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Import Subscription Without Receipt¶

Apple App Store

Subscription

Invoice for the subscription

Path Parameter

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Retrieve subscription from the store using the receipt¶

Path Parameter

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns