What happens to active subscription contracts' billing cycles and payment tokens when migrating subscribers between any platform and Shopify's subscription data model?
Two contract-level fields decide whether a subscriber migration succeeds: nextBillingDate and the payment method reference. Shopify requires nextBillingDate on every imported contract and treats it as "independent of billing cycles", and payment methods import through customerPaymentMethodRemoteCreate only from Stripe, Braintree, PayPal Express or Authorize.net connected as a secondary gateway (per Shopify's docs, September 2026).
Field one: the billing anchor
nextBillingDate is a non-null input on subscriptionContractAtomicCreate, and Shopify documents it as "the next billing date for the subscription contract. This field is independent of billing cycles" (per Shopify's GraphQL Admin API reference, September 2026). That independence is the useful part and the dangerous part. It means you set the anchor explicitly rather than inheriting it from a cadence, so a contract imported with the wrong date will bill on the wrong date, confidently, with no cycle arithmetic to catch you.
The billingPolicy carries interval, intervalCount and minCycles. Those describe the rhythm. nextBillingDate describes when the music starts. Import them from two different sources and the subscriber gets charged twice or not at all.
Field two: the payment mandate
A vaulted payment token is not a portable file. It is a reference held by a processor, scoped to a merchant account, and it works on Shopify only if that same processor is attached to the Shopify store. Shopify supports four as secondary gateways for exactly this purpose: Stripe, Braintree, PayPal Express and Authorize.net (per Shopify's Help Center and developer docs, September 2026). Skio's own guidance is to move to Stripe or Authorize.net first if the current gateway is incompatible (per Skio, September 2026), which tells you how narrow the door is.
What actually breaks when the gateway changes
Nothing transfers. There is no "export tokens" path between unrelated processors, because the mandate was granted to that processor under its own PCI scope. The realistic options are two:
- Slow drip. Keep the old processor connected as a secondary gateway and let payment methods move to the primary one naturally as cards expire and customers update billing. Shopify says this "can take months or even years" (per Shopify's Help Center, September 2026).
- Re-collect. Ask subscribers to add a card. Every re-collection request is a cancel decision you have invited, which is where subscriber loss concentrates.
The PayPal exception worth knowing before you promise anything
"PayPal billing agreements belong to the account that created them. If the new account can't use the previous account's agreements, then existing renewals can fail" (per Shopify's Help Center, September 2026). And PayPal billing agreements cannot be migrated through Shopify's Professional Services at all. If a meaningful share of your subscribers pay by PayPal, that share needs its own plan and its own risk line.
One idempotency detail. subscriptionBillingAttemptCreate requires an idempotencyKey, documented as "a unique key generated by the client to avoid duplicate payments" (per Shopify's docs, September 2026). During a parallel billing run, that key is the only thing standing between a retry and a double charge.
The Deploi point of view
Our own position, from building on Shopify. Separate from the facts above.
- Our take: Decide the gateway question before the platform question. Whether you can keep the processor is upstream of which subscription app you choose, and reversing that order is how migrations acquire a surprise re-collection campaign halfway through.
- What we’ve seen: The anchor date is where the errors land. Cadence imports cleanly because it is a rule; nextBillingDate is a value, and values arrive from spreadsheets that were exported three days before anyone ran the import.
- Where we disagree: The category talks about "migrating payment tokens" as though tokens are the thing that moves. The token stays exactly where it is. What moves is a reference to it, and only inside the same processor relationship, which is why the honest question is never "can we migrate tokens" but "can we keep this processor".
- What this page adds: the two specific fields that carry the risk, the exact API wording that makes nextBillingDate independent of cycles, and the PayPal billing-agreement exception that no contract-level import touches.
Reviewed by Martin Dejnicki, Director of SEO & AI Search. Facts verified 2026-09-13.