This resource unifies representation of the subscription data across multiple sources, such as the Apple App Store and Google Play Store. It provides one-to-one mapping of underlying data into Chargebee’s omnichannel format. Acting as a middleware, the solution delivers data in a unified format as it is presented.
Note: This resource represents in-app subscriptions made on Apple App Store and Google Play Store.
string, max chars=100 The identifier of the subscription in the source. For Apple App Store, it is the Transaction ID of the initial_purchase_transaction.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
enumerated string Status of the omnichannel_subscription_item. Learn more about status and their mapping with the store's status.
Possible values are
activeWhen the subscription associated with the omnichannel_subscription_item is activeexpiredWhen the subscription associated with the omnichannel_subscription_item is expiredcancelledWhen the subscription associated with the omnichannel_subscription_item is cancelledin_dunningWhen the subscription associated with the omnichannel_subscription_item is in_dunning.
optional, timestamp(UTC) in seconds End of the current billing period of the subscription item. It is applicable only if the status is active.
Note: This timestamp can be considered closest to the next_billing_at timestamp as Apple does not provide information on the next renewal. Apple can renew the subscription 24 hours before it expires, and after entering the billing retry state, it can attempt to renew the subscription for up to 60 days. Learn more.
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was expired in the source
optional, enumerated string Specifies the reason for the subscription expiration.
Possible values are
billing_errorIndicates a billing error, such as the customer's payment information being invalid.product_not_availableIndicates that the product was unavailable for purchase at the time of renewal.otherIndicates that the subscription associated with the item expired for an unspecified reason.
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source
optional, enumerated string The reason of canceling the subscription.
Possible values are
customer_cancelledIndicates that the subscription was voluntarily cancelled by the customer.customer_did_not_consent_to_price_increaseIndicates that the customer did not consent to the price increase for the subscription item.refunded_due_to_app_issueIndicates that the subscription was cancelled and refunded due to the app issue.refunded_for_other_reasonIndicates that the subscription was cancelled and refunded for another reason.
optional, timestamp(UTC) in seconds Indicates timestamp when the grace period of subscription associated with the omnichannel_subscription_item expires in the source
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
optional, list of omnichannel_subscription_item_offer Represents the omnichannel_subscription_item_offers associated with the omnichannel_subscription_item.
Omnichannel subscription item offer attributes
id
string, max chars=40 Unique identifier for the omnichannel_subscription_item_offer. System-generated.
optional, string, max chars=100 Identifier of the offer on the source platform (for example, Apple App Store or Google Play Store). Used to map Chargebee’s record to the source.
enumerated string Indicates functional purpose of the offer. For example, introductory indicates a first-time offer for new subscribers.
Possible values are
introductoryIntroductory offer for first-time subscribers, typically providing special pricing or terms for the first billing cycle.promotionalPromotional offer that may be available to both new and existing subscribers, often featuring limited-time pricing or terms.developer_determinedOffer terms that are determined by the developer, potentially including unique pricing or features.
optional, string, max chars=100 Category label as defined by the source platform (for example, Apple App Store or Google Play Store). Directly fetched from the source; useful for debugging or platform-specific workflows.
enumerated string Indicates how the offer is applied from a pricing-model perspective.
Possible values are
free_trialProvides a free trial period. The customer is not charged during the trial; regular billing begins after the trial ends.pay_up_frontRequires a fixed upfront payment for a defined subscription period, often at a discount. For example, pay for two months in advance.pay_as_you_goApplies a recurring discounted price at each billing cycle over multiple renewals, such as on a monthly plan, a discount on the initial purchase, and the next three billing cycles.
optional, string, max chars=100 Offer type as recorded by the source platform (for example, Apple App Store or Google Play Store), such as code>category_at_source is useful for tracking and audit.
fixed_amountDiscount that subtracts a fixed amount from the original price of the subscription item.percentageApplies a percentage discount on the original price of the subscription item. For example, 20% off.priceOverrides the original price with a fixed discounted price for the offer term. For example, set the price to $9.99 during the offer.
string, max chars=5 Indicates how long the offer applies to the subscription. This attribute uses ISO 8601 duration format. For example, P1M (1 month), P7D (7 days). After this duration, regular pricing resumes.
optional, double, min=0.01, max=100.0 Used when discount_type is percentage. Specifies the discount as a decimal value. For example, a value of 12.5 corresponds to a 12.5% discount.
optional, long Fractional part of the offer amount in nanos (billionths of the currency unit). For example, 500000000 represents 0.50. Combine with price_units to construct the total price (for example, $10.50).
optional, timestamp(UTC) in seconds Timestamp when the offer becomes effective for the subscription item. It is typically set to the time when the offer is first applied or activated.
optional, timestamp(UTC) in seconds Timestamp when the offer becomes invalid. After this time, regular pricing or terms apply to the subscription item.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
optional, upcoming_renewal This field contains information about the upcoming renewal. It is present only if the source provides renewal information (currently available only for Google Play Store purchases) and the omnichannel_subscription_item's auto_renew_status is set to on to renew for the next term. Otherwise, this field is absent.
Upcoming renewal attributes
price_currency
optional, string, max chars=3 The three-letter ISO 4217 currency code in which the next renewal is set to occur
optional, linked_item Represents an active product catalog mapping between an omnichannel_subscription_item and a Chargebee item. Use this attribute to retrieve entitlements for the omnichannel_subscription_item that are associated with the linked Chargebee item.
Linked item attributes
id
string, max chars=100 Represents the item_id of the Chargebee item linked to the omnichannel_subscription_item.
optional, timestamp(UTC) in seconds Indicates the timestamp when the mapping between the omnichannel_subscription_item and the Chargebee item was created in Chargebee.
string, max chars=100 The identifier of the subscription in the source. For Apple App Store, it is the Transaction ID of the initial_purchase_transaction. For Google Play Store, it is the Order ID of the initial_purchase_transaction.
enumerated string Omnichannel subscription transaction type that describes the transaction
Possible values are
purchaseIndicates that the transaction occurred for a purchase.renewalIndicates that the transaction was initiated as part of a renewal for a previously completed purchase.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, list of linked_omnichannel_subscription A list of omnichannel_subscription objects linked to this transaction. Each entry represents a subscription associated with the initial purchase transaction.
optional, list of linked_omnichannel_one_time_order A list of omnichannel_one_time_order objects linked to this transaction. Each entry represents a one-time order associated with the initial purchase transaction.
string, max chars=100 The identifier of the subscription in the source. For Apple App Store, it is the Transaction ID of the initial_purchase_transaction.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
Resource version attributes
has_scheduled_changes
boolean, default=false Indicates whether the omnichannel_subscription_item has any scheduled changes.
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription automatically resumes after being set to paused.
Resumes at attributes
grace_period_expires_at
optional, timestamp(UTC) in seconds Indicates timestamp when the grace period of subscription associated with the omnichannel_subscription_item expires in the source
optional, timestamp(UTC) in seconds Indicates timestamp when the grace period of subscription associated with the omnichannel_subscription_item expires in the source
Grace period expires at attributes
cancellation_reason
optional, enumerated string The reason of canceling the subscription.
Possible values are
customer_cancelledIndicates that the subscription was voluntarily cancelled by the customer.customer_did_not_consent_to_price_increaseIndicates that the customer did not consent to the price increase for the subscription item.refunded_due_to_app_issueIndicates that the subscription was cancelled and refunded due to the app issue.refunded_for_other_reasonIndicates that the subscription was cancelled and refunded for another reason.
optional, enumerated string The reason of canceling the subscription.
Cancellation reason attributes
cancelled_at
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source
Cancelled at attributes
expiration_reason
optional, enumerated string Specifies the reason for the subscription expiration.
Possible values are
billing_errorIndicates a billing error, such as the customer's payment information being invalid.product_not_availableIndicates that the product was unavailable for purchase at the time of renewal.otherIndicates that the subscription associated with the item expired for an unspecified reason.
optional, enumerated string Specifies the reason for the subscription expiration.
Expiration reason attributes
expired_at
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was expired in the source
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription associated with the omnichannel_subscription_item was expired in the source
Expired at attributes
current_term_end
optional, timestamp(UTC) in seconds End of the current billing period of the subscription item. It is applicable only if the status is active.
Note: This timestamp can be considered closest to the next_billing_at timestamp as Apple does not provide information on the next renewal. Apple can renew the subscription 24 hours before it expires, and after entering the billing retry state, it can attempt to renew the subscription for up to 60 days. Learn more.
optional, timestamp(UTC) in seconds End of the current billing period of the subscription item. It is applicable only if the status is active.
Note: This timestamp can be considered closest to the next_billing_at timestamp as Apple does not provide information on the next renewal. Apple can renew the subscription 24 hours before it expires, and after entering the billing retry state, it can attempt to renew the subscription for up to 60 days. Learn more.
Current term end attributes
current_term_start
optional, timestamp(UTC) in seconds Start of the current billing period of the subscription item. It is applicable only if the status is active.
optional, enumerated string The renewal status for the omnichannel_subscription_item.
Auto renew status attributes
status
enumerated string Status of the omnichannel_subscription_item. Learn more about status and their mapping with the store's status.
Possible values are
activeWhen the subscription associated with the omnichannel_subscription_item is activeexpiredWhen the subscription associated with the omnichannel_subscription_item is expiredcancelledWhen the subscription associated with the omnichannel_subscription_item is cancelledin_dunningWhen the subscription associated with the omnichannel_subscription_item is in_dunning.
required, string, max chars=40 Uniquely identifies a omnichannel_subscription_item.
Id attributes
omnichannel_subscription_item_offers
optional, list of omnichannel_subscription_item_offer Represents the omnichannel_subscription_item_offers associated with the omnichannel_subscription_item.
optional, list of omnichannel_subscription_item_offer Represents the omnichannel_subscription_item_offers associated with the omnichannel_subscription_item.
Omnichannel subscription item offer attributes
id
string, max chars=40 Unique identifier for the omnichannel_subscription_item_offer. System-generated.
optional, string, max chars=100 Identifier of the offer on the source platform (for example, Apple App Store or Google Play Store). Used to map Chargebee’s record to the source.
enumerated string Indicates functional purpose of the offer. For example, introductory indicates a first-time offer for new subscribers.
Possible values are
introductoryIntroductory offer for first-time subscribers, typically providing special pricing or terms for the first billing cycle.promotionalPromotional offer that may be available to both new and existing subscribers, often featuring limited-time pricing or terms.developer_determinedOffer terms that are determined by the developer, potentially including unique pricing or features.
optional, string, max chars=100 Category label as defined by the source platform (for example, Apple App Store or Google Play Store). Directly fetched from the source; useful for debugging or platform-specific workflows.
enumerated string Indicates how the offer is applied from a pricing-model perspective.
Possible values are
free_trialProvides a free trial period. The customer is not charged during the trial; regular billing begins after the trial ends.pay_up_frontRequires a fixed upfront payment for a defined subscription period, often at a discount. For example, pay for two months in advance.pay_as_you_goApplies a recurring discounted price at each billing cycle over multiple renewals, such as on a monthly plan, a discount on the initial purchase, and the next three billing cycles.
optional, string, max chars=100 Offer type as recorded by the source platform (for example, Apple App Store or Google Play Store), such as code>category_at_source is useful for tracking and audit.
fixed_amountDiscount that subtracts a fixed amount from the original price of the subscription item.percentageApplies a percentage discount on the original price of the subscription item. For example, 20% off.priceOverrides the original price with a fixed discounted price for the offer term. For example, set the price to $9.99 during the offer.
string, max chars=5 Indicates how long the offer applies to the subscription. This attribute uses ISO 8601 duration format. For example, P1M (1 month), P7D (7 days). After this duration, regular pricing resumes.
optional, double, min=0.01, max=100.0 Used when discount_type is percentage. Specifies the discount as a decimal value. For example, a value of 12.5 corresponds to a 12.5% discount.
optional, long Fractional part of the offer amount in nanos (billionths of the currency unit). For example, 500000000 represents 0.50. Combine with price_units to construct the total price (for example, $10.50).
optional, timestamp(UTC) in seconds Timestamp when the offer becomes effective for the subscription item. It is typically set to the time when the offer is first applied or activated.
optional, timestamp(UTC) in seconds Timestamp when the offer becomes invalid. After this time, regular pricing or terms apply to the subscription item.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource.
optional, upcoming_renewal This field contains information about the upcoming renewal. It is present only if the source provides renewal information (currently available only for Google Play Store purchases) and the omnichannel_subscription_item's auto_renew_status is set to on to renew for the next term. Otherwise, this field is absent.
optional, upcoming_renewal This field contains information about the upcoming renewal. It is present only if the source provides renewal information (currently available only for Google Play Store purchases) and the omnichannel_subscription_item's auto_renew_status is set to on to renew for the next term. Otherwise, this field is absent.
Upcoming renewal attributes
price_currency
optional, string, max chars=3 The three-letter ISO 4217 currency code in which the next renewal is set to occur
optional, linked_item Represents an active product catalog mapping between an omnichannel_subscription_item and a Chargebee item. Use this attribute to retrieve entitlements for the omnichannel_subscription_item that are associated with the linked Chargebee item.
optional, linked_item Represents an active product catalog mapping between an omnichannel_subscription_item and a Chargebee item. Use this attribute to retrieve entitlements for the omnichannel_subscription_item that are associated with the linked Chargebee item.
Linked item attributes
id
string, max chars=100 Represents the item_id of the Chargebee item linked to the omnichannel_subscription_item.
optional, timestamp(UTC) in seconds Indicates the timestamp when the mapping between the omnichannel_subscription_item and the Chargebee item was created in Chargebee.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
Resource version attributes
created_at
timestamp(UTC) in seconds The timestamp of transaction creation
optional, timestamp(UTC) in seconds Timestamp denoting the time when the transaction occurred in source
Transacted at attributes
type
enumerated string Omnichannel subscription transaction type that describes the transaction
Possible values are
purchaseIndicates that the transaction occurred for a purchase.renewalIndicates that the transaction was initiated as part of a renewal for a previously completed purchase.
string, max chars=100 The identifier of the subscription in the source. For Apple App Store, it is the Transaction ID of the initial_purchase_transaction. For Google Play Store, it is the Order ID of the initial_purchase_transaction.
required, string, max chars=100 The identifier of the subscription in the source. For Apple App Store, it is the Transaction ID of the initial_purchase_transaction. For Google Play Store, it is the Order ID of the initial_purchase_transaction.
Id at source attributes
id
string, max chars=40 Unique ID of a omnichannel transaction
required, string, max chars=40 Unique ID of a omnichannel transaction
Id attributes
linked_omnichannel_subscriptions
optional, list of linked_omnichannel_subscription A list of omnichannel_subscription objects linked to this transaction. Each entry represents a subscription associated with the initial purchase transaction.
optional, list of linked_omnichannel_subscription A list of omnichannel_subscription objects linked to this transaction. Each entry represents a subscription associated with the initial purchase transaction.
optional, list of linked_omnichannel_one_time_order A list of omnichannel_one_time_order objects linked to this transaction. Each entry represents a one-time order associated with the initial purchase transaction.
optional, list of linked_omnichannel_one_time_order A list of omnichannel_one_time_order objects linked to this transaction. Each entry represents a one-time order associated with the initial purchase transaction.
Retrieves an omnichannel_subscription object using an omnichannel_subscription_id. You can get the omnichannel_subscription_id for any successfully recorded purchase in Chargebee using List Omnichannel subscriptions API.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
optional, string, max chars=1000 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call.
optional, enumerated string filter To filter based on OmnichannelSubscription Source. Possible values are : apple_app_store, google_play_store Supported operators : is, is_not, in, not_in
Example →source[is] = "apple_app_store"
+
source
To filter based on OmnichannelSubscription Source. pass parameters as source[<param name>][<operator>]
source[is][operator]
source[is][operator]
optional, enumerated string filter Possible values are : apple_app_store, google_play_store Supported operators :
Example →
source[is_not][operator]
source[is_not][operator]
optional, enumerated string filter Possible values are : apple_app_store, google_play_store Supported operators :
Example →
source[in][operator]
source[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
source[not_in][operator]
source[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
customer_id[<operator>]
customer_id[<operator>]
optional, string filter Chargebee Customer External Identifier.Possible values are : Supported operators : is, is_not, starts_with
Example →customer_id[is] = "8gsnbYfsMLds"
+
customer_id
Chargebee Customer External Identifier. pass parameters as customer_id[<param name>][<operator>]
customer_id[is][operator]
customer_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
customer_id[is_not][operator]
customer_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
customer_id[starts_with][operator]
customer_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
always returned optional, string, max chars=1000 This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
optional, string, max chars=1000 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call.
always returned optional, string, max chars=1000 This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Moves an omnichannel_subscription to another customer. Updates the Omnichannel subscription’s customer ID and related records, then triggers the OMNICHANNEL_SUBSCRIPTION_MOVED_IN webhook with the new customer details.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Settings
Configure SDK
