Docs
Omnichannel Subscriptions refer to a subscription model that allows businesses to manage and track subscriptions across multiple channels, such as web, mobile apps, and cloud marketplaces.
Every Omnichannel Subscription has a designated source that indicates where it was created. Like the subscription created in Apple will have the source as Apple App Store. This source owns the subscription and is responsible for its management. Chargebee relies on webhook events from these sources to update subscription statuses, meaning Chargebee's billing engine does not manage the subscription state.
This model is particularly beneficial for companies looking to leverage multiple sales channels to maximize customer engagement and revenue potential.
This solution is currently available only on the Apple App Store and exclusively in the US. Support for additional regions will be rolled out soon. Documentation for Omnichannel Subscription events is also coming soon.
While mobile app stores like Apple App Store provide the client side solution to implement in-app purchases in your App, you need to have server implementation for provisioning the paid content and maintaining the access control for your premium subscriptions. Chargebee provides the backend server infrastructure for managing these in-app purchases by directly integrating with the app server notifications and thus helps you run your business smoothly.
Following sections will help you understand the key concepts of the Omnichannel solution and how you can use this solution to solve your business problems.
Handle in-app purchases flow in your app using native billing libraries (like Storekit or Google billing library) or cross-platform libraries offered by Flutter or React Native. Use these libraries to present in-app products configured in the store to end users and allow them to make purchases. Since the client-side SDKs (i.e., iOS , Android , React Native or Flutter ) add very little value, these are currently not offered as part of the Omnichannel solution.
Since mobile app stores equip app developers with ways to implement paywalls and in-app purchases using client-side billing libraries, having client-side SDKs on top of these billing libraries adds very little value to App developers. Disadvantages associated with client-side SDKs
The perceived value of client SDKs is that they make implementation easier and quicker. Chargebee believes that quick implementation of billing methods can be achieved through proper implementation guides on top of the documentation provided by these stores, and this will be released soon.
Thus, currently, Chargebee doesn't provide client SDKs for implementing in-app purchases and recommends implementing in-app purchases using the billing methods offered by app stores. If you still think that there's a requirement to have client-side SDKs, you can reach out to us at omnichannel@chargebee.com
Once an in-app purchase is made in your app, you can pass this purchase information to Chargebee by invoking the Record a Purchase API with Apple transaction. Chargebee will immediately return the recorded_purchase resource and initiate the job for recording the purchase. Before recording the purchase, Chargebee will verify the transaction with the respective store and only the verified transaction will be recorded in Chargebee.
Upon successful recording of a purchase in Chargebee, an Omnichannel subscription and transaction are automatically created. As soon as the Omnichannel subscription is created, Chargebee triggers a webhook event omnichannel_subscription_created. This Omnichannel subscription resource represents the subscription from an external source in Chargebee. The source attribute of this subscription indicates the store where the purchase is made. These omnichannel subscriptions will be listed under Omnichannel head in the left navigation ons the Chargebee site.
Since the Omnichannel subscription represents the subscription from an external source, Chargebee's billing engine will not manage the renewals for this subscription. Chargebee does not provide any user interface or APIs to manage this subscription as this is owned by an external source.
This subscription needs to be managed outside Chargebee as recommended by the source like Apple where the purchase was made. Chargebee will fully rely on the server notifications from this source to manage the renewals and subscription state.
Omnichannel subscription model represents the subscription from an external source in Chargebee. Since there can be multiple items associated with a single omnichannel subscription, the status of the subscription is maintained at an item level from futuristic perspective.
Here's the mapping of omnichannel subscription status to Apple App Store subscription status.
| Omnichannel Item Subscription Status |
Auto-Renewal Status |
Apple Subscription Status |
Description |
|---|---|---|---|
| active |
ON / OFF |
active |
The customer is entitled to access the product/service, and if the auto_renew_status is ON, the subscription will renew at the end of the billing period. If the auto_renew_status is OFF then though the subscription status is Active at present, it will be cancelled at the end of the period. |
| expired |
Not Applicable |
expired |
The subscription is expired and the customer should no longer have access to the product/service. The source like Apple, can expire the subscription due to payment collection failure. |
in_dunning and in_grace_period. Although Omnichannel serves as a representation of subscriptions from external sources, you may want to review specific transactions and events from the source, such as the Apple App Store, to confirm the subscription status in Chargebee.
To view Transactions and Events for an app linked to Chargebee, go through these steps.
This setup enables you to ensure the subscription's status in Chargebee aligns accurately with the data from the external source.
Upon successful in-app purchase, the end user should be given access to the paid content immediately. So it is recommended to grant access to the content as soon as the purchase transaction is verified by the source.
In the case of in-app purchases made using Apple's Storekit 2 framework, Apple takes care of this verification at the time of purchase . Thus, access to the content can be given if the transaction is verified.
However if you rely on Chargebee webhook events for the downstream actions like enabling entitlements, then you need to rely on omnichannel_subscription_created event webhook event for provisioning content to the end user.
Since the invoice is issued by the source where the purchase was made, Chargebee will not issue any invoice to the end user for Omnichannel subscriptions.
Since the price configuration structure of in-app products is different from Chargebee's item price structure, Omnichannel subscription is. not associated with the item price in Chargebee. Item ID at source attribute in the Omnichannel subscription resource can be used to check the product ID in the source to which the subscription belongs.
There's a separate set of webhook events associated with Omnichannel subscription. You need to rely on these webhook events to manage the subscription state at your end.
An omnichannel solution creates a single source of truth for purchases made across Apple and Web storefronts, minimizes the integration efforts involved in managing these disparate channels, and maximizes revenues through data insights and workflows. Here are some key use cases that you can achieve through this capability.
Currently, the omnichannel solution only supports Apple subscriptions in Chargebee. In the future, it will support Google and other storefronts like the Amazon app store, Roku, etc.
As a business selling on the web and Apple storefronts, you may want to provide a seamless experience to your customers by allowing them to start their subscription on one channel such as mobile and continue to access the subscribed content on another such as your website.
Example:
John purchases premium sports news content on a mobile app but would prefer to read the same on his desktop browser and thus login to the website. Upon login, you can invoke the list omni-subscriptions API with the customer ID of John and check for the active subscriptions. Since he has an active Apple subscription, you can allow him to access his favorite sports news content on the desktop browser and thereby avoiding duplicate subscriptions.
Building a subscription engine that integrates with Apple APIs and notification events requires significant effort, including staying updated with Apple's changes. Instead of diverting valuable development resources to tackle this unrelated challenge, focus on streamlining efforts to address your core business problems.
Example:
Acme Inc. offers exercise videos through an app available on the Apple App Store, but premium subscriptions are only available via their website due to Apple's in-app purchase requirements. With a significant number of mobile users, the company needs to invest engineering resources to build a subscription solution from scratch.
Instead, Acme Inc. can integrate Apple's paywall for in-app purchases and leverage Chargebee's backend infrastructure for provisioning, notifications, and subscription management, allowing them to focus on their core offering.
Omnichannel Subscriptions solution ensures that subscriptions from external marketplaces are not managed by Chargebee's billing engine. This guarantees an accurate representation of external store subscriptions within Chargebee. Thus, you can rely on the subscription state in Chargebee and ensure that only eligible users get access to the paid content.
Example:
Acme Inc. is into health and fitness videos on monthly and annual subscription plans. John purchases a monthly subscription plan for $20 per month and soon realizes that he can get more value with an annual plan of $100 per month. So he upgraded his subscription by visiting the settings page of the App Store and thus is now eligible for the upgraded content. Acme Inc. can rely on Chargebee's upgrade webhook event and grant access to upgraded content immediately.
Customers expect fast, immediate responses, especially on mobile in-app purchases. Chargebee's real-time sync with Apple lets you quickly view transaction and subscription changes, enabling you to address queries efficiently and enhance customer relationships.
Example:
John purchased a travel app subscription through the Apple App Store but now wants to cancel it since he has no travel plans in the near future. He is uncertain whether canceling will result in immediate loss of access to the content (i.e., travel itineraries) or if he can continue using it until the end of the current billing period. He reaches out to customer support for clarification.
Without Chargebee, the support agent wouldn't have access to John's information since Apple doesn't share customer data. John would need to contact Apple Support for this cancellation query, but they wouldn't be able to assist with questions about saved or browsed travel itineraries, as they lack context on the app's offerings.
However, with Chargebee, customer data is linked to Apple subscription details. This allows the support agent to view John's subscription information directly. The agent can then confirm how long John can continue accessing the content and when the current billing term will end, providing him with accurate and timely assistance.
When Apple app subscribers have queries about payments, cancellations, or premium content access, Chargebee's omni-subscription feature provides a quick overview of their status. For deeper insights into the subscription lifecycle, you can access detailed Apple transaction and event data through Chargebee's Apple Purchase Information page. Leveraging Apple APIs, this page provides real-time transaction details along with information on Apple products and offers. This functionality enables you to efficiently troubleshoot subscription issues and reach out to Apple customer care when necessary.
Example:
Acme Inc. offers artists basic and premium plans on the Apple App Store for distributing their music globally. The basic plan provides promotional guidance, while the premium plan allows publishing with top music companies.
When artist John downloads Acme's app and purchases the basic plan, he quickly decides to upgrade to the premium plan for better opportunities. However, after upgrading through the App Store settings, he still cannot access top music labels and contacts Acme support.
Upon checking John's customer ID in Chargebee, the Acme support team finds that his subscription hasn't been upgraded. They escalate the issue to their technical team, who can easily check John's Apple purchase information in Chargebee to verify whether the upgrade transaction occurred, rather than dealing with Apple APIs.
If the upgrade is confirmed in Apple, Acme will reach out to Chargebee support to investigate why the upgrade event wasn't triggered. If not, they will inform John that the upgrade failed in Apple and advise him to retry.
Chargebee allows enterprises to link multiple Apple apps and accounts to a single site, providing a unified view of subscriptions across all apps. This helps you gain valuable insights across apps and accounts to make informed business decisions.
Example:
Acme Inc. offers health and fitness services through two apps, Yoga and Gym, on the Apple Store. After acquiring ABC Inc., which provides Diet and Wellbeing apps, Acme now manages all four apps under two Apple accounts. With Chargebee, Acme can view and analyze subscriptions for all apps in one site, using filters to track performance by app. Here's how the apps will be available in Chargebee:
Acme Inc
ABC Inc.
Omnichannel subscription currently represents only in-app subscription purchases made on the Apple App Store. We will be extending this solution to the Google Play Store by Q2 2025 and to Chargebee web subscriptions by the end of 2025. Therefore, the limitations stated below apply only to Apple App Store integration.
Currently, there's no provision to link the in-app products configured in the App Store Connect to Chargebee's product catalog. So you'll not be able to view the in-app products configured in your App Store Connect account in Chargebee's Product Catalog. To get the information about the Apple product, you can access the Omnichannel subscriptions page or the purchases page.
Offers like Introductory, Promotional, Win-Back, and Offer Codes associated with products in App Store Connect cannot be viewed in Chargebee's product catalog as Apple offers are currently not linked to Chargebee. If these offers are availed during the in-app purchase, then this information will be available on the Purchases page.
Customer records cannot be created through record purchase API. So before invoking the record purchase API, a customer record needs to be created in Chargebee, and the created customer ID needs to be passed while invoking the record purchase API.
A customer record associated with an active Omnichannel subscription can be deleted in Chargebee. This means that there can be Omnichannel subscriptions in Chargebee without a customer record, so it is recommended to double-check the Omnichannel subscription associated with the customer before deleting the customer record.
Omnichannel subscriptions can only be created in Chargebee by invoking the Record a Purchase API with a valid Apple transaction. Since Apple introduced the transaction concept for devices with iOS15+ OS, purchases made in lower versions of devices cannot be recorded using this API.
Chargebee's Record a Purchase API operates asynchronously as invoking this API triggers verification of signed Apple transactions, which is a third-party operation and is not in Chargebee's control. So you may experience some delay in receiving the omnichannel_subscription_created event from Chargebee. However, upon invoking Record a Purchase API, the recorded_purchase object is returned synchronously. You can use the ID of the recorded_purchase to invoke Retrieve a Recorded Purchase API and get the status of recorded purchase. If the recording of the purchase is completed successfully in Chargebee, then Omnichannel Subscription ID and Omnichannel Transaction ID will also be available as part of the recorded_purchase object.
If offers are associated with in-app subscriptions, the omnichannel subscription will be created in Chargebee with the offer price, but the details of the offer will not be present on the details page.
Currently, one-time purchases made for in-app products configured in App Store Connect cannot be recorded in Chargebee.
Omnichannel subscriptions are fully managed with Apple notifications and cannot be modified in Chargebee. This means that they are read-only subscriptions, and operations like edit, cancel, pause, etc. will not be applicable to them.
Currently, Chargebee supports only limited events from the App Store, and thus, only the following subscription operations are possible on Omnichannel subscriptions through Apple events: Renewal, Upgrade, Downgrade, Cancel, Revoke, and Reactivate. Learn more.
Omnichannel subscriptions consume only App Store V2 server notifications; thus, if you have configured V1 notifications in App Store Connect, then make sure that it is changed to V2. Learn more on how to configure the notifications URL in App Store Connect.
Chargebee's dunning capabilities are not applicable for Omnichannel subscriptions as the stores directly handle the payment retries for failed transactions.
When a payment fails through Apple's payment system, Apple will automatically attempt to process the payment again for a period of 60 days. Learn more.
Currently, Omnichannel subscriptions are not integrated with Revenue Story, so you need to build your analytics engine by relying on Omnichannel subscription events.
The transaction information present in the Omnichannel transaction resource indicates the amount paid by the end user at the time of the transaction. Thus, it includes the commission amount charged by Apple as well as the taxes paid by the end user. So consider this amount for calculating gross revenue only.
For Revenue recognition, please refer to the Revrec solution of Chargebee.
As Apple owns the subscription, it generates invoices and sends these directly to the end user. Since Chargebee doesn't have access to these invoices, these invoices cannot be imported or generated in Chargebee.
Since Apple owns the invoice, accounting, and taxation, the Omnichannel transactions in Chargebee are not transmitted to any downstream accounting and tax integrations of Chargebee. It is recommended to rely on the reports generated by Apple to understand sales and proceeds for the purchases made on the store.
The new Omnichannel solution for the Apple App Store cannot be enabled for your Chargebee site if the Multi Business Entity feature is enabled for it.