Documentation Index
Fetch the complete documentation index at: https://app.docs.circuly.io/llms.txt
Use this file to discover all available pages before exploring further.
What is Contract Migration?
Contract migration allows you to move existing subscription contracts from your previous system (e.g., the old Circuly custom solution or another subscription platform) into Shopify via Circuly Subscriptions. This is a one-time operation per customer migration, typically performed during onboarding to the Shopify app.How It Works
The migration tool:- Imports payment methods from your existing payment gateway into Shopify
- Creates subscription contracts in Shopify with the correct billing policies
- Backfills historical data (billing cycles, payment totals) into our local records
Prerequisites
Before starting a migration:- Customers must exist in Shopify — Import your customers into Shopify first (via CSV or API)
- Products and variants must exist — The products your subscribers are subscribed to must be in your Shopify catalog
- Payment gateway must be connected — Your payment gateway (Stripe, Braintree, Authorize.Net, or PayPal) must be configured as a payment provider in Shopify
- Customer payment references — You need the gateway-specific IDs for each customer’s payment method
Supported Payment Gateways
| Gateway | Required IDs |
|---|---|
| Stripe | customerId (cus_xxx) + paymentMethodId (pm_xxx) |
| Braintree | customerId + paymentMethodToken |
| Authorize.Net | customerProfileId + customerPaymentProfileId |
| PayPal | billingAgreementId |
What Gets Created
For each migrated subscription:- A Shopify subscription contract with the correct billing schedule
- A payment method linked to the customer’s existing card/account
- A local contract record with historical data (cycle count, billing totals)
Limitations
- Maximum 500 subscriptions per batch — For larger migrations, split into multiple batches
- Sequential processing — Contracts are created one at a time (~2-4 seconds each) to respect Shopify API rate limits
- No selling plan linkage — Migrated contracts are not linked to selling plans (this can be done later)
- Webhook dependency — Local record creation depends on Shopify webhooks firing after contract creation
Next Steps
Migrate from Stripe
Step-by-step guide for Stripe-based migrations