---
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
api_name: admin
---

# Migrating existing subscription contracts to Shopify

Migrating your existing subscriptions to Shopify enables 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/admin/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
              }
            }
          }
        ],
        line: {
          currentPrice: 29.99,
          customAttributes: [
            {
              key: "Type",
              value: "Subscription"
            }
          ],
          pricingPolicy: {
            basePrice: 29.99,
            cycleDiscounts: [
              {
                adjustmentType: FIXED_AMOUNT,
                adjustmentValue: {
                  fixedValue: 29.99
                },
                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:**

You can create and commit subscription drafts without a payment method. To create a billing attempt for a subscription contract without a payment method, the optional `paymentProcessingPolicy` field must be set to `SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER`. This creates an order without an associated payment method that can be paid using an invoice or through [manual payment](https://help.shopify.com/en/manual/payments/manual-payments) capture.

If `paymentProcessingPolicy` isn't passed or is set to `FAIL_UNLESS_VALID_PAYMENT_METHOD`, then the subscription contract must be updated to include a valid payment method before the billing attempt can be created. You can use an existing payment method that's been vaulted in Shopify for use with subscriptions or a card-on-file. Alternatively, you can direct customers to [customer accounts](https://help.shopify.com/manual/customers/customer-accounts/new-customer-accounts) 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, Shopify bills the subscription contract against its current [status](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract):

## POST https://{shop}.myshopify.com/admin/api/{api\_version}/graphql.json

## GraphQL query

```graphql
mutation {
  subscriptionBillingAttemptCreate(
    subscriptionContractId: "gid://shopify/SubscriptionContract/1",
    subscriptionBillingAttemptInput: {
      idempotencyKey: "abc123"
    }
  ) {
    subscriptionBillingAttempt {
      id
      state {
        __typename
        ... on SubscriptionBillingAttemptSuccessState {
          order {
            id
          }
        }
        ... on SubscriptionBillingAttemptFailedState {
          error {
            __typename
            ... on SubscriptionBillingAttemptPaymentError {
              code
            }
          }
        }
        ... on SubscriptionBillingAttemptActionRequiredState {
          action {
            ... on SubscriptionBillingAttemptPaymentChallenge {
              nextActionUrl
            }
          }
        }
      }
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "subscriptionBillingAttemptCreate": {
      "subscriptionBillingAttempt": {
        "id": "gid://shopify/SubscriptionBillingAttempt/593791910",
        "state": {
          "__typename": "SubscriptionBillingAttemptPendingState"
        }
      }
    }
  }
}
```

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 use the [Bulk Operations API](https://shopify.dev/docs/apps/build/apis/graphql-admin/bulk-operations/imports) to perform these operations on large numbers of contracts without incurring any API limit costs.

***