API Version
Product Catalog
Library

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__gps_sdfwerzx5134", "customer_id": "__test__XpbTXGTSRp3gEsD8", "id_at_source": "20000006743", "source": "google_play_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, "omnichannel_subscription_item_offers": [ { "id": "__test__off__AHsdfs123LD1", "offer_id_at_source": "intro_offer_google_monthly", "category": "introductory", "category_at_source": "INTRODUCTORY", "type": "free_trial", "type_at_source": "FREE_TRIAL", "discount_type": "percentage", "duration": "P1M", "percentage": 50, "price_currency": "USD", "price_units": 2, "price_nanos": 90000000, "offer_term_start": 1752676649, "offer_term_end": 1755268649 } ] } ] }

API Index URL

https://{site}.chargebee.com/api/v2/omnichannel_subscriptions

Model Class

id id
string, max chars=50

The ID generated by Chargebee for the recorded subscription purchase.


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


app_id app_id
string, max chars=100

App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:


source source
enumerated string

The source where the purchase is originally made and managed.


Possible values are
apple_app_store

When source of the application is Apple App Store

google_play_store

When source of the application is Google Play Store

Show all values[+]
customer_id customer_id
optional, string, max chars=100

The id of the customer object that is associated with this purchase.


created_at created_at
timestamp(UTC) in seconds

Indicates timestamp when the omnichannel_subscription created in Chargebee.


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


omnichannel_subscription_items
optional, list of omnichannel_subscription_item

Items associated with the omnichannel_subscription.


initial_purchase_transaction
optional, omnichannel_transaction

Refers to the record created when a customer makes their first purchase.


resource_version
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
Show attributes [+]
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.

has_scheduled_changes
boolean, default=false

Indicates whether the omnichannel_subscription_item has any scheduled changes.


has_scheduled_changes
Show attributes [+]
required, boolean, default=false

Indicates whether the omnichannel_subscription_item has any scheduled changes.

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

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


grace_period_expires_at
Show attributes [+]
optional, timestamp(UTC) in seconds

Indicates timestamp when the grace period of subscription associated with the omnichannel_subscription_item expires in the source

cancellation_reason
optional, enumerated string

The reason of canceling the subscription.


Possible values are
customer_cancelled

Indicates that the subscription was voluntarily cancelled by the customer.

customer_did_not_consent_to_price_increase

Indicates that the customer did not consent to the price increase for the subscription item.

refunded_due_to_app_issue

Indicates that the subscription was cancelled and refunded due to the app issue.

refunded_for_other_reason

Indicates that the subscription was cancelled and refunded for another reason.

Show all values[+]
cancellation_reason
Show attributes [+]
optional, enumerated string

The reason of canceling the subscription.

cancelled_at
optional, timestamp(UTC) in seconds

Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source


cancelled_at
Show attributes [+]
optional, timestamp(UTC) in seconds

Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source

expiration_reason
optional, enumerated string

Specifies the reason for the subscription expiration.


Possible values are
billing_error

Indicates a billing error, such as the customer's payment information being invalid.

product_not_available

Indicates that the product was unavailable for purchase at the time of renewal.

other

Indicates that the subscription associated with the item expired for an unspecified reason.

Show all values[+]
expiration_reason
Show attributes [+]
optional, enumerated string

Specifies the reason for the subscription expiration.

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

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 .


current_term_end
Show attributes [+]
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_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 .


current_term_start
Show 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 .

auto_renew_status
optional, enumerated string

The renewal status for the omnichannel_subscription_item .


Possible values are
off

The auto-renewal of omnichannel_subscription_item is disabled.

on

The auto-renewal of omnichannel_subscription_item is enabled.

Show all values[+]
auto_renew_status
Show attributes [+]
optional, enumerated string

The renewal status for the omnichannel_subscription_item .

status
enumerated string

Status of the omnichannel_subscription_item. Learn more about status and their mapping with the store's status.


Possible values are
active

When the subscription associated with the omnichannel_subscription_item is active

expired

When the subscription associated with the omnichannel_subscription_item is expired

cancelled

When the subscription associated with the omnichannel_subscription_item is cancelled

in_dunning

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

item_parent_id_at_source
optional, string, max chars=100

The parent name of the product ID in the source .


item_parent_id_at_source
Show attributes [+]
optional, string, max chars=100

The parent name of the product ID in the source .

item_id_at_source
string, max chars=100

Product ID in the source .


item_id_at_source
Show attributes [+]
required, string, max chars=100

Product ID in the source .

id
string, max chars=40

Uniquely identifies a omnichannel_subscription_item .


required, string, max chars=40

Uniquely identifies a omnichannel_subscription_item .

omnichannel_subscription_item_offers
optional, list of omnichannel_subscription_item_offer

Represents the omnichannel_subscription_item_offers associated with the omnichannel_subscription_item .


omnichannel_subscription_item_offers
Show attributes [+]
optional, list of omnichannel_subscription_item_offer

Represents the omnichannel_subscription_item_offers associated with the omnichannel_subscription_item .

upcoming_renewal
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
Show attributes [+]
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.

linked_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
Show attributes [+]
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 .

resource_version
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
Show attributes [+]
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.

created_at
timestamp(UTC) in seconds

The timestamp of transaction creation


required, timestamp(UTC) in seconds

The timestamp of transaction creation

transacted_at
optional, timestamp(UTC) in seconds

Timestamp denoting the time when the transaction occurred in source


transacted_at
Show attributes [+]
optional, timestamp(UTC) in seconds

Timestamp denoting the time when the transaction occurred in source

type
enumerated string

Omnichannel subscription transaction type that describes the transaction


Possible values are
purchase

Indicates that the transaction occurred for a purchase.

renewal

Indicates that the transaction was initiated as part of a renewal for a previously completed purchase.

Show all values[+]
required, enumerated string

Omnichannel subscription transaction type that describes the transaction

price_nanos
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


price_nanos
Show attributes [+]
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

price_units
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


price_units
Show attributes [+]
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

price_currency
optional, string, max chars=3

The currency code for the transaction


price_currency
Show attributes [+]
optional, string, max chars=3

The currency code for the transaction

app_id
string, max chars=100

App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:


required, string, max chars=100

App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the app_id:

id_at_source
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
Show attributes [+]
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
string, max chars=40

Unique ID of a omnichannel transaction


required, string, max chars=40

Unique ID of a omnichannel transaction

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.


linked_omnichannel_subscriptions
Show attributes [+]
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.

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


linked_omnichannel_one_time_orders
Show attributes [+]
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.

Try in API Explorer

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.

Sample Request
Try in API Explorer
curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/__test__os_AHsdfs123ld1 \
     -u {site_api_key}:
copy
Click to Copy
200:
OK
STATUS

Sample Response [ JSON ]

Show more...
{
    "omnichannel_subscription": {
        "id": "__test__os_AHsdfs123ld1",
        "app_id": "__test__gps_sdfwerzx5134",
        "customer_id": "__test__XpbTXGTSRp3gEsD8",
        "id_at_source": "20000006743",
        "source": "google_play_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,
                "omnichannel_subscription_item_offers": [
                    {
                        "id": "__test__off__AHsdfs123LD1",
                        "offer_id_at_source": "intro_offer_google_monthly",
                        "category": "introductory",
                        "category_at_source": "INTRODUCTORY",
                        "type": "free_trial",
                        "type_at_source": "FREE_TRIAL",
                        "discount_type": "percentage",
                        "duration": "P1M",
                        "percentage": 50,
                        "price_currency": "USD",
                        "price_units": 2,
                        "price_nanos": 90000000,
                        "offer_term_start": 1752676649,
                        "offer_term_end": 1755268649
                    },
                    {..}
                ]
            },
            {..}
        ]
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/{omnichannel-subscription-id}

Method

omnichannel_subscription omnichannel_subscription
always returned
Resource object representing omnichannel_subscription

Sample admin console URL

https://{site}.chargebee.com/admin-console/omnichannel_subscriptions/123x
Try in API Explorer

Returns a list of omnichannel_subscription .

Sample Request
Try in API Explorer
curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions \
     -G  \
     -u {site_api_key}:
copy
Click to Copy
200:
OK
STATUS

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "omnichannel_subscription": {
                "id": "__test__os_AHsdfs123ld1",
                "app_id": "__test__gps_sdfwerzx5134",
                "customer_id": "__test__XpbTXGTSRp3gEsD8",
                "id_at_source": "20000006743",
                "source": "google_play_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,
                        "omnichannel_subscription_item_offers": [
                            {
                                "id": "__test__off__AHsdfs123LD1",
                                "offer_id_at_source": "intro_offer_google_monthly",
                                "category": "introductory",
                                "category_at_source": "INTRODUCTORY",
                                "type": "free_trial",
                                "type_at_source": "FREE_TRIAL",
                                "discount_type": "percentage",
                                "duration": "P1M",
                                "percentage": 50,
                                "price_currency": "USD",
                                "price_units": 2,
                                "price_nanos": 90000000,
                                "offer_term_start": 1752676649,
                                "offer_term_end": 1755268649
                            },
                            {..}
                        ]
                    },
                    {..}
                ]
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/omnichannel_subscriptions

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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.
Filter Params
For operator usages, see the Pagination and Filtering section.
source[<operator>]
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[is][operator]
optional, enumerated string filter
Possible values are : apple_app_store, google_play_store
Supported operators :

Example
source[is_not][operator]
optional, enumerated string filter
Possible values are : apple_app_store, google_play_store
Supported operators :

Example
source[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
source[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[<operator>]
optional, string filter

Chargebee Customer External Identifier. Supported operators : is, is_not, starts_with

Example → customer_id[is] = "8gsnbYfsMLds"

Possible values are :
Supported operators : is, is_not, starts_with

Example customer_id[is] = "8gsnbYfsMLds"
customer_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
omnichannel_subscription omnichannel_subscription
always returned
Resource object representing omnichannel_subscription
next_offset next_offset
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
Try in API Explorer

Returns a list of omnichannel_transaction associated with the specified omnichannel_subscription .

Sample Request
Try in API Explorer
curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/__test__os_AHsdfs123ld1/omnichannel_transactions \
     -G  \
     -u {site_api_key}:
copy
Click to Copy
200:
OK
STATUS

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

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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.
omnichannel_transaction omnichannel_transaction
always returned
Resource object representing omnichannel_transaction
next_offset next_offset
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
Try in API Explorer

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.

Sample Request
Try in API Explorer
curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/os___dev__XpbBs6UUtfPr5b5/move \
     -u {site_api_key}:\
     -d to_customer_id="new_customer_id"
copy
Click to Copy
200:
OK
STATUS

Sample Response [ JSON ]

Show more...
{
    "omnichannel_subscription": {
        "id": "os___dev__XpbBs6UUtfPr5b5",
        "id_at_source": "2000000964948913",
        "app_id": "as_app___dev__XpbBs6UUtfPUHM2",
        "source": "apple_app_store",
        "customer_id": "new_customer_id",
        "created_at": 1755006365,
        "resource_version": 1755006365336,
        "initial_purchase_transaction": {
            "id": "ot___dev__XpbBs6UUtfPr5F4",
            "id_at_source": "2000000964948913",
            "app_id": "as_app___dev__XpbBs6UUtfPUHM2",
            "price_currency": "INR",
            "price_units": 0,
            "price_nanos": 0,
            "type": "purchase",
            "transacted_at": 1752839196,
            "created_at": 1755006365,
            "resource_version": 1755006365000,
            "object": "omnichannel_transaction"
        },
        "object": "omnichannel_subscription",
        "omnichannel_subscription_items": [
            {
                "id": "osi___dev__XpbBs6UUtfPr5d6",
                "item_id_at_source": "gold-yearly",
                "status": "active",
                "expired_at": 1752839796,
                "expiration_reason": "other",
                "resource_version": 1755006365339,
                "object": "omnichannel_subscription_item"
            },
            {..}
        ]
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/{omnichannel-subscription-id}/move

Method

to_customer_id[]
required, string, max chars=50

Specifies the unique ID of the customer resource to which the subscription will be moved.

omnichannel_subscription omnichannel_subscription
always returned
Resource object representing omnichannel_subscription

Sample admin console URL

https://{site}.chargebee.com/admin-console/omnichannel_subscriptions/123x