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.
Sample omnichannel subscription [ JSON ]
{
"id": "__test__os_AHsdfs123ld1",
"app_id": "__test__aas_sdfwerzx5134",
"customer_id": "__test__XpbTXGTSRp3gEsD8",
"id_at_source": "20000006743",
"source": "apple_app_store",
"created_at": 1517487053,
"object": "omnichannel_subscription",
"omnichannel_subscription_items": [
{
"id": "__test__osi_BXswds133lf1",
"id_at_source": "com.example.landmarks.premium",
"status": "active",
"current_term_start": 1728988425,
"current_term_end": 1731666825
}
]
}
API Index URL GET
https://{site}.chargebee.com/api/v2/omnichannel_subscriptions
string, max chars=50 The ID generated by Chargebee for the recorded subscription 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.
string, max chars=100 App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get this app_id follow these steps.
enumerated string The source where the purchase is originally made and managed. Possible values are
apple_app_storeWhen source of the application is Apple App Storegoogle_play_storeWhen source of the application is Google Play Store
Show all values[+]
optional, string, max chars=100 The id of the customer object that is associated with this purchase.
timestamp(UTC) in seconds Indicates timestamp when the omnichannel_subscription 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. optional, list of omnichannel_subscription_item
Items associated with the omnichannel_subscription.
Omnichannel subscription item attributes
string, max chars=40 Uniquely identifies a omnichannel_subscription_item.
string, max chars=100 Product ID in the source.
optional, string, max chars=100 The parent name of the product ID in the source.
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.
Show all values[+]
optional, enumerated string The renewal status for the omnichannel_subscription_item. Possible values are
offThe auto-renewal of omnichannel_subscription_item is disabled.onThe auto-renewal of omnichannel_subscription_item is enabled.
Show all values[+]
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, 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.
Show all values[+]
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.
Show all values[+]
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 subscription automatically resumes after being set to paused.
boolean, default=false Indicates whether the omnichannel_subscription_item has any scheduled changes.
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
optional, string, max chars=3 The three-letter ISO 4217 currency code in which the next renewal is set to occur
optional, long The whole units of the amount.
For example:
if currencyCode is USD (i.e. two decimal currency), then the unit value for USD 1.23 will be 1
if currencyCode is JPY (i.e. zero decimal currency), then the unit value for JPY 123 will be 123
if currencyCode is BHD (i.e. three decimal currency), then the unit value for BHD 1.234 will be 1
optional, long The fractional price amount, in nanos (billionths of the currency unit), for the next renewal.
The value must be between 0 and +999,999,999 inclusive.
For example:
If currencyCode is USD (i.e. two decimal currency), then nanos value for USD 1.23 will be 230,000,000
If currencyCode is JPY (i.e. zero decimal currency), then nanos value for JPY 123 will be 0
If currencyCode is BHD (i.e. three decimal currency), then nanos value for BHD 1.234 will be 234,000,000
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.
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, omnichannel_transaction
Refers to the record created when a customer makes their first purchase.
Initial purchase transaction attributes
string, max chars=40 Unique ID of a omnichannel 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
string, max chars=100 Application ID of the store
optional, string, max chars=3 The currency code for the transaction
optional, long The whole units of the currency
optional, long The fraction part of the currency
enumerated string Omnichannel subscription transaction type that describes the transaction
optional, timestamp(UTC) in seconds Timestamp denoting the time when the transaction occurred in source
timestamp(UTC) in seconds The timestamp of transaction creation
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.
string, max chars=50 The ID generated by Chargebee for the recorded subscription 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.
string, max chars=100 App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get this app_id follow these steps.
enumerated string The source where the purchase is originally made and managed. Possible values are
apple_app_storeWhen source of the application is Apple App Storegoogle_play_storeWhen source of the application is Google Play Store
Show all values[+]
optional, string, max chars=100 The id of the customer object that is associated with this purchase.
timestamp(UTC) in seconds Indicates timestamp when the omnichannel_subscription 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.
optional, list of omnichannel_subscription_item Items associated with the omnichannel_subscription.
optional, omnichannel_transaction Refers to the record created when a customer makes their first 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. 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
boolean, default=false Indicates whether the omnichannel_subscription_item has any scheduled changes. required, boolean, default=false
Indicates whether the omnichannel_subscription_item has any scheduled changes.
Has scheduled change attributes
optional, timestamp(UTC) in seconds Indicates timestamp when the subscription automatically resumes after being set to paused. optional, timestamp(UTC) in seconds
Indicates timestamp when the subscription automatically resumes after being set to paused.
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
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.
Show all values[+] optional, enumerated string
The reason of canceling the subscription.
Cancellation reason attributes
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
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.
Show all values[+] optional, enumerated string
Specifies the reason for the subscription expiration.
Expiration reason attributes
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
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
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, timestamp(UTC) in seconds Start of the current billing period of the subscription item. It is applicable only if the status is active.
Current term start attributes
optional, enumerated string The renewal status for the omnichannel_subscription_item. Possible values are
offThe auto-renewal of omnichannel_subscription_item is disabled.onThe auto-renewal of omnichannel_subscription_item is enabled.
Show all values[+] optional, enumerated string
The renewal status for the omnichannel_subscription_item.
Auto renew status attributes
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.
Show all values[+] required, enumerated string Status of the omnichannel_subscription_item. Learn more about status and their mapping with the store's status.
optional, string, max chars=100 The parent name of the product ID in the source. optional, string, max chars=100 The parent name of the product ID in the source.
Item parent id at source attributes
string, max chars=100 Product ID in the source. required, string, max chars=100 Product ID in the source.
Item id at source attributes
string, max chars=40 Uniquely identifies a omnichannel_subscription_item. required, string, max chars=40
Uniquely identifies a omnichannel_subscription_item.
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
optional, string, max chars=3 The three-letter ISO 4217 currency code in which the next renewal is set to occur
optional, long The whole units of the amount.
For example:
if currencyCode is USD (i.e. two decimal currency), then the unit value for USD 1.23 will be 1
if currencyCode is JPY (i.e. zero decimal currency), then the unit value for JPY 123 will be 123
if currencyCode is BHD (i.e. three decimal currency), then the unit value for BHD 1.234 will be 1
optional, long The fractional price amount, in nanos (billionths of the currency unit), for the next renewal.
The value must be between 0 and +999,999,999 inclusive.
For example:
If currencyCode is USD (i.e. two decimal currency), then nanos value for USD 1.23 will be 230,000,000
If currencyCode is JPY (i.e. zero decimal currency), then nanos value for JPY 123 will be 0
If currencyCode is BHD (i.e. three decimal currency), then nanos value for BHD 1.234 will be 234,000,000
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.
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. 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.
Sample Response [ JSON ]
Show more...
{
"omnichannel_subscription": {
"id": "__test__os_AHsdfs123ld1",
"app_id": "__test__aas_sdfwerzx5134",
"customer_id": "__test__XpbTXGTSRp3gEsD8",
"id_at_source": "20000006743",
"source": "apple_app_store",
"created_at": 1517487053,
"object": "omnichannel_subscription",
"omnichannel_subscription_items": [
{
"id": "__test__osi_BXswds133lf1",
"id_at_source": "com.example.landmarks.premium",
"status": "active",
"current_term_start": 1728988425,
"current_term_end": 1731666825
},
{..}
]
}
}
URL Format
GET
https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/{omnichannel-subscription-id}
always returned required
Resource object representing omnichannel_subscription
Sample admin console URL
https://{site}.chargebee.com/admin-console/omnichannel_subscriptions/123x
Returns a list of omnichannel_subscription.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"list": [
{
"omnichannel_subscription": {
"id": "__test__os_AHsdfs123ld1",
"app_id": "__test__aas_sdfwerzx5134",
"customer_id": "__test__XpbTXGTSRp3gEsD8",
"id_at_source": "20000006743",
"source": "apple_app_store",
"created_at": 1517487053,
"object": "omnichannel_subscription",
"omnichannel_subscription_items": [
{
"id": "__test__osi_BXswds133lf1",
"id_at_source": "com.example.landmarks.premium",
"status": "active",
"current_term_start": 1728988425,
"current_term_end": 1731666825
},
{..}
]
}
},
{..}
]
}
URL Format
GET
https://{site}.chargebee.com/api/v2/omnichannel_subscriptions
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
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
Possible values are : apple_app_store, google_play_store
Supported operators : is, is_not, in, not_in
Example → source[is] = "apple_app_store"
pass parameters as source[<param name>][<operator>]
optional, enumerated string filter
Possible values are : apple_app_store, google_play_store
Supported operators :
Example →
optional, enumerated string filter
Possible values are : apple_app_store, google_play_store
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Chargebee Customer External Identifier. Possible values are :
Supported operators : is, is_not, starts_with
Example → customer_id[is] = "8gsnbYfsMLds"
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 :
Example →
always returned required
Resource object representing omnichannel_subscription
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`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/omnichannel_subscriptions/123x
Returns a list of omnichannel_transaction associated with the specified omnichannel_subscription.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"list": [
{
"omnichannel_transaction": {
"id": "__test__ot_LKedfs123ld1",
"app_id": "__test__aas_sdfwerzx5134",
"id_at_source": "20000006743",
"price_currency": "USD",
"price_units": 1,
"price_nanos": 230000000,
"type": "purchase",
"created_at": 1517487053,
"transacted_at": 1517487053,
"object": "omnichannel_transaction"
}
},
{..}
]
}
URL Format
GET
https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/{omnichannel-subscription-id}/omnichannel_transactions
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
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 required
Resource object representing omnichannel_transaction
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`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/omnichannel_subscriptions/123x
Settings
Configure SDK
