Migration playbook: Recharge to subZwallet

Switching subscription apps mid-operation is one of the highest-risk changes a Shopify merchant can make. Get it wrong and you face failed renewals, confused customers, and a support backlog that takes weeks to clear. This playbook gives you the exact sequence for a Recharge to subZwallet migration that protects revenue continuity and customer experience.

The two most common migration failures are rushed cutovers without parity validation and unclear ownership across teams. This guide eliminates both by giving you a phased approach with checklists, timelines, and templates you can follow step by step. If you are evaluating whether to switch, see the full Recharge vs subZwallet comparison at /recharge-alternative.

How Shopify subscription migration works

Shopify's Subscriptions API handles migration in two phases: settings first, then data. You configure selling plans and portal settings in subZwallet, then create subscription contracts using the subscriptionContractAtomicCreate mutation. Payment methods are migrated separately using CustomerPaymentMethodRemoteCreate, which transfers vaulted tokens from Stripe or Braintree without requiring customers to re-enter card details (https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts).

Key platform constraints to plan around: past subscription events (pauses, skips, plan changes) cannot be imported into Shopify. Contracts tied to Recharge are auto-cancelled 48 hours after Recharge is uninstalled. Customer payment methods survive app uninstall. Shopify recommends pausing billing during the migration window to prevent duplicate charges (https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/ux-for-migration).

Diagram showing the two-phase migration flow: settings configuration then data migration

Feature parity matrix: Recharge vs subZwallet

Before starting any migration work, map every Recharge feature you use to its subZwallet equivalent. This matrix covers the most common features. For each row, confirm whether the feature transfers automatically, requires manual setup, or has a behavior difference you need to communicate to customers.

Feature | Recharge | subZwallet | Migration status ---|---|---|--- Recurring billing | Subscription charges on schedule | Native Shopify billing via contracts | Automatic after contract creation Billing frequency options | Weekly, monthly, custom intervals | Weekly, biweekly, monthly, custom intervals | Manual setup — recreate each selling plan Prepaid subscriptions | Prepaid multi-cycle plans | Prepaid subscription plans | Manual setup — recreate plan structure Subscription discounts | Percentage or fixed discounts per plan | Percentage, fixed amount, or free shipping per plan | Manual setup — recreate discount rules Pause subscription | Customer-initiated pause | Customer-initiated pause with configurable duration | Automatic after portal setup Skip next delivery | Per-cycle skip from portal | Per-cycle skip from portal | Automatic after portal setup Product swap | Swap products within subscription | Swap products within subscription | Automatic after portal setup Cancel flow | Basic cancellation | Configurable cancel flow with save offers, surveys, and alternatives | Manual setup — build cancel flow in subZwallet Dunning / failed payment retry | Configurable retry schedule | Configurable retry schedule with smart timing | Manual setup — configure dunning policy Customer portal | Hosted portal page | Embedded portal in store theme | Manual setup — configure portal widget Email notifications | Upcoming charge, order confirmation | Upcoming charge, order confirmation, failed payment | Manual setup — configure notification templates Analytics | Recharge dashboard | subZwallet analytics dashboard | No migration — starts fresh Rewards / loyalty | Recharge rewards add-on | Built-in subscription rewards | Manual setup — configure reward tiers Subscription API access | Recharge API | Shopify Subscriptions API + subZwallet API | Requires integration updates

Feature parity matrix showing Recharge features mapped to subZwallet equivalents

Migration timeline: 10-day example

This timeline assumes a store with 500-2,000 active subscribers, standard billing cadences, and a support team of 2-3 people. Scale the timeline proportionally for larger subscriber bases or more complex setups.

Day 1-2: Planning and ownership. Name a single migration owner. Export full subscriber data from Recharge. Audit active selling plans, discount rules, and dunning policies. Define success metrics: billing success rate, cancellation rate, support ticket volume, and portal login success.

Day 3-4: Configuration. Install subZwallet (/shopify-subscription-app). Recreate all selling plans, frequencies, and discount rules. Configure the customer portal, cancel flows, and dunning policy. Set up email notification templates.

Day 5-6: Test cohort migration. Select 50-100 subscribers covering edge cases (multi-item, heavy discounts, recent failures). Migrate their payment methods and create contracts. Run validation scenarios: renewal, skip, pause, cancel, failed payment retry.

Day 7: Fix and re-validate. Address issues found in test cohort. Re-run failed scenarios. Get sign-off from migration owner and support lead.

Day 8: Customer communication. Send pre-migration email to all subscribers (see template below). Update help center and support macros.

Day 9: Full migration. Pause billing in Recharge. Migrate remaining payment methods and contracts in bulk using Shopify's Bulk Operations API. Verify contract counts match.

Day 10: Launch-day runbook. Resume billing in subZwallet. Monitor first renewal cycle. Keep one Slack/Teams channel for incidents, one for customer comms approvals. Run post-migration QA checklist (below).

Visual timeline showing 10-day migration phases from planning through launch

Phase 1: Planning and ownership

Migration fails most often when ownership is split across departments with no single point of accountability. Before any technical work begins, establish these foundations.

Name a single migration owner with authority across support, lifecycle, and engineering decisions.
Export your full subscriber dataset from Recharge: active contracts, plan details, discount rules, payment methods, and subscription event history (this history will not import into Shopify, but you need it for reference and reporting).
Document every active selling plan, billing cadence, discount behavior, and dunning policy currently running in Recharge.
Define success metrics for the first 30 days: billing success rate, cancellation rate, support ticket volume, and retention-save action acceptance rates.
Create a decision log for cutover rules: what triggers a rollback, who approves go/no-go, and escalation contacts for launch day.
Set customer-facing communication windows and prepare response templates before announcing any dates.

Migration planning checklist with ownership assignments and success metrics

Phase 2: Feature parity mapping

Map every active selling plan, cadence, discount behavior, and subscription state to a subZwallet equivalent. Use the parity matrix above as your starting point. For each mapping, document the expected customer-visible behavior at four moments: renewal, skip/pause, product swap, and cancellation.

If any behavior cannot be mapped exactly, write the accepted difference and the customer message explaining the change before proceeding. Common differences include: portal URL changes, email template appearance, and the addition of cancel-flow save offers that did not exist in Recharge.

Plan frequency and billing schedule parity confirmed.
Discount and reward behavior parity confirmed.
Customer portal actions parity confirmed (pause, skip, swap, cancel).
Email and notification parity confirmed for billing and lifecycle events.
Dunning retry policy parity confirmed for failed payments — see /help/how-to-set-up-dunning for configuration details.
Cancel flow configured with save offers, surveys, and alternatives.
All accepted differences documented with customer-facing explanations.

Phase 3: Test cohort migration and validation

Do not migrate your full subscriber base without validating on a representative test cohort first. Select 50-100 subscribers that cover your most complex scenarios: multi-item subscriptions, discount-heavy plans, recently failed payments, and high-support-contact customers.

The migration sequence for each subscriber is: (1) migrate payment method using CustomerPaymentMethodRemoteCreate, (2) create subscription contract using subscriptionContractAtomicCreate, (3) verify the contract appears correctly in subZwallet and the customer portal (https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information).

Validation scenarios to test

Successful renewal: standard cadence subscription renews on schedule with correct discount applied.
Failed payment flow: payment fails, dunning retries trigger on schedule, final action (pause or cancel) executes correctly.
Customer-initiated pause: customer pauses from portal, subscription status updates, resume works correctly.
Skip next delivery: customer skips next cycle from portal, billing adjusts to next scheduled date.
Product swap: customer changes product within subscription, next renewal reflects the new product.
Cancellation with save offers: customer initiates cancellation, sees save alternatives (skip, delay, swap, discount), accepts or declines.
Support-agent actions: agent modifies subscription from admin, changes appear in audit trail and customer portal.
Prepaid subscription: multi-cycle prepaid plan renews correctly at cycle end.

Test cohort validation results showing pass/fail status for each scenario

Customer communication template

Send this email 48-72 hours before the migration window. Customize the bracketed sections for your brand.

Subject: Update to your [Brand Name] subscription management Hi [First Name], We are upgrading the system that manages your [Brand Name] subscription. This change happens on [Date] and improves your ability to manage deliveries, pause or skip orders, and update payment details. What this means for you: - Your subscription continues without interruption. Same products, same schedule, same price. - Your payment method stays on file. You do not need to re-enter your card. - Your customer portal moves to a new URL: [New Portal URL]. Bookmark this page. - You now have more control: pause for a set duration, skip individual deliveries, or swap products directly from your portal. What you need to do: Nothing. Your subscription transfers automatically. If you have questions, reply to this email or contact [Support Email]. Our support team is standing by through [Date + 7 days] for any subscription-related questions. [Brand Name] Team

Phase 4: Full migration and launch-day runbook

After your test cohort validates successfully and your customer communication is sent, execute the full migration.

Pause all billing in Recharge to prevent charges during the migration window.
Run bulk payment method migration using Shopify's Bulk Operations API.
Run bulk contract creation. Verify total contract count matches your Recharge export.
Spot-check 20-30 migrated contracts for correct plan, frequency, discount, and next billing date.
Enable billing in subZwallet.
Monitor the first renewal cycle in real time. Keep one channel open for incidents, one for customer comms.
Prioritize customer-impacting issues first: failed renewals, portal access failures, and high-value subscriber tickets.

Keep Recharge installed (but inactive) for 48 hours after cutover as a safety net. Only uninstall Recharge after you have confirmed all contracts are active in subZwallet and the first renewal cycle has completed without critical issues.

Post-migration QA checklist

Complete every item on this checklist before declaring the migration successful. Each item should have a named owner and a verified timestamp.

Total active contracts in subZwallet matches expected count from Recharge export.
Billing success rate for first renewal cycle is equal to or higher than pre-migration baseline.
Customer portal loads correctly and subscribers can log in.
Pause, skip, swap, and cancel actions work from the customer portal.
Dunning retries trigger on schedule for failed payments.
Cancel flow displays save offers, surveys, and alternatives correctly.
Email notifications fire for upcoming charges, order confirmations, and failed payments.
Discount rules apply correctly at renewal (percentage, fixed amount, free shipping).
Prepaid subscription plans renew at cycle end with correct billing.
Support team can modify subscriptions from the Shopify admin and subZwallet dashboard.
Analytics dashboard shows accurate subscriber counts and revenue figures.
All selling plans display correctly on product pages and at checkout.

Post-migration QA checklist with verification status for each item

Post-launch: first 14 days

Days 1-3: Monitor billing success and failed-payment cohorts daily. Compare to pre-migration baseline.
Days 1-3: Track support ticket volume. Tag all subscription-related tickets for pattern analysis.
Days 4-7: Review cancellation reasons and save-action acceptance rates. Adjust cancel flow offers if acceptance is below 15%.
Days 4-7: Tighten support macros based on real ticket patterns observed in the first 3 days.
Day 7: Run a 7-day retro with migration owner, support lead, and lifecycle operations. Document what worked, what broke, and what to change for next time.
Days 8-14: Shift from daily monitoring to every-other-day checks. Begin optimizing dunning, cancel flows, and rewards based on initial data.
Day 14: Final migration sign-off. Compare 14-day metrics to pre-migration baselines. Uninstall Recharge if not already done.

How to measure migration success

Track these four metrics daily for 14 days, then weekly for the next 30 days.

Metric | What it measures | Target | How to track ---|---|---|--- Billing success rate | Percentage of renewal attempts that succeed on first try | Equal to or higher than pre-migration baseline | subZwallet analytics dashboard > Billing Cancellation rate | Percentage of active subscribers who cancel per week | No increase vs pre-migration baseline | subZwallet analytics dashboard > Churn Support ticket volume | Subscription-related tickets per day | Return to pre-migration levels within 7 days | Helpdesk filtered by subscription tag Portal login success | Percentage of portal access attempts that succeed | Above 95% | subZwallet analytics dashboard > Portal

Common mistakes and how to avoid them

Mistake: Migrating without a parity matrix. Result: customers encounter unexpected behavior changes and flood support. Fix: complete the feature parity matrix and sign off on every accepted difference before touching production.

Mistake: Informing the support team on launch day. Result: agents cannot answer subscription questions and escalate everything. Fix: share ticket playbooks, escalation paths, and response templates at least 48 hours before cutover.

Mistake: Declaring success when contracts are created. Result: billing failures, portal issues, and dunning problems surface days later. Fix: use the post-migration QA checklist and track metrics for a full 14 days before signing off.

Mistake: Uninstalling Recharge immediately after migration. Result: no fallback if critical issues appear. Fix: keep Recharge installed but inactive for at least 48 hours after the first successful renewal cycle. Remember that contracts auto-cancel 48 hours after the owning app is uninstalled.

Next steps

After migration is complete, set up the operational systems that protect your subscriber revenue. Configure your dunning policy to recover failed payments — see /help/how-to-set-up-dunning. Build retention flows and cancel-flow save offers — see /help/manage-subscriptions. Review subscription plan configurations — see /help/subscription-plans. For a full walkthrough of subZwallet features, start at /help/getting-started.

If you are still evaluating whether to switch from Recharge, see the full comparison at /recharge-alternative or explore subZwallet's subscription management features at /shopify-subscription-app.