Omnichannel subscriptions

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 subscriptionJSON

Omnichannel subscriptions attributes

required, string, max chars=50

The ID generated by Chargebee for the recorded subscription purchase.

id_at_source

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 .

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:

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

source

required, enumerated string

The source where the purchase is originally made and managed.

apple_app_store

When source of the application is Apple App Store

google_play_store

When source of the application is Google Play Store

customer_id

optional, string, max chars=100

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

created_at

required, 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

required, 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.

Omnichannel subscription item attributes

required, string, max chars=40

Uniquely identifies a omnichannel_subscription_item .

item_id_at_source

required, 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

required, enumerated string

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

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 .

in_grace_period

When the subscription associated with the omnichannel_subscription_item is in_grace_period .

paused

When the subscription associated with the omnichannel_subscription_item is paused .

auto_renew_status

optional, enumerated string

The renewal status for the omnichannel_subscription_item .

off

The auto-renewal of omnichannel_subscription_item is disabled.

The auto-renewal of omnichannel_subscription_item is enabled.

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.

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.

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.

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.

merchant_revoked

Indicates that the merchant revoked access to the subscription.

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

required, 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.

omnichannel_subscription_item_offers

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.

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 attributes

required, string, max chars=40

Unique ID of a omnichannel transaction

id_at_source

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 .

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:

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

required, enumerated string

Omnichannel subscription transaction type that describes the transaction

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.

transacted_at

optional, timestamp(UTC) in seconds

Timestamp denoting the time when the transaction occurred in source

created_at

required, 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.

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