Shopify Subscription Contract Export: What to Check Before You Trust the Data

A subscription contract export can look clean and still be unsafe.

The spreadsheet may have contract IDs, customer IDs, products, next billing dates, delivery cadence, prices, discounts, and status. The API response may be complete enough for a developer to move forward. The row count may even match the old platform.

None of that proves the subscriptions are ready to migrate.

Before a Shopify subscription migration, the export has to answer an operating question: can the team rebuild the customer, payment, product, billing, delivery, lifecycle, support, and renewal state without guessing? If the answer is no, the export is a starting point, not a source of truth.

Shopify's subscription contracts documentation describes the contract as the agreement for recurring purchases. The `SubscriptionContract` object defines what products to deliver, when to bill and ship them, and at what price. That is the technical object. The migration job is to prove the object still represents the customer relationship accurately.

Decide what the export has to prove

Do not start by asking for "all subscription data."

Start by writing down what the export must prove after cutover:

• Which customer owns each subscription.
• Which payment method can be charged.
• Which product, variant, selling plan, and quantity should recur.
• Which billing date comes next.
• Which delivery date comes next.
• Which discounts or credits still apply.
• Which contracts are active, paused, canceled, failed, prepaid, or pending review.
• Which lifecycle, support, finance, and inventory systems depend on the subscription state.

That list becomes the export spec. It also prevents a common migration failure: exporting what is easy to retrieve while missing the fields that decide whether the first renewal works.

Pull contracts in the shape migration will need

Shopify's `subscriptionContracts` query returns subscription contracts through the GraphQL Admin API and supports pagination. That matters because subscription data should be retrieved deliberately, not sampled from a convenient admin screen.

For migration planning, the export should preserve the relationships around each contract:

• Contract ID and status.
• Customer reference and contact details.
• Billing and delivery policy.
• Next billing date or billing-cycle state.
• Contract lines, product IDs, variant IDs, selling plan references, quantity, and price.
• Shipping address and billing address references where applicable.
• Payment method readiness or payment action needed.
• Discount, prepaid, trial, gift, or custom price logic.
• App ownership and any legacy platform identifier.
• Last successful billing event and next expected renewal event.

This is not about making the biggest possible data dump. It is about keeping the fields in a shape that can be reconciled, tested, and explained.

Reconcile customers before contracts

A contract cannot be trusted if the customer layer is weak.

Shopify's customer-information migration guide separates customer and payment-method work from contract migration. That order is useful operationally. The contract depends on the customer record, payment path, billing address, shipping address, and account context being ready first.

Before trusting the export, reconcile:

• Customer email and phone.
• Duplicate customer records.
• Account access and customer-portal ownership.
• Consent state for email and SMS.
• Shipping and billing addresses.
• Support notes or migration-review flags.
• Legacy subscriber ID mapped to the new Shopify customer ID.

If the old platform has one customer and Shopify has two possible matches, do not let the contract export decide for you. Resolve the customer identity before contracts move.

Separate billing cycles from order history

Subscription contracts are not the same as historical orders.

Shopify's billing-cycle documentation defines a billing cycle as the scheduled interval where a subscription contract attempts to bill a customer for a set of items. Shopify's order documentation and subscription references separate the order created by a purchase from the contract that governs recurring purchases.

That distinction matters in an export. Historical orders show what happened. The contract and billing cycle show what should happen next.

For migration QA, check both:

• Last successful order.
• Last failed payment or failed billing attempt.
• Next billing cycle.
• Delivery cadence.
• Fulfillment state for prepaid or delayed items.
• Refund, cancellation, skip, pause, or replacement history that affects the next cycle.
• Finance reconciliation needs.

If the export only captures order history, the team may know what customers bought but not what should renew. If it only captures contracts, support and finance may lose the context behind the next renewal.

Check products, variants, plans, and discounts

Contract lines are fragile during migration because product data changes.

A legacy subscription may point to a product that was renamed, merged, archived, bundled, replaced, or split into new variants. The customer sees a simple recurring item. The systems see product IDs, variant IDs, plan rules, price logic, discount handling, inventory settings, and shipping requirements.

Before trusting the export, test:

• Does each contract line map to an active Shopify product and variant?
• Does the selling plan match the old subscription promise?
• Is the recurring price still correct?
• Are discounts, prepaid credits, or custom prices represented cleanly?
• Are inventory and fulfillment rules different for recurring orders?
• Does a replacement product need customer approval or support review?

Shopify's subscription contract migration documentation includes variant, plan, payment method, billing address, and shipping address context for imported contracts. Those fields are not technical trivia. They decide whether the renewal will be correct.

Protect lifecycle and support state

The export also feeds the customer experience around the subscription.

Klaviyo, support, finance, warehouse, and customer-success workflows may all need subscription state. If the export labels everyone only as "active subscriber," the team can trigger the wrong flows after migration.

Separate the states that matter:

• Active and charge-ready.
• Active but payment action needed.
• Paused.
• Canceled but still inside a winback window.
• Prepaid with deliveries remaining.
• Gift purchaser or gift recipient.
• Failed payment.
• Product replacement needed.
• Support review needed.
• Migration QA hold.

Those states do not all need public customer messages on day one. They do need to stop the team from sending renewal, replenishment, failed-payment, winback, or support messages to the wrong people.

Test the export like a renewal, not a spreadsheet

The final test is not whether the file opens.

The final test is whether a sample of contracts can make it through the first renewal window:

• A normal active subscriber renews on the right date.
• A subscriber with a discount renews at the right price.
• A prepaid subscription ships without an unintended charge.
• A failed-payment subscriber enters the right recovery path.
• A paused subscriber stays paused.
• A canceled subscriber does not restart.
• A product replacement is routed for review.
• A gift subscription keeps payer and recipient state separate.
• Support can identify the contract from the customer record.
• Klaviyo receives the right lifecycle state after renewal.

If those scenarios fail, the export is telling the team where the migration still needs work. That is useful. It is not a reason to pretend the data is ready.

What Lake House Group checks before migration

When Lake House Group reviews a subscription migration, the export is not treated as a finished deliverable.

We use it as a reconciliation layer. We check customer identity, payment readiness, contract fields, billing cycles, products, variants, selling plans, discounts, delivery cadence, lifecycle state, support ownership, finance needs, and first-renewal QA. Then we decide which records can move automatically, which need cleanup, and which need manual review before launch.

The goal is not a clean spreadsheet. The goal is a subscription base that can renew correctly after the platform changes.

Related reading

• Shopify subscription migration for existing customers
• Shopify subscription billing cycle migration
• Shopify subscription migration communications
• Shopify gift subscription migration
• Shopify migration services