/ Journal — Migration
Migrating Subscription Customers to Shopify: What Needs More Than a CSV
s
A standard ecommerce migration can move products, customers and order history with structured files. Subscription customers are different. The value is not only in a customer row or an order row; it sits in an active agreement that must keep charging the right payment method, on the right date, for the right products and price.
( Short answer )
Migrate subscription customers as contracts, not just records.
That is why Shopify migration subscriptions projects need more than a CSV import. They require coordinated work across Shopify, the current subscription platform, the destination subscription app, payment gateways, customer consent, operations and finance. A technically successful import can still fail commercially if billing dates shift, prepaid entitlements disappear, retry rules reset or customers are asked to re-enter cards unexpectedly.
Short answer Contracts, not rows
Migrate subscription customers as contracts, not just records.
Preserve the customer-to-payment-method relationship, contract status, product and variant mapping, quantity, price, discount, billing and delivery cadence, next charge date, prepaid balance, shipping details, taxes and failed-payment state. Rehearse the migration, pause source billing during the controlled cutover, import in dependency order, reconcile every population and prove a billing cycle before retiring the old system.
/ Why it’s different
Why a subscription migration is not a normal customer import.
A customer CSV can tell Shopify who someone is. It cannot, by itself, authorize a future off-session charge or recreate the complete commercial agreement. Shopify represents recurring purchases through subscription contracts. Those contracts reference customers, products or variants, payment methods, billing policies, delivery policies, prices, addresses and other terms. The practical migration unit is therefore a linked graph of records.
If one dependency is absent, the contract may import but not behave like the source. This is the central risk in a Shopify subscription migration: record completeness is not the same as continuity.
01The Shopify customer and source customer identifier
02The reusable payment method or an approved route to continue charging it
03The subscription contract and its current status
04One or more contract lines mapped to valid Shopify variants
05Billing and delivery schedules, including the next billing date
06Discounts, shipping price, currency, tax treatment and addresses
07Operational history such as failed attempts, skips, pauses or prepaid deliveries
/ Discovery audit ( 07 )
Start with a contract-level discovery audit.
Before selecting a migration method, profile the live subscription population. Do not use the headline “active subscribers” number as the only scope. Segment contracts by platform, gateway, payment type, currency, cadence, product structure and exception state.
( Area — questions to answer before build — why it matters )
01Contract status. Active, paused, cancelled, expired, pending, prepaid or delinquent? Determines which records move and their destination state.
02Payments. Which gateway holds the credential? Card, PayPal, wallet or another method? Determines whether payment methods can be referenced, migrated or must be recaptured.
03Cadence. Are billing and delivery intervals the same? Are there anchors or custom dates? A monthly charge can fund weekly deliveries; one frequency field is not enough.
04Products. Do contracts contain retired SKUs, bundles, gifts or custom line items? Every line needs a deliberate Shopify variant or exception treatment.
05Pricing. Fixed legacy price, percentage discount, tiered price, first-order incentive or manual override? Recalculating from today’s catalogue can change the customer’s agreement.
06Failure state. How many attempts have failed, when is the next retry, and what messages were sent? Resetting dunning can over-contact customers or delay revenue recovery.
07Consent. What terms were accepted, when, in which market and for which payment method? Supports lawful and defensible continuation of recurring billing.
Export raw source data and keep it immutable. Build a separate normalized migration dataset and a transformation log. That separation makes reruns, audit and reconciliation possible without altering source evidence.
/ Payment tokens
Payment tokens are the first feasibility gate.
Merchants often ask to “move the cards.” In practice, the migration usually works with provider-controlled tokens or remote payment-method references rather than readable card data. A normal export should not expose primary account numbers or security codes, and a CSV containing customer details does not make a payment credential portable.
Shopify’s subscription migration documentation describes supported paths for customer payment methods associated with gateways including Stripe, Braintree, PayPal Express and Authorize.net. The exact route depends on the source gateway, the destination setup and Shopify’s current eligibility and API requirements. For example, Shopify documents legacy subscription gateway connections for continuing to charge certain existing contracts while new or updated contracts can use Shopify Payments. It also notes constraints: Shopify’s Stripe migration path supports credit cards, specialized charge flows can increase authorization failures, Braintree legacy subscription billing has multi-currency limitations, and PayPal requires the appropriate reference-transaction capability.
( Per payment cohort )
Treat gateway compatibility as a discovery deliverable.
Not an implementation detail. For each payment cohort, record:
+Source gateway account and merchant entity
+Payment-method type and token format
+Customer reference and billing address relationship
+Supported Shopify or app migration path
+Currency and market limitations
+Required permissions, approvals and lead times
+Fallback if the credential cannot be migrated
+Test evidence that a migrated method can be charged successfully
Payment-method creation can be asynchronous. Shopify’s guidance recommends monitoring customer payment-method create, update and revoke webhooks because an initial response does not prove that the method is ready. Do not create dependent contracts until each required method has reached the expected usable state.
( Important )
One working test card proves one cohort.
Token portability Test every cohort
Never assume all token populations are portable because one test card worked.
Test each gateway, payment type, currency and relevant account configuration. If a cohort must re-authorize, design that as a customer conversion journey with clear timing, consent and support, not as a surprise after launch.
/ Consent
Preserve consent and the commercial agreement.
A payment token is not the whole authority to charge. Retain evidence of what the customer agreed to: recurring amount or calculation, frequency, trial terms, cancellation terms, material notices, timestamp, source, terms version and any market-specific disclosure. Work with qualified legal and payments advisers where consent requirements or cross-entity data transfers are unclear.
Migration is also the wrong moment to silently replace contractual terms. If prices, cadence, seller entity or customer rights must change, identify which cohorts require notice or fresh agreement. Store the source contract ID and consent evidence in an appropriate secure system so support and finance can trace a Shopify contract back to the original agreement.
Marketing consent is separate from subscription billing consent. Do not infer email or SMS marketing permission from the existence of a paid subscription.
/ Contract mapping ( 08 )
Map Shopify subscription contracts field by field.
Shopify defines a subscription contract as the recurring purchase arrangement for a customer. Its billing and delivery policies control when charges and fulfillments occur, while contract lines define products, quantities and pricing. A robust mapping specification should include every field required to reproduce behavior, plus explicit treatment for data that has no direct destination.
Shopify provides an atomic contract creation mutation for migration scenarios, but the API call is only the final loading mechanism. Most of the difficult work is upstream: cleaning identities, resolving variants, preserving commercial rules and deciding what to do with exceptions.
Source concept Destination decision and acceptance test
CustomerMatch or create the Shopify customer using stable identifiers and controlled duplicate rules.
Acceptance test: Correct customer, address, market and external ID.
Contract statusMap active, paused, cancelled, failed and other states deliberately.
Acceptance test: No cancelled contract becomes billable; paused behavior is retained or documented.
Product lineMap source SKU/variant to a live Shopify variant and selling plan.
Acceptance test: Correct product, quantity, price and customer-facing name.
Billing policyMap interval, interval count, minimum/maximum cycles and next billing date.
Acceptance test: Next three expected charge dates match the source schedule.
Delivery policyMap separately from billing, including prepaid deliveries.
Acceptance test: Next three expected fulfillment dates match.
Payment methodAttach the successfully migrated or remotely referenced method.
Acceptance test: Controlled billing attempt succeeds with the expected gateway.
MoneyPreserve currency, current price, delivery price and discount logic.
Acceptance test: Order-level totals match approved expected values.
AddressesMap contract billing and shipping addresses, not only the customer default.
Acceptance test: Generated order routes and taxes correctly.
/ Schedules
Schedules require more than “every month”.
Frequency is rarely a single field. Preserve the interval, interval count, anchor date, timezone, next billing date and next delivery date. Account for end-of-month behavior, daylight saving changes, skipped cycles, paused periods and manual date changes.
Prepaid subscriptions need special attention because billing and fulfillment diverge. A customer might have paid for six deliveries upfront and already received two. Recreating that as an ordinary monthly subscription could charge them again before the remaining four deliveries are fulfilled. Record paid-through dates, remaining entitlements and the event that triggers the next renewal.
Test schedules by calculating at least the next three billing and delivery events for representative and edge-case contracts. A visually correct contract in an admin screen is not sufficient evidence.
/ Discounts and legacy prices
Discounts and legacy prices must be reconstructed, not guessed.
Subscriptions often contain pricing that no longer exists on the storefront: grandfathered prices, fixed line overrides, “first three orders” discounts, free shipping, retention offers, gifts or manually negotiated terms. Decide whether each value is contractual, promotional or safely recalculated.
Shopify contracts can hold line pricing and recurring-cycle discount information. However, the source app’s promotion model might not map one-to-one to the destination app’s behavior. Build test cases for:
+Percentage and fixed-amount discounts
+Discounts that expire after a number of cycles
+Free or reduced shipping
+Grandfathered unit prices after catalogue changes
+Multi-line contracts where only some lines are discounted
+Tax-inclusive and tax-exclusive markets
+Currency rounding and minimum charge rules
Compare the expected next order total, not just the displayed discount label. Finance should approve any rounding tolerance before migration.
/ Failed payments and dunning ( 03 )
Failed payments and dunning state need an explicit policy.
01 · State
Delinquent is not simply active or inactive.
A delinquent contract may carry an attempt count, last failure reason, next retry time, retry strategy, recovery link, grace period and a series of customer notifications. Moving it without that context can restart the retry sequence, send duplicate emails or leave a recoverable customer untouched.
02 · Segments
Decide per population.
Segment contracts into clean active, currently retrying, exhausted, paused because of payment failure and scheduled-to-cancel populations. Decide whether to finish dunning on the source platform, migrate the state, or exclude and reactivate customers through a controlled campaign. The answer depends on app capability and cutover length.
03 · Idempotency
Never charge twice.
Define idempotency for billing attempts. Re-running a migration or job must not produce a second charge. Use unique source references, deterministic migration IDs and a ledger of attempted, succeeded, failed and reversed actions.
/ Choosing the app ( 10 )
Choose the destination subscription app before finalizing the model.
Shopify supplies the subscription primitives, but merchants usually operate subscriptions through an app such as Shopify Subscriptions or a specialist platform. Apps differ in migration support, portal experience, bundles, prepaid plans, dunning, analytics, APIs, webhooks and operational controls.
Ask shortlisted vendors to confirm, in writing, how they handle your actual cohorts. A generic claim that migration is supported is not enough.
( Ask every vendor )
01Which source platforms and gateways have a documented migration path?
02Who owns token coordination and what approvals are required?
03Can legacy prices, prepaid balances, mixed cadences and bundles be preserved?
04Can failed-payment attempt state and next retry timing be migrated?
05How are source IDs stored and exposed for reconciliation?
06Are contract imports API-driven, vendor-assisted or file-based?
07What validation reports are provided before and after import?
08Can the platform support a pilot cohort and repeatable delta loads?
09What customer emails are suppressed during migration?
10What are the rollback, support and incident-response arrangements?
Evaluate the full operating model as well as feature lists. Customer service needs to edit contracts, finance needs reliable reconciliation, developers need observable APIs and customers need a usable portal after the move.
/ The migration sequence
( 11 stages )
The correct migration sequence.
Dependencies should determine sequencing. Shopify’s own migration guidance puts customer and payment-method preparation before contract creation. For an established business, the wider release plan usually looks like this:
01
Stage 01
Discover and segment
Inventory contracts, gateways, exceptions, consent and operational dependencies.
02
Stage 02
Design the destination
Configure Shopify, products, variants, selling plans, delivery profiles, taxes, discounts, the app, portal and communications.
03
Stage 03
Establish identity maps
Link source customers, source variants and source contracts to stable Shopify records.
04
Stage 04
Prove payment paths
Complete gateway approvals and validate each payment cohort in a safe environment or approved pilot.
05
Stage 05
Import or match customers
Resolve duplicates before attaching payment methods.
06
Stage 06
Create and verify payment methods
Wait for asynchronous status confirmation.
07
Stage 07
Create contracts
Attach the verified customer, payment method, mapped lines, terms and next dates.
08
Stage 08
Reconcile the pilot
Compare source and destination at field, cohort and financial levels.
09
Stage 09
Rehearse the production run
Measure duration, exceptions and operator steps with production-scale data.
10
Stage 10
Cut over in a controlled freeze
Stop source changes or capture them as a final delta, then prevent parallel billing.
11
Stage 11
Validate and resume
Enable destination billing only after launch gates pass.
On every project, in writing: [ You see the work as it happens ] [ A short note every Friday ] [ Founder on every call ] [ Everything in your accounts ] Why we work this way →
/ Reconciliation ( 04 )
Reconciliation is the proof of migration.
“Imported successfully” usually means the loader did not reject the row. It does not prove the subscription will generate the correct order. Reconcile at four levels.
01 · Population
Population reconciliation
Compare counts by status, gateway, currency, cadence, app, market and exception category. Every source contract should have one disposition: migrated, deliberately excluded, cancelled, re-authorization required or unresolved.
02 · Field
Field-level reconciliation
Compare customer, product, quantity, current price, discount, currency, next billing date, delivery cadence, address, payment-method reference and status. Use automated comparisons for the full population and human review for high-value and unusual contracts.
03 · Financial
Financial reconciliation
Calculate expected recurring revenue and next-cycle charge totals before and after migration. Break differences down by known rounding, exclusions and defects. Include prepaid liabilities and remaining deliveries, not only monthly recurring revenue.
04 · Behavioral
Behavioral reconciliation
Generate or simulate representative billing attempts and orders. Verify payment routing, tax, shipping, inventory, fulfillment, notifications, analytics, support visibility and customer portal behavior.
/ Customer communication
Customer communication without creating avoidable churn.
Not every behind-the-scenes migration needs a dramatic announcement. Communication should be driven by customer impact and legal obligations. Explain what is changing, what is not, when it happens and whether action is required.
Customers may need targeted messages when they must set a new account password, re-authorize a payment method, use a new portal, expect a changed statement descriptor or accept changed terms. Keep action-required cohorts separate from no-action cohorts. Avoid phishing-like requests for card details by email; send customers to an authenticated, branded flow.
Prepare customer service with searchable source-to-destination IDs, screenshots, macros and escalation routes. Give them clear answers for missing subscriptions, wrong next dates, unexpected charges, expired cards, portal access and cancellations. Track contacts by migration reason so systemic issues surface quickly.
/ Cutover runbook ( 10 )
Cutover controls that prevent double billing.
Shopify explicitly recommends pausing billing in the current application while migrating customer payment methods and contracts to avoid double-billing. Build that control into a timed cutover runbook rather than relying on someone to remember it.
( Cutover runbook )
01Choose a lower-volume window with no major campaign or renewal spike.
02Record the source cutoff timestamp and export the final delta.
03Pause source billing, retries and customer notifications as planned.
04Prevent contract edits in both systems, or queue and replay approved changes.
05Import customers and verify payment methods before creating contracts.
06Load contracts with deterministic IDs so the job can be retried safely.
07Reconcile counts, dates, values and exceptions before destination billing starts.
08Run controlled end-to-end charges for approved test contracts.
09Enable destination billing and monitor attempts, orders and downstream systems.
10Keep the source platform read-only and accessible until formal retirement.
Define the rollback boundary in advance. Once destination charges and customer edits begin, “rollback” may mean a forward-fix with carefully reconciled state rather than simply switching the old system back on.
/ After launch
What to monitor after launch.
The first renewal cycle is the real production test. Monitor daily and compare against a pre-migration baseline.
Keep a migration exception register with owner, severity, affected contracts, customer impact, workaround and final resolution. Do not decommission the source data or gateway relationship until finance and operations can complete a full-cycle reconciliation.
01Billing attempts, success rate and failure codes by gateway
02Duplicate, missing or early charges
03Orders generated per expected renewal cohort
04Average subscription order value and discount variance
05Tax, shipping and currency anomalies
06Skips, pauses, cancellations and payment-method updates
07Portal login and contract-edit failures
08Support volume and complaint categories
09Fulfillment exceptions and prepaid delivery balances
10Revenue, processor settlements and app reports
( How we approach it )
How Signature Works approaches Shopify subscription migration.
We treat subscription migration as a revenue-continuity project inside the wider Shopify build. The work starts with contract and gateway discovery, not an import template. We map source behavior to Shopify and the selected subscription app, prototype the difficult cohorts, automate repeatable transformations and build reconciliation into the migration tooling.
Our launch plan connects catalogue mapping, theme subscription UX, accounts, payment methods, app configuration, fulfillment, analytics and customer support. That avoids a common failure mode where the contracts technically move but the rest of the customer and operating journey is incomplete.
/ FAQ ( 08 )
Subscription migration, answered.
Can Shopify subscriptions be migrated with a CSV?
A CSV can help transport customer, product and contract data, but it cannot by itself recreate chargeable payment credentials or prove that the destination contract behaves correctly. Most migrations also require gateway coordination, payment-method creation or referencing, API or vendor-assisted contract loading, and post-import reconciliation.
Can existing subscription payment tokens be moved to Shopify?
Sometimes, but portability depends on the source gateway, payment type, merchant account setup, destination app and Shopify’s supported migration paths. Stripe, Braintree, PayPal Express and Authorize.net each have different requirements and constraints. Validate every cohort with Shopify, the gateway and the app before promising a seamless move.
Will subscription customers need to enter their card details again?
Not always. Supported token or remote payment-method migration paths can allow existing customers to continue without re-entering card details. Unsupported gateways or payment types may require re-authorization. Identify those customers early and provide a secure, branded update flow.
How do you avoid charging subscription customers twice during migration?
Use a controlled billing freeze, record the cutoff, pause source charges and retries, load the final delta, verify payment methods and contracts, reconcile the destination, then enable billing in one system only. Shopify’s migration documentation specifically recommends pausing current billing while payment methods and contracts are migrated.
Can grandfathered subscription prices and discounts be preserved?
Often, provided they are extracted and mapped explicitly. Test fixed legacy prices, percentage and fixed discounts, limited-cycle promotions, shipping incentives and multi-line rules against expected next-order totals. Do not assume the destination app will reconstruct them from today’s product price.
What happens to failed payments during a Shopify subscription migration?
Decide whether the source system will finish the retry sequence or whether attempt state can be carried into the destination. Preserve the last failure, attempt count, next retry and customer communications where possible. Never reset dunning unintentionally or retry a charge without idempotent controls.
How long does a Shopify subscription migration take?
Timing depends less on subscriber count than on gateway approvals, number of payment cohorts, contract complexity, source data quality, app support and required customer action. Discovery and token feasibility should happen early; rehearsals should prove the production run duration before a cutover is scheduled.
Which Shopify subscription app is best for a migration?
The best app is the one that supports your required gateway path, contract types, prepaid and bundle behavior, pricing rules, dunning, customer portal, integrations and reconciliation needs. Test vendors against real contract cohorts rather than choosing from feature lists alone.
Technical capabilities and platform requirements change. Confirm the current Shopify, payment-gateway and subscription-app documentation for your exact setup before production migration.
/ Next
Planning a subscription move to Shopify?
Signature Works can assess the source platform, payment gateways, app options and contract complexity before you commit to a cutover date. We can then design, build, test and reconcile the migration as part of a Shopify or Shopify Plus replatform.
Also worth a look: Migrations and rescues · Store audits · Shopify technical ownership
/ Next
Want this done on your store?
Tell us what’s going on. A first look costs nothing.