Omnichannel Statuses

An omnichannel subscription item represents a product or service an end user subscribes to across billing platforms such as Chargebee, the Apple App Store, or the Google Play Store.

Each platform uses its own statuses to indicate the state of a subscription. Chargebee's Omnichannel Subscription Item status standardizes these statuses, offering a consistent set of states regardless of the underlying billing platform.

Important: Status lives on the omnichannel_subscription_item resource. The parent omnichannel_subscription does not have a status attribute. One-time order items do not use this status model; they express cancellation via cancelled_at / cancellation_reason.

Omnichannel subscription item statuses

Currently, omnichannel subscription items have the following statuses:

Status	Description
`active`	A customer has an active subscription for an item for the current term. This includes cases where auto-renew is off but the term has not ended yet (see Google cancel-still-active below). Grace / dunning states are separate statuses.
`in_grace_period`	The subscription for an item has failed to renew due to a billing issue and is now in the grace period. Continue to provide service using the grace period while billing is retried.
`in_dunning`	The subscription for an item has failed to renew due to a billing issue and is now in the dunning period. Access to the subscription can be revoked while billing is retried. Inform the customer that their access is revoked and that there may be an issue with their billing information.
`cancelled`	The subscription for an item has ended due to cancellation, refund, or revoke contexts. Check the cancellation reason (`customer_cancelled`, `customer_did_not_consent_to_price_increase`, `refunded_due_to_app_issue`, `refunded_for_other_reason`, or `merchant_revoked`) to understand why.
`expired`	An item's subscription has expired due to billing errors, the item being no longer available, or other non-cancellation reasons. Check the expiration reason to understand the reason for expiration.
`paused`	A customer has paused their subscription for an item. See `resumes_at` on the item when available.

Mapping of Apple subscription status to omnichannel subscription item status

The following table shows the mapping of Apple subscription status to omnichannel subscription item status:

Apple App Store Status	Omnichannel Subscription Item Status
`ACTIVE`	`active`
`ACTIVE` with auto-renew disabled / scheduled cancel (`DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED`)	`active` Note: The subscription item remains `active` until term end. Auto-renew is off via `auto_renew_status` = `off`. When Apple sends `DID_CHANGE_RENEWAL_STATUS` with `AUTO_RENEW_DISABLED`, Chargebee emits `omnichannel_subscription_item_cancellation_scheduled` (see omnichannel events).
`BILLING_GRACE_PERIOD`	`in_grace_period`
`BILLING_RETRY`	`in_dunning`
`EXPIRED` with the expiration intents, `CUSTOMER_CANCELLED`, and `CUSTOMER_DID_NOT_CONSENT_TO_PRICE_INCREASE`	`cancelled`
`EXPIRED` with the expiration intents, `BILLING_ERROR`, `PRODUCT_NOT_AVAILABLE`, and `OTHER`	`expired`
`REVOKED` (and refund / revoke notification paths such as `REFUND`)	`cancelled` Note: See `cancellation_reason` values such as `refunded_due_to_app_issue`, `refunded_for_other_reason`, or `merchant_revoked`.

Note:

To understand the possible subscription statuses in Apple, refer to the status documentation.
For more information on enabling grace period in Apple App Store, see Enable Billing Grace Period for auto-renewable subscriptions.
Apple App Store continues to retry billing for 60 days, or until the customer resolves their billing issue or cancels their subscription, whichever comes first. Learn more about reducing involuntary subscriber churn in Apple.
Additional statuses may be supported in the future with other billing system integrations.

Mapping of Google subscription status to omnichannel subscription item status

The following table shows the mapping of Google subscription status to omnichannel subscription item status:

Google Play Store Status	Omnichannel Subscription Item Status
`SUBSCRIPTION_STATE_ACTIVE`	`active`
`SUBSCRIPTION_STATE_CANCELED`	`active` Note: Google has canceled auto-renew but the entitlement is still in-term. On the `omnichannel_subscription_item`, `auto_renew_status` is `off`. Status stays `active` until term end, then becomes `cancelled`. When Google sends `SUBSCRIPTION_CANCELED`, Chargebee emits `omnichannel_subscription_item_cancellation_scheduled` (see omnichannel events).
`SUBSCRIPTION_STATE_IN_GRACE_PERIOD`	`in_grace_period`
`SUBSCRIPTION_STATE_ON_HOLD`	`in_dunning`
`SUBSCRIPTION_STATE_PAUSED`	`paused`
`SUBSCRIPTION_STATE_EXPIRED` with the canceled state context as `userInitiatedCancellation`	`cancelled` (`cancellation_reason` typically `customer_cancelled`)
`SUBSCRIPTION_STATE_EXPIRED` with merchant revoke / chargeback-style contexts (see also `SUBSCRIPTION_REVOKED` notifications)	`cancelled` (`cancellation_reason` typically `merchant_revoked`)
Other `SUBSCRIPTION_STATE_EXPIRED` contexts / pending states	Confirm product mapping for your site. Google user-initiated and merchant-revoked expirations typically map to `cancelled` rather than `expired`.