--- title: Migrating existing subscription contracts to Shopify description: >- Migrate existing subscription contracts to Shopify to continue charging existing subscribers. source_url: html: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts md: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#requirements) * [What you'll learn](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#what-youll-learn) * [Step 1: Import subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#step-1-import-subscription-contracts) * [Step 2: Create billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#step-2-create-billing-attempts) * [Import and bill contracts in bulk](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#import-and-bill-contracts-in-bulk) # Migrating existing subscription contracts to Shopify Migrating your existing subscriptions to Shopify will allow you to continue charging your existing subscribers without experiencing any disruption in service. In this tutorial, you’ll learn how to migrate existing subscription contracts to Shopify. *** ## Requirements This tutorial assumes that you've already completed the preceding tutorial to [migrate customer information](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information). *** ## What you'll learn In this tutorial, you'll learn how to do the following tasks: * Import subscription contracts * Create billing attempts *** ## Step 1: Import subscription contracts After you've created or updated Shopify's customer record, you can import the subscription contracts. [Subscription contracts](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionContract) include information about the variant, the plan, the payment method, and the billing and shipping addresses. To import subscription contracts you can use the [subscriptionContractAtomicCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionContractAtomicCreate) mutation. The following example creates a subscription contract including the customer that was previously imported, [the payment method](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information#step-2-import-payment-methods-for-customers) from the preceding step, and lines: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql mutation subscriptionContractAtomicCreate { subscriptionContractAtomicCreate(input: { customerId: "gid://shopify/Customer/1", nextBillingDate: "2024-06-01", currencyCode: USD, contract: { status: ACTIVE, paymentMethodId: "gid://shopify/CustomerPaymentMethod/869e7a39", billingPolicy: { interval: MONTH, intervalCount: 1, minCycles: 3 }, deliveryPolicy: { interval: MONTH, intervalCount: 1 }, deliveryMethod: { shipping: { address: { firstName: "John", lastName: "McDonald", address1: "33 New Montgomery St", address2: "#750", city: "San Francisco", provinceCode: "CA", countryCode: US, zip: "94105" } } }, deliveryPrice: 14.99, }, lines: [ { discounts: [ { recurringCycleLimit: 1, title: "Amazing discount", value: { fixedAmount: { amount: 1.1, appliesOnEachItem: true }, percentage: 1 } } ], line: { currentPrice: 29.99, customAttributes: [ { key: "Type", value: "Subscription" } ], pricingPolicy: { basePrice: 29.99, cycleDiscounts: [ { adjustmentType: FIXED_AMOUNT, adjustmentValue: { fixedValue: 29.99, percentage: 1.1 }, afterCycle: 1, computedPrice: 29.99 } ] }, productVariantId: "gid://shopify/ProductVariant/10079785100", quantity: 1, sellingPlanId: "gid://shopify/SellingPlan/11988072400", sellingPlanName: "Subscribe and save" } } ] }) { contract { id lines(first: 10) { nodes { id quantity } } } userErrors { field message } } } ``` ## JSON response ```json { "data": { "subscriptionContractAtomicCreate": { "contract": { "id": "gid://shopify/SubscriptionContract/1", "lines": { "nodes": [ { "id": "gid://shopify/SubscriptionLine/bc43bd4d-59ea-45fa-b276-4bac64ae3c96", "quantity": 1 } ] } }, "userErrors": [] } } } ``` Note Subscription contracts can be created without a payment method. However, the contract must be edited to include a payment method before a billing attempt can be created successfully for that subscription. An existing payment method that's been vaulted in Shopify can be used or customers can be directed to [customer accounts](https://help.shopify.com/manual/customers/customer-accounts/new-customer-accounts) in order to add a new payment method. To be notified of new payment methods, you can subscribe to the [customer\_payment\_methods/create](https://shopify.dev/docs/api/webhooks) webhook topic. These webhooks occur whenever a customer payment method is created. *** ## Step 2: Create billing attempts You need to create [billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt) to trigger the billing schedule of a contract. When billing attempts are successful, Shopify creates an order. The following mutation makes a billing attempt by specifying the required fields `subscriptionContractId` and `idempotencyKey` (a unique key generated by the client to avoid duplicate payments). In response to a successful mutation, the subscription contract is billed against its current [status](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract#step-1-query-the-available-contracts-on-the-store): ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql mutation { subscriptionBillingAttemptCreate( subscriptionContractId: "gid://shopify/SubscriptionContract/1", subscriptionBillingAttemptInput: { idempotencyKey: "abc123" } ) { subscriptionBillingAttempt { id errorMessage nextActionUrl order { id } ready } } } ``` ## JSON response ```json { "data": { "subscriptionBillingAttemptCreate": { "subscriptionBillingAttempt": { "id": "gid://shopify/SubscriptionBillingAttempt/593791910", "errorMessage": null, "nextActionUrl": null, "order": { "id": "gid://shopify/Order/148977776" }, "ready": true } } } } ``` For more information on creating billing attempts, refer to [Create a billing attempt](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt). *** ## Import and bill contracts in bulk You can also leverage the [`Bulk Operations API`](https://shopify.dev/docs/api/usage/bulk-operations/imports) to perform these operations on large numbers of contracts without incurring any API limit costs. *** * [Requirements](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#requirements) * [What you'll learn](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#what-youll-learn) * [Step 1: Import subscription contracts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#step-1-import-subscription-contracts) * [Step 2: Create billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#step-2-create-billing-attempts) * [Import and bill contracts in bulk](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts.md#import-and-bill-contracts-in-bulk)