Omnichannel subscriptions

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__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

id

string, max chars=50
The ID generated by Chargebee for the recorded subscription purchase.

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

string, max chars=100

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.

source

enumerated string
The source where the purchase is originally made and managed.

Possible values are

customer_id

optional, string, max chars=100
The id of the customer object that is associated with this purchase.

created_at

timestamp(UTC) in seconds
Indicates timestamp when the omnichannel_subscription created in Chargebee.

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

optional, list of omnichannel_subscription_item
Items associated with the omnichannel_subscription.

Omnichannel subscription item attributes

id

string, max chars=40
Uniquely identifies a omnichannel_subscription_item.

item_id_at_source

string, max chars=100
Product ID in the source.

item_parent_id_at_source

optional, string, max chars=100
The parent name of the product ID in the source.

status

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

Possible values are

auto_renew_status

optional, enumerated string
The renewal status for the omnichannel_subscription_item.

Possible values are

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

expired_at

optional, timestamp(UTC) in seconds
Indicates timestamp when the subscription associated with the omnichannel_subscription_item was expired in the source

expiration_reason

optional, enumerated string
Specifies the reason for the subscription expiration.

Possible values are

cancelled_at

optional, timestamp(UTC) in seconds
Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source

cancellation_reason

optional, enumerated string
The reason of canceling the subscription.

Possible values are

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

resumes_at

optional, timestamp(UTC) in seconds
Indicates timestamp when the subscription automatically resumes after being set to paused.

has_scheduled_changes

boolean, default=false
Indicates whether the omnichannel_subscription_item has any scheduled changes.

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.

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.

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.

initial_purchase_transaction
Show attributes [+]

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

Initial purchase transaction attributes

id

string, max chars=40
Unique ID of a omnichannel transaction

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.

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:

For Apple, follow these steps.
For Google, follow these steps.

price_currency

optional, string, max chars=3
The currency code for the transaction

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_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

type

enumerated string
Omnichannel subscription transaction type that describes the transaction

Possible values are

transacted_at

optional, timestamp(UTC) in seconds
Timestamp denoting the time when the transaction occurred in source

created_at

timestamp(UTC) in seconds
The timestamp of transaction creation

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.

id

string, max chars=50
The ID generated by Chargebee for the recorded subscription purchase.

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

string, max chars=100

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.

source

enumerated string
The source where the purchase is originally made and managed.

Possible values are

customer_id

optional, string, max chars=100
The id of the customer object that is associated with this purchase.

created_at

timestamp(UTC) in seconds
Indicates timestamp when the omnichannel_subscription created in Chargebee.

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.

has_scheduled_changes

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.

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

cancellation_reason

optional, enumerated string
The reason of canceling the subscription.

Possible values are

cancelled_at

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

expired_at

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.

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.

auto_renew_status

optional, enumerated string
The renewal status for the omnichannel_subscription_item.

Possible values are

status

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

Possible values are

item_parent_id_at_source

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.

id

string, max chars=40
Uniquely identifies a omnichannel_subscription_item.

upcoming_renewal
Show attributes [+]

linked_item
Show attributes [+]

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

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/__test__os_AHsdfs123ld1 \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

omnichannel_subscription

always returned
Resource object representing omnichannel_subscription

Returns a list of omnichannel_subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions \
     -G  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

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"

customer_id[<operator>]

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

Example → customer_id[is] = "8gsnbYfsMLds"

omnichannel_subscription

always returned
Resource object representing omnichannel_subscription

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

Returns a list of omnichannel_transaction associated with the specified omnichannel_subscription.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/omnichannel_subscriptions/__test__os_AHsdfs123ld1/omnichannel_transactions \
     -G  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

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

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

omnichannel_transaction

always returned
Resource object representing omnichannel_transaction

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

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

Only for Java

copy full code

Click to Copy

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:

STATUS

Sample Response [ JSON ]

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

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

always returned
Resource object representing omnichannel_subscription

Sample omnichannel subscription [ JSON ]

API Index URL GET

Model Class

Omnichannel subscription attributes

Event types

Omnichannel Subscription Item attributes

Consent Fields for Omnichannel subscription

Custom Fields for Omnichannel subscription

Retrieve an Omnichannel subscription ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List Omnichannel subscriptions ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List Omnichannel transactions of an Omnichannel subscription ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Move an Omnichannel subscription ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL