Represents a subscription purchased and managed in an external app marketplace (apple_app_store or google_play_store), normalized into Chargebee's omnichannel model.
Omnichannel subscriptions are typically created when you record a purchase and are kept in sync via store server notifications. They are store-managed: lifecycle changes come from Apple or Google, not from the Chargebee Subscriptions API.
Use omnichannel statuses for how store statuses map to omnichannel_subscription_item.status, and omnichannel events for notification-to-webhook mappings.
Identifier tip: Parent id_at_source is the Apple Transaction ID or Google purchase token. Nested initial_purchase_transaction.id_at_source is the Apple Transaction ID or Google Order ID (GPA.…). See attribute descriptions below.
Note: This resource represents in-app subscriptions made on Apple App Store and Google Play Store.
Sample Omnichannel subscriptionJSON
Omnichannel subscriptions attributes
The identifier of the subscription in the source.
Apple App Store: The original purchase Transaction ID (stable for the subscription lifecycle).
Google Play Store: The subscription purchase token. This value can change when Google issues a new token after certain subscription changes; Chargebee updates id_at_source to the latest token.
Note: Do not confuse this with
initial_purchase_transaction.id_at_source. For Google, the nested transaction uses the Order ID (GPA.…), not the purchase token.
App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:
- For Apple, follow these steps.
- For Google, follow these steps.
The id
of the customer
object that is associated with this purchase.
Timestamp (UTC) when the subscription was originally purchased in the app marketplace (initial purchase). This corresponds to the time of the initial purchase transaction in the source.
Omnichannel subscription item attributes
Product identifier of this subscription item in the source store.
Apple App Store: The App Store Connect product identifier.
Google Play Store: The Google Play product / base-plan identifier associated with the active entitlement. See also item_parent_id_at_source when a parent/child hierarchy applies.
Parent product identifier in the source store, when the store exposes a parent/child product hierarchy.
Apple App Store: Typically the subscription group / parent product context when applicable.
Google Play Store: Typically the parent product ID associated with the base plan / offer hierarchy when applicable.
Status of the omnichannel_subscription_item. Status lives on the item, not on the parent subscription.
Learn more about status and store mappings.
The subscription item is active and entitled for the current term.
Google Play Store: Also used when Google has canceled auto-renew but the term has not ended (auto_renew_status = off).
The subscription item expired for a non-cancellation reason. See expiration_reason.
The subscription item is cancelled (entitlement ended due to cancellation / revoke / refund contexts). See cancellation_reason.
Billing is retrying after a payment failure and access may be restricted (Apple billing retry / Google account hold).
Billing is retrying during a grace period; service should typically continue.
The subscription item is paused. See resumes_at when available.
Whether the subscription item is set to auto-renew at the end of the current term (on or off).
Google Play Store: When the customer cancels but remains in-term, status stays active and auto_renew_status is off.
Auto-renewal is disabled for the omnichannel_subscription_item.
Auto-renewal is enabled for the omnichannel_subscription_item.
Start of the current billing period of the subscription item. It is applicable only if the status
is active
.
End of the current billing period of the subscription item. Applicable when status is active.
Apple App Store: Closest analogue to next_billing_at because Apple does not expose a separate next-renewal timestamp. Apple may renew up to 24 hours before expiry and, in billing retry, may retry for up to 60 days. Learn more.
Google Play Store: Corresponds to the subscription expiry / next billing boundary from Play. When the customer has canceled but the term has not ended, status remains active with auto_renew_status = off (see omnichannel statuses).
Indicates timestamp when the subscription associated with the omnichannel_subscription_item
was expired
in the source
Specifies the reason for the subscription expiration. Present when status is expired.
Apple App Store: Commonly maps from Apple expiration intents such as BILLING_ERROR, PRODUCT_NOT_AVAILABLE, and OTHER.
Google Play Store: User-initiated and merchant-revoked expirations typically map to cancelled with a cancellation_reason instead of expired.
Billing error, such as invalid customer payment information.
Apple App Store: Maps from expiration intent BILLING_ERROR.
The product was unavailable for purchase at the time of renewal.
Apple App Store: Maps from expiration intent PRODUCT_NOT_AVAILABLE.
The subscription associated with the item expired for an unspecified reason.
Apple App Store: Maps from expiration intent OTHER.
Indicates timestamp when the subscription associated with the omnichannel_subscription_item
was cancelled
in the source
The reason the subscription item was cancelled. Present when status is cancelled. Store applicability varies by enum value.
The customer voluntarily cancelled the subscription.
Apple App Store: Commonly maps from expiration intent CUSTOMER_CANCELLED.
Google Play Store: Commonly maps from user-initiated cancellation / cancel-at-term-end flows.
The customer did not consent to a price increase for the subscription item.
Apple App Store: Maps from expiration intent CUSTOMER_DID_NOT_CONSENT_TO_PRICE_INCREASE.
Google Play Store: Not typically used for this reason code.
The subscription was cancelled and refunded due to an app issue.
Apple App Store: Commonly set for refund notifications with an app-issue refund reason.
Google Play Store: Not typically used for this reason code.
The subscription was cancelled and refunded for another reason.
Apple App Store: Commonly set for refund notifications with a non-app-issue refund reason.
Google Play Store: Not typically used for this reason code.
The merchant revoked access to the subscription.
Apple App Store: Can apply when access is revoked (for example, REVOKED / related refund revoke flows).
Google Play Store: Commonly maps from revoke / chargeback-style contexts (for example, SUBSCRIPTION_REVOKED).
Timestamp when the grace period for the omnichannel_subscription_item expires in the source.
Apple App Store: Present when the item is in in_grace_period (Apple billing grace period).
Google Play Store: Present when the item is in in_grace_period (SUBSCRIPTION_STATE_IN_GRACE_PERIOD).
Indicates whether the omnichannel_subscription_item
has any scheduled changes. When true, use List scheduled changes for an omnichannel subscription item to retrieve them.
Information about the upcoming renewal price.
Google Play Store: Present when Google provides renewal price information and auto_renew_status is on.
Apple App Store: Not applicable; this field is absent.
Initial purchase transaction attributes
The store-native identifier for this transaction.
Apple App Store: Transaction ID for this transaction.
Google Play Store: Order ID for this transaction (typically GPA.…). This is not the subscription purchase token (that is the parent omnichannel_subscription.id_at_source).
App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:
- For Apple, follow these steps.
- For Google, follow these steps.
The whole units of the amount.
For example:
if price_currency is USD (two-decimal currency), then the unit value for USD 1.23 will be 1
if price_currency is JPY (zero-decimal currency), then the unit value for JPY 123 will be 123
if price_currency is BHD (three-decimal currency), then the unit value for BHD 1.234 will be 1
The fractional price amount, in nanos (billionths of the currency unit).
The value must be between 0 and +999,999,999 inclusive.
For example:
If price_currency is USD (two-decimal currency), then nanos value for USD 1.23 will be 230,000,000
If price_currency is JPY (zero-decimal currency), then nanos value for JPY 123 will be 0
If price_currency is BHD (three-decimal currency), then nanos value for BHD 1.234 will be 234,000,000
Apple App Store: Typically present for purchase and renewal transactions.
Google Play Store: May be present when Google provides price data for the transaction; otherwise absent.
Omnichannel transaction type that describes this transaction.
Indicates that the transaction occurred for an initial purchase (subscription or one-time order).
Indicates that the transaction was initiated as part of a renewal for a previously completed subscription purchase.