Migrating subscriptions between platforms

A "subscription" in a merchant's head is one object. In two systems it is three, and pulling them apart is what makes the project estimable.

The plan. Shopify calls this a selling plan: the delivery, pricing and billing policies attached to products. It is configuration, it is small, and you rebuild it rather than migrating it. This is also the moment to stop reproducing plans nobody has bought since 2023 — a migration is the cheapest catalogue rationalisation you will ever get.

The contract. The agreement between one customer and you: which variants, how often, at what price, next billing on what date, shipping to where. Shopify models this as a subscription contract, and the documentation describes contracts moving through active, paused, failed, cancelled and expired states. This part is a data import and it is tractable.

The credential. The stored means of taking money. This is the one that decides whether the project is a fortnight of engineering or a customer communications campaign, and it is the one that never appears on the first plan.

Card numbers are not yours to move. They live in a gateway vault under someone's PCI scope, and no reputable platform will hand you a spreadsheet of them. What can move is a reference, and which references are available depends entirely on a fact about your old setup that is worth establishing before anything else: whose gateway was billing your subscribers?

If you keep the gateway, you keep the vault. This is the good case. Shopify's customerPaymentMethodRemoteCreate mutation exists precisely for it — it imports payment methods from external gateways and associates them with a Shopify customer record, and Shopify names Stripe, Authorize.Net and Braintree as the gateways it covers. You are moving a pointer, not a card, and the customer is never asked to do anything.

If you are leaving the gateway, you need a vault transfer. Gateways do run PCI-compliant vault migrations between one another, but they are a commercial and operational process with lead times, not an API call. Start it before you scope the build, because the answer sometimes comes back "not for your card mix" and that changes the project rather than delaying it.

If the old platform was the merchant of record, assume you are starting again. Where the subscription platform held the merchant relationship rather than you, the credentials are theirs. Every subscriber has to re-authorise, and that is not a migration, it is a re-acquisition campaign with a migration attached. Know this on day one and budget for the churn honestly rather than discovering it at cutover.

One implementation detail that catches people: the remote import is asynchronous. Shopify is explicit that the returned payment method may be incomplete at first and instructs you to "use the customerPaymentMethod query to retrieve the payment method status until all details are available or the payment method is revoked." That means the migration is a job with a reconciliation pass, not a script that prints a success count. Anything left incomplete when you reconcile is a contract that will fail its first billing attempt.

Once credentials exist in Shopify, the contracts follow. The documented input to subscriptionContractCreate is a useful checklist because every field is something you must have extracted correctly from the old system: customerId, currencyCode and nextBillingDate are required at the top level, and the contract object carries status, paymentMethodId, billingPolicy, deliveryPolicy, deliveryPrice and deliveryMethod. The scope is write_own_subscription_contracts, alongside the manage_orders_information permission.

Two things follow from reading that list carefully.

The first is that nextBillingDate is the field carrying all the risk. It is the difference between a customer's next box arriving on time and it arriving twice, or not at all. Extract it, do not derive it — recomputing "every 30 days from the start date" against a contract that has been paused twice and skipped once will produce a date that is plausible and wrong, and plausible-and-wrong is precisely the kind of error that survives review.

The second is a versioning check to do before estimating. Shopify's documentation marks subscriptionContractCreate and its draft-based flow as deprecated in favour of the SubscriptionContractCalculation API, which uses a calculate-poll-commit pattern instead. Whether your migration writes the old flow or the new one depends on the API version your app targets, and the two are different enough that finding out mid-build costs real days. Read the current reference for your version rather than a tutorial, this one included.

The scopes themselves are worth a conversation with both vendors. They are named read_own_subscription_contracts and write_own_subscription_contracts, and what an app can observe across a store during a parallel run is exactly what determines whether you can verify the migration from inside Shopify or have to reconcile against exports. Ask both sides before you design the verification step.

Everything else on this page is recoverable. Charging a customer twice in one week is not — it is a refund, a support ticket, a chargeback risk and, for a subscription business, an immediate cancellation. So the cutover rule is absolute: at no point may two billing engines hold a live credential for the same subscriber. Freeze billing on the old platform before you import the first contract, and verify the freeze rather than trusting a toggle.

Given that constraint, cohort by billing date. Take the subscribers billing furthest out first, migrate them, and let them bill on the new platform while the near-term cohorts are still running on the old one. Each cohort gives you a real billing run against real credentials before the next one moves, and the blast radius of a bad assumption is one week of subscribers rather than the whole base.

Two other things belong in the plan. Rehearse the whole extract-transform-load against a copy first, with the billing step pointed at nothing, and compare counts and totals field by field — a dry run that only proves the script completes has proved nothing. And decide in advance what a failed first billing attempt means: a natural rate of decline exists on any book of subscriptions, so you need the old platform's baseline failure rate to hand, or you will spend cutover week unable to tell a broken import from a Tuesday.

Where re-authorisation is unavoidable, Shopify provides customerPaymentMethodSendUpdateEmail, which sends the customer a link to update a vaulted payment method and is documented for exactly the expiring-or-declined case. It is a good tool and a bad plan: use it to recover the tail, not to move the base. Sequence the emails so the ask arrives close to a delivery the customer is looking forward to, not three weeks before anything happens.

A subscription migration asks every one of your best customers to notice you. That is the cost, and it is not on the quote. Against it, two reasons people give for moving, only one of which survives.

"The platform is too expensive." Usually not worth it. Model the fee difference over two years against the engineering, the vault transfer, the churn from any cohort that has to re-authorise, and the support load. For most mid-market books the saving arrives in year three, assuming nothing goes wrong, and something goes wrong. If the only complaint is the invoice, go and negotiate the invoice.

"We cannot build the thing the business needs." This one is worth it. A platform that cannot express your bundle logic, cannot offer the pause-and-swap behaviour that keeps people subscribed, or cannot be integrated with the ERP is blocking revenue rather than costing money, and no negotiation fixes that. Migrate deliberately, cohort by cohort, with the credential question answered before anything else is scoped.

And a third, quieter case: if you are migrating the storefront anyway, migrate the subscriptions at a different time. Doing both in one weekend means that when a billing run looks wrong you will not know whether the cause is the contracts, the catalogue or the theme. Separate the variables. The calendar is the cheapest risk control available.

• Shopify subscriptions & Recharge
• Subscriptions natively or with a platform?
• The migration dry run