Phased Migration from Legacy to Omnichannel Solution

This page describes the recommended four-phase plan to migrate from a coexistence setup of Mobile Subscriptions (Legacy) and Omnichannel Subscriptions to the Omnichannel solution.

Refer to Using the Legacy and New Omnichannel Solutions - Coexistence Mode to understand the coexistence setup of Mobile Subscriptions (Legacy) and the new Omnichannel solutions.

Progress through these phases on a schedule that fits your app release and customer upgrade plans.

Phase 1 — Set up both solutions on your test site

Complete these steps on your Chargebee test site:

1. Ask Chargebee to enable both solutions on your test site. Contact Chargebee Support or your account team to enable running the legacy and Omnichannel solutions together on your test site. Mention that you want to enable the Omnichannel solution in coexistence mode.

2. Connect your Apple and Google apps to the Omnichannel solution. For Apple, follow Apple App Store steps. For Google, follow Google Play Store steps.

3. Ask Chargebee to enable sync from the legacy solution to the new solution. Contact support and mention that all the apps are reconnected to Chargebee and request support to enable syncing of new subscriptions and notifications from the legacy solution to the new Omnichannel solution on the test site.

   Note

   Before enabling this sync, make sure all apps configured in the legacy solution are also connected in the Omnichannel solution. Otherwise, notifications from apps not yet connected to the Omnichannel solution will still be received by the new Omnichannel solution and processing will fail for these notifications.

4. Configure Google notifications while both solutions run together. On the existing Pub/Sub topic used by your legacy Google integration, add a subscription that delivers notifications to the Omnichannel notification URL. See How subscription sync works while both solutions run together and the Google Play Store notification setup.

   Note

   For Apple store notifications, there is no need to change the notifications URL configured in App Store Connect.

5. Test the Omnichannel solution on your test site. Verify that new legacy-originated subscriptions appear in Omnichannel and that your downstream workflows behave as expected without any changes to your legacy solution.

   Note

   Testing the new Omnichannel webhook events is optional at this stage but recommended, as you'll need to migrate to the new solution in the future. Ensure your backend consumes these webhook events and that downstream workflows, such as provisioning entitlements and revoking access, function correctly with the new Chargebee Omnichannel events.

Phase 2 — Enable both solutions on your live site

After you validate Phase 1 on your test site, enable both solutions on your Chargebee live site by repeating Phase 1 steps 1–5 on the live site.

Keep your legacy integration and notification URLs unchanged during this phase. Running both solutions together on the live site does not require changes to your production app or legacy mobile SDK integration.

Phase 3 — Implement the new Omnichannel integration on your test site

Build and validate the new app integration against your test site before releasing to production:

1. Create new Apple and Google app listings (or test app variants) for the Omnichannel integration, separate from the apps tied to your legacy integration where required by your release plan.

   Note

   If you are using Chargebee's mobile SDK, use the native App Store and Play Store methods to create these new apps. We don’t support mobile SDKs in the new Omnichannel solution due to the reasons mentioned here.

2. Implement the Record a Purchase API at your server side to record new in-app subscription purchases made in your app directly into the new Omnichannel solution. For Apple, use StoreKit 2.0 transaction IDs for recording Apple purchases while invoking the record. See Apple App Store and Google Play Store documentation.

   Note

   1. It is recommended to use StoreKit 2.0 transaction IDs and Apple V2 notifications for recording and managing Omnichannel subscriptions.
   2. If you are using Chargebee's mobile SDK, use the native App Store and Play Store methods to update your apps. This may need a new version of the app to be published in Apple and Google stores. Please note we don’t support Chargebee’s mobile SDKs in the new Omnichannel solution due to the reasons mentioned here.

3. Handle Omnichannel webhook events for provisioning, reporting, and customer support workflows. This step can be ignored if you have already tested the Omnichannel webhook events for your downstream workflows in Phase 1.

   Note

   You can retrieve Omnichannel subscriptions using the List Omnichannel Subscriptions API or the Chargebee UI to validate successful subscription creation and updates in your backend.

Test all these flows on your test site while both solutions remain active for legacy-originated subscriptions.

Phase 4 — Live migration and cutover to Omnichannel

When your new Apple and Google apps are ready for production:

1. Release and validate live app subscriptions. After the new apps are live, confirm that subscriptions purchased through the new app flow are recorded correctly in the Omnichannel solution via the Record a Purchase API using the transaction or token ID received from your client app.
2. Complete full migration of existing subscriptions. Proceed with full migration to import existing legacy subscriptions into Omnichannel. Chargebee can assist with this import. You can also perform a self-service migration by invoking the Record a Purchase API in a script, subject to Chargebee and store rate limits. See Full migration prerequisites and the Importing Historic Data guide to understand the process. See also the Omnichannel Subscriptions Migration Guide.
3. Update notification URLs to Omnichannel. After migration is complete and validated, update the notification URLs in App Store Connect and Google Cloud Platform to point to the Omnichannel solution's notification URLs for your apps. This is the final step in the migration moving away from the legacy solution. Until this step is complete, both solutions continue to run together and both legacy and Omnichannel webhook events can fire for subscriptions.