Omnichannel events | Chargebee API documentation

API Version

Product Catalog

Library

Omnichannel events

Processing Omnichannel Webhooks

When selling subscriptions across platforms such as the Apple App Store, Google Play Store, or the web, it’s essential to track subscription changes in your backend. This ensures accurate provisioning of content and timely communication with end users.

Billing platforms use webhook notifications or events to communicate subscription state changes to external systems. However, each platform manages subscription states and events differently, adding complexity to handling these events.

Chargebee’s Omnichannel events simplify this process by providing a unified event representation. This allows you to integrate as though you are working with a single billing system while Chargebee handles platform-specific complexities for you.

Events from various billing platforms are consumed by Chargebee through the webhook notification URL configured in each respective platform.

Note: To learn how to configure the Chargebee webhook notification URL for the Apple App Store, click here.

When a purchase is recorded in Chargebee using the Record a Purchase API, Chargebee initiates a background job to process that purchase. Upon successful completion of this job, Chargebee returns the following event:

Chargebee Event	Description
`omnichannel_subscription_created` / `omnichannel_subscription_imported`	`omnichannel_subscription_created` will be triggered when an omnichannel subscription is successfully created in Chargebee. If there are any transactions (purchases or renewals) recorded after the initial transaction, we emit the `omnichannel_subscription_imported` event instead of `omnichannel_subscription_created`. In this scenario, the `imported` omnichannel subscription resource will include only two transactions: the `initial_purchase_transaction` and the most recent transaction. Note: To get the details of the item for which the subscription was purchased, refer to the `omnichannel_subscription` resource. To get the details of the transaction that happened at the source, refer to the `omnichannel_transaction` resource.
`record_purchase_failed`	The `record_purchase_failed` event will be triggered when recording a purchase fails to create an omnichannel subscription in Chargebee. The `status` of the recorded purchase will be changed to `failed`, and the error details will be available in the `error_detail` field.

The table below outlines various scenarios in which the Apple App Store triggers notifications or events. It details the types and sub-types of these notifications and the corresponding omnichannel subscription events triggered by Chargebee.

Important

Here is the link to Apple's v2 notifications.
Apple has deprecated v1 notification types, and these are not supported by the omnichannel solution.
Chargebee will process a transaction's events only if they are recorded with Chargebee. Otherwise, incoming events will be marked as ignored, even if we support those event types.
Notification types and sub-types not listed in the table are currently ignored by Chargebee. Support for these will be included in future releases.

Notification Type	Subtype	Chargebee’s Response
`DID_RENEW`		Scenario: When a subscription item successfully auto-renews. Description: The `current_term_start` and `current_term_end` attributes of the `omnichannel_subscription_item` resource in the event content indicates the new term after the renewal. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_renewed`
	`DOWNGRADE`	Scenario: When a subscription item successfully auto-renews with a different product ID. Description: The `item_id_at_source` attribute of the `omnichannel_subscription_item` resource in the event content specifies the ID of the item at the source that the customer downgraded to. The `current_term_start` and `current_term_end` attributes indicate the new term after the renewal. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_downgraded` `omnichannel_subscription_item_renewed`
	`BILLING_RECOVERY`	Scenario: When the subscription that is in the `in_dunning` or `in_grace_period` state has been successfully renewed. Description: A subscription that is in the `in_dunning` or `in_grace_period` state has been successfully renewed during the billing retry period. The omnichannel subscription status is changed from `in_dunning` or `in_grace_period` to `active`. As a result, the subscriber should regain access to the content. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_renewed`
`SUBSCRIBED`	`RESUBSCRIBE`	Scenario: When a customer resubscribes to any subscription item from the same subscription group as their expired subscription. Description: The `current_term_start` and `current_term_end` attributes of the `omnichannel_subscription_item` resource in the event content indicates the new term of the resubscribed item. The `item_id_at_source` attribute specifies the ID of the item at the source that the customer subscribed to. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_resubscribed`
`DID_CHANGE_RENEWAL_PREF`	`UPGRADE`	Scenario: When a customer upgrades to a subscription item that has a higher level than the currently subscribed item from the same subscription group. Description: The `item_id_at_source` attribute of the `omnichannel_subscription_item` resource in the event content specifies the ID of the item at the source that the customer upgraded to. The `current_term_start` and `current_term_end` attributes indicate the new term after the upgrade. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_upgraded`
	`DOWNGRADE`	Scenario: When a customer downgrades to a subscription item that has a lower level than the currently subscribed item from the same subscription group. Description: The subscription is scheduled for change with `change_type` as "downgrade" at the `scheduled_at` of `omnichannel_subscription_item_scheduled_change` and the `item_id_at_source` in scheduled_state specifies the item ID at source the customer will downgrade to. The `has_scheduled_changes` attributes in the `omnichannel_subscription_items` is set to true. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_change_scheduled`
		Scenario: When a customer reverts to the previous subscription, effectively canceling their downgrade. Description: The subscription scheduled for change is removed. The ID of the `omnichannel_subscription_item_scheduled_change` identifies the change that has been removed. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_scheduled_change_removed`
`DID_FAIL_TO_RENEW`	`GRACE_PERIOD`	Scenario: When a subscription item fails to renew due to a billing issue, the subscription enters into a grace period. Description: An item's subscription has failed to renew due to a billing issue, and the subscription is in the grace period. The grace period is decided based on the configuration in the App Store for a maximum of 28 days. Continue to provide service through the grace period while billing is retried. Subscription item status: `in_grace_period` Chargebee webhooks triggered: `omnichannel_subscription_item_grace_period_started`
`DID_FAIL_TO_RENEW`		Scenario: When a subscription item fails to renew due to a billing issue, the subscription enters a billing retry period. Description: An item's subscription has failed to renew due to a billing issue, and the subscription is in a dunning period. The App Store continues to retry billing for 60 days, or until the customer resolves their billing issue or cancels their subscription, whichever comes first. You can stop providing the subscription service upon receiving this notification. Subscription item status: `in_dunning` Chargebee webhooks triggered: `omnichannel_subscription_item_dunning_started`
`GRACE_PERIOD_EXPIRED`		Scenario: When the grace period of the subscription item expires, and the subscription continues in billing retry. Description: The grace period of an item's subscription is over and billing retry is still attempted. Upon receiving this notification, the omnichannel subscription state is changed from `in_grace_period` to `in_dunning`. You can stop providing the subscription service upon receiving this notification. The App Store continues to retry billing for the remaining days after the grace period, up to a maximum of 60 days, or until the customer resolves their billing issue or cancels their subscription, whichever comes first. Subscription item status: `in_dunning` Chargebee webhooks triggered: `omnichannel_subscription_item_grace_period_expired` `omnichannel_subscription_item_dunning_started`
`EXPIRED`	`VOLUNTARY`	Scenario: When the subscription of an item expires because the customer chooses to cancel it. Description: The `cancelled_at` and `cancellation_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item was cancelled and the reason for the cancellation, respectively. In this case, the cancellation reason is `customer_cancelled`. Subscription item status: `cancelled` Chargebee webhooks triggered: `omnichannel_subscription_item_cancelled`
	`PRICE_INCREASE`	Scenario: When the subscription for an item expires if the customer does not consent to a price increase for the subscribed item that requires their approval. Description: The `cancelled_at` and `cancellation_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item was cancelled and the reason for the cancellation, respectively. In this case, the cancellation reason is `customer_did_not_consent_to_price_increase`. Subscription item status: `cancelled` Chargebee webhooks triggered: `omnichannel_subscription_item_cancelled`
	`PRODUCT_NOT_FOR_SALE`	Scenario: When the subscription for an item expires if the developer removes the associated subscription item from sale, causing the renewal to fail. Description: The `expired_at` and `expiration_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item has expired and the reason for its expiration, respectively. In this case, the expiration reason is `product_not_available`. Subscription item status: `expired` Chargebee webhooks triggered: `omnichannel_subscription_item_expired`
	`BILLING_RETRY`	Scenario: When the subscription for an item expires if the billing retry period ends without successfully recovering the subscription. Description: The `expired_at` and `expiration_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item has expired and the reason for its expiration, respectively. In this case, the expiration reason is `billing_error`. Subscription item status: `expired` Chargebee webhooks triggered: `omnichannel_subscription_item_expired`
		Scenario: When a subscription to an item expires without any specific reason. Description: The `expired_at` and `expiration_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item has expired and the reason for its expiration, respectively. In this case, the expiration reason is `other`. Subscription item status: `expired` Chargebee webhooks triggered: `omnichannel_subscription_item_expired`
`DID_CHANGE_RENEWAL_STATUS`	`AUTO_RENEW_DISABLED`	Scenario: When a customer cancel the subscription Description: The subscription is cancelled at the `current_term_end` and does not auto renew. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_cancellation_scheduled`
`DID_CHANGE_RENEWAL_STATUS`	`AUTO_RENEW_ENABLED`	Scenario: When a customer subscribes again after canceling a subscription. Description: The cancellation is removed for the subscription and it is auto renewed at the `current_term_end`. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_scheduled_cancellation_removed`
`REFUND`		Scenario: When the subscription for an item is refunded. Description: The `cancelled_at` and `cancellation_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicate when the subscription was revoked and the reason for the revocation. Subscription item status: `cancelled` Chargebee webhooks triggered: `omnichannel_subscription_item_cancelled`
`REFUND_REVERSED`		Scenario: When a refund for a subscription is reversed. Description: The refund for the subscription is reversed. The subscription becomes `active`, and the `auto_renew_status` is set to `on`. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_reactivated`

The table below outlines various scenarios in which the Google Play Store triggers notifications or events. It details the types of these notifications and the corresponding omnichannel subscription events triggered by Chargebee.

Important

Here is the link to Google's Real Time Developer Notifications.
Chargebee will process the events associated with a subscription purchase only if they are recorded with Chargebee. Otherwise, incoming events will be marked as ignored, even if we support those event types.
Chargebee currently ignores notification types not listed in the following table. Support for these will be included in future releases.
While changing the subscription, Google provides multiple replacement modes. Currently, Chargebee only handles CHARGE_PRORATED_PRICE and DEFERRED modes.

Notification Type	Chargebee’s Response
`SUBSCRIPTION_RENEWED`	Scenario: When a subscription item successfully auto-renews. Description: The `current_term_start` and `current_term_end` attributes of the `omnichannel_subscription_item` resource in the event content indicates the new term after the renewal. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_renewed`
`SUBSCRIPTION_RENEWED`	Scenario: When a subscription item successfully auto-renews with a different product ID Description: The `id_at_source` attribute of the `omnichannel_subscription` resource will be changed to specify the latest purchase token associated with the subscription change. The `item_id_at_source` attribute of the `omnichannel_subscription_item` resource in the event content specifies the ID of the item at the source that the customer upgraded/downgraded to. The `current_term_start` and `current_term_end` attributes indicate the new term after the renewal. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_changed` `omnichannel_subscription_item_renewed`
`SUBSCRIPTION_PURCHASED`	Scenario: When a customer changes the subscription from the currently subscribed item to a different item with the `CHARGE_PRORATED_PRICE` replacement mode. Description: When the replacement mode is `CHARGE_PRORATED_PRICE`, the subscription change is applied immediately. The `id_at_source` attribute of the `omnichannel_subscription` resource will be changed to specify the latest purchase token associated with the subscription change. The `current_term_start` and `current_term_end` attributes of the `omnichannel_subscription_item` resource in the event content indicate the new term of the new item. The `item_id_at_source` attribute specifies the ID of the item at the source that the customer subscribed to. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_changed`
`SUBSCRIPTION_PURCHASED`	Scenario: When a customer changes the subscription from the currently subscribed item to a different item with the `DEFERRED` replacement mode. Description: When the replacement mode is `DEFERRED`, subscription change is scheduled to be applied at the end of the current term. The `has_scheduled_chanegs` attribute of the `omnichannel_subscription_item` resource in the event content indicates the scheduled changes. The `omnichannel_subscription_item_scheduled_change` resource contains the details of the change. Subscription item status: `active` Chargebee webhooks triggered: `omnichannel_subscription_item_change_scheduled`
`SUBSCRIPTION_CANCELED`	Scenario: When a customer cancels the subscription. Description: The subscription is canceled at the `current_term_end` and does not `auto_renew`. The `auto_renew` flag will be set to `off`, indicating the subscription will not `auto_renew` at the term end. Subscription item status: The `status` of the subscription is `active` till the end of the term, only after which it gets `cancelled`. Chargebee webhooks triggered: `omnichannel_subscription_item_cancellation_scheduled`
`SUBSCRIPTION_EXPIRED`	Scenario: When the subscription of an item expires because the customer chooses to cancel it. Description: The `cancelled_at` and `cancellation_reason` attributes of the `omnichannel_subscription_item` resource in the event content indicates when the subscription for an item was cancelled and the reason for the cancellation, respectively. In this case, the cancellation reason is `customer_cancelled`. Subscription item status: `cancelled` Chargebee webhooks triggered: `omnichannel_subscription_item_cancelled`

Processing Omnichannel Webhooks

Chargebee event for recording a purchase

Chargebee Event

Description

Mapping of Apple App Store notifications to Chargebee events

Notification Type

Subtype

Chargebee’s Response

Mapping of Google Play Store notifications to Chargebee events

Notification Type

Chargebee’s Response