Migrate from Stripe

Overview

This guide walks you through migrating subscription contracts from a Stripe-based system to Circuly Subscriptions on Shopify.

Step 1: Prepare Your Data

You need to export your subscription data into a JSON file. Each subscription requires:

The Shopify customer ID (the customer must already exist in Shopify)
The Stripe customer ID (cus_xxx) and payment method ID (pm_xxx)
The Shopify product variant ID for the subscribed product
Billing details (price, interval, next billing date)
The customer’s delivery address

JSON Format

Your file must be a JSON array of subscription objects:

[
  {
    "shopifyCustomerId": "gid://shopify/Customer/123456789",
    "paymentReference": {
      "gateway": "stripe",
      "customerId": "cus_abc123",
      "paymentMethodId": "pm_def456"
    },
    "productVariantId": "gid://shopify/ProductVariant/987654321",
    "recurringPrice": "29.99",
    "currencyCode": "EUR",
    "billingInterval": "MONTH",
    "billingIntervalCount": 1,
    "nextBillingDate": "2026-04-01",
    "deliveryAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      "address1": "Musterstr. 1",
      "city": "Berlin",
      "zip": "10115",
      "country": "DE"
    },
    "status": "ACTIVE"
  }
]

Required Fields

Field	Type	Description
`shopifyCustomerId`	string	Shopify customer GID (`gid://shopify/Customer/XXX`)
`paymentReference.gateway`	string	Must be `"stripe"`
`paymentReference.customerId`	string	Stripe customer ID (`cus_xxx`)
`paymentReference.paymentMethodId`	string	Stripe payment method ID (`pm_xxx`)
`productVariantId`	string	Shopify variant GID (`gid://shopify/ProductVariant/XXX`)
`recurringPrice`	string	Price per billing cycle (e.g., `"29.99"`)
`currencyCode`	string	ISO 4217 currency code (e.g., `"EUR"`, `"USD"`)
`billingInterval`	string	`"WEEK"`, `"MONTH"`, or `"YEAR"`
`billingIntervalCount`	number	Number of intervals between charges
`nextBillingDate`	string	ISO date for the next charge (e.g., `"2026-04-01"`)
`deliveryAddress`	object	Customer’s shipping address
`status`	string	`"ACTIVE"` or `"PAUSED"`

Optional History Fields

Include these to preserve billing history from your old system:

Field	Type	Description
`currentCycleIndex`	number	How many billing cycles have completed
`totalBilled`	string	Total amount billed to date (e.g., `"179.94"`)
`totalPaid`	string	Total amount paid to date
`cyclesBilled`	number	Number of successful billing cycles
`minCycles`	number	Minimum commitment cycles
`maxCycles`	number	Maximum cycles before auto-cancel

Step 2: Find Your IDs

Shopify Customer IDs

You can find customer GIDs in the Shopify admin URL. When viewing a customer, the URL contains the numeric ID: admin.shopify.com/store/your-store/customers/123456789 The GID format is: gid://shopify/Customer/123456789

Stripe IDs

In your Stripe Dashboard:

Customer ID: Found on the customer detail page (starts with cus_)
Payment Method ID: Found under the customer’s payment methods (starts with pm_)

Shopify Variant IDs

Product variant IDs can be found in the Shopify admin URL when editing a variant, or exported via the Shopify Products CSV export.

Step 3: Run the Migration

Navigate to the Migration page in the Circuly Subscriptions app
Upload your JSON file using the drop zone
Review the validation preview — check that all subscriptions show as “Valid”
Click Migrate to start the process
Wait for the migration to complete (approximately 2-4 seconds per subscription)
Review the results — download the results JSON for your records

Step 4: Verify

After migration:

Check the Subscriptions page in Circuly — migrated contracts should appear
Open a few contracts in the Shopify admin to verify billing policies
Check the customer portal — migrated contracts should be visible to customers
Verify payment methods on customer records in Shopify admin

Troubleshooting

Validation Errors

These errors appear during the file upload/validation step:

Error	Solution
”Customer ID is required”	Add a `shopifyCustomerId` field with a valid string value
”Customer ID must be a Shopify GID”	Use the format `gid://shopify/Customer/123456789`
”Product variant ID is required”	Add a `productVariantId` field with a valid string value
”Product variant ID must be a Shopify GID”	Use the format `gid://shopify/ProductVariant/123456789`
”Payment reference is required”	Add a `paymentReference` object with `gateway`, `customerId`, and `paymentMethodId`
”Unsupported gateway”	Use one of: `stripe`, `braintree`, `authorize_net`, `paypal`
”Recurring price must be a positive number”	Provide a numeric string greater than zero (e.g., `"29.99"`)
“Currency code is required”	Add an ISO 4217 currency code (e.g., `"EUR"`, `"USD"`)
“Billing interval is not supported”	Use `WEEK`, `MONTH`, or `YEAR`
”Billing interval count must be at least 1”	Provide a number >= 1
”Next billing date must be a valid date”	Use ISO date format (e.g., `"2026-04-01"`)
“Delivery address is required”	Add a `deliveryAddress` object with shipping details
”Status is not supported”	Use `ACTIVE` or `PAUSED`

Migration Errors

These errors appear after migration starts:

Error	Error Code	Solution
”Payment method import failed”	`PAYMENT_IMPORT_FAILED`	Check that Stripe is connected as a payment provider in Shopify
”Payment method was revoked”	`PAYMENT_METHOD_REVOKED`	The Stripe payment method may be invalid or expired
”Payment method not ready after 30s”	`PAYMENT_METHOD_TIMEOUT`	The payment method import is taking too long — retry or check Shopify admin
”Contract creation failed”	`CONTRACT_CREATION_FAILED`	Check that the product variant exists and the billing policy is valid
”ContractRecord not found after waiting”	`BACKFILL_RECORD_NOT_FOUND`	The webhook may not have fired — check webhook logs in the app
”Invalid customer GID”	`INVALID_CUSTOMER_GID`	Use the format `gid://shopify/Customer/123456789`
”Invalid variant GID”	`INVALID_VARIANT_GID`	Use the format `gid://shopify/ProductVariant/123456789`
”Invalid recurring price”	`INVALID_PRICE`	Provide a numeric string greater than zero (e.g., `"29.99"`)
“Invalid billing interval count”	`INVALID_INTERVAL_COUNT`	Provide a number >= 1
”Invalid next billing date”	`INVALID_BILLING_DATE`	Use ISO date format (e.g., `"2026-04-01"`)
“Payment reference requires…”	`INVALID_PAYMENT_REFERENCE`	Ensure all required fields for the gateway are provided
”Unsupported payment gateway”	`UNSUPPORTED_GATEWAY`	Use one of: `stripe`, `braintree`, `authorize_net`, `paypal`

Getting Started

Rental Engine

Extensions

Integrations

Migration

Resources

Overview

Step 1: Prepare Your Data

JSON Format

Required Fields

Optional History Fields

Step 2: Find Your IDs

Shopify Customer IDs

Stripe IDs

Shopify Variant IDs

Step 3: Run the Migration

Step 4: Verify

Troubleshooting

Validation Errors

Migration Errors

​Overview

​Step 1: Prepare Your Data

​JSON Format

​Required Fields

​Optional History Fields

​Step 2: Find Your IDs

​Shopify Customer IDs

​Stripe IDs

​Shopify Variant IDs

​Step 3: Run the Migration

​Step 4: Verify

​Troubleshooting

​Validation Errors

​Migration Errors

Overview

Step 1: Prepare Your Data

JSON Format

Required Fields

Optional History Fields

Step 2: Find Your IDs

Shopify Customer IDs

Stripe IDs

Shopify Variant IDs

Step 3: Run the Migration

Step 4: Verify

Troubleshooting

Validation Errors

Migration Errors