Phased Rollout from Legacy to Omnichannel

This page describes the recommended four-phase plan to move from running Mobile Subscriptions (Legacy) and Omnichannel Subscriptions together to full migration and cutover. For what running both solutions together means, how sync notifications work, and webhook behavior during cutover, see Using the Legacy and New Omnichannel Solutions Together.

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.

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

   Note

   Before enabling notification sync, make sure all apps configured in the legacy solution are also connected in the Omnichannel solution. Otherwise, notifications from apps not yet connected in Omnichannel will still be received, creating unnecessary processing overhead.

3. Confirm sync notifications are enabled. Chargebee enables sync notifications so that new subscriptions recorded in the legacy solution on the test site are carried forward to Omnichannel.

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.

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.

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

2. Implement the Record a Purchase API to record new in-app subscription purchases directly in Omnichannel. For Apple, use StoreKit 2.0 transaction IDs. See Apple App Store and Google Play Store.

3. Handle Omnichannel webhook events for provisioning, reporting, and customer support workflows.

4. Retrieve Omnichannel subscriptions using the List Omnichannel Subscriptions API or the Chargebee UI to validate subscription state in your backend.

Test 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 Omnichannel via the Record a Purchase API.
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 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 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.