Skip to main content

Migrate customer information to Shopify

Shopify has built a set of tools to import pay-as-you-go contracts into Shopify without the need to migrate credit cards directly.

In this tutorial, you'll learn how to migrate customer information from the following payment gateways to Shopify:

  • Stripe
  • Braintree
  • PayPal Express
  • Authorize.net

Stripe or Braintree will connect as a legacy subscription payment gateway for billing your existing contracts, while all new or updated contracts charge against Shopify Payments. Authorize.net can be setup the same way if you wish to use Shopify Payments after the migration.

Other payment gateways will remain the same after the migration.

Warning

We strongly recommend that you pause any billing in your current application while migrating customer payment methods and contracts. Pausing billing will help you avoid double-billing a contract.

Anchor to RequirementsRequirements

This tutorial assumes that you've already completed the Subscriptions API migration guide.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

  • Configure your payment gateway to work with subscriptions
  • Import any missing customers
  • Create new payment methods for customers

Anchor to Step 1: Configure your payment gateway to work with subscriptionsStep 1: Configure your payment gateway to work with subscriptions

The steps for configuring your payment gateway to work with subscriptions depend on the payment gateway that you're using.

Anchor to Migrate from StripeMigrate from Stripe

Note

Shopify only supports the migration of credit card payment methods from Stripe.

If your primary payment gateway is Shopify Payments and you're migrating from Stripe, then you need to use Stripe's Payment Intents API to connect Stripe as a secondary payment gateway. The process is also compatible with Stripe's Charges API.

Caution

Customized charge flows, including specialized payment flags, aren't supported and might result in an elevated rate of authorization failures.

To connect a merchant's current Stripe account to Shopify as a secondary gateway, redirect the merchant to the following URL:

https://admin.shopify.com/store/{shop}/payments/legacy_subscription

We recommend that you open the redirect URL in a new browser window so that merchants can return to your migration page when they complete the process.

Merchants are redirected to Stripe and asked to initiate the connection process. After merchants successfully initiate the connection process, they're redirected back to the payment settings page and a banner notifies them of a successful connection.

Anchor to Migrate from BraintreeMigrate from Braintree

If you're migrating from Braintree, and you sell internationally, then you need to consider that Braintree's legacy payment gateway integration doesn't support multi-currency subscription contracts.

If your primary payment gateway is Shopify Payments and you're migrating from Braintree, then you need to use Braintree's OAuth to connect Braintree as a secondary payment gateway.

To connect a merchant's current Braintree account to Shopify as a secondary gateway, redirect the merchant to the following URL:

https://admin.shopify.com/store/{shop}/payments/legacy_subscription_braintree

We recommend that you open the redirect URL in a new browser window so that merchants can return to your migration page when they complete the process.

Merchants are redirected to Braintree and asked to initiate the connection process. After merchants successfully initiate the connection process, they're redirected back to the payment settings page and a banner notifies them of a successful connection.

Braintree uses a separate sandbox account for test mode. To connect to a Sandbox Braintree account, use the following URL:

https://admin.shopify.com/store/{shop}/payments/legacy_subscription_braintree?sandbox=true

Anchor to Migrate from Authorize.netMigrate from Authorize.net

If your primary payment gateway is Shopify Payments and you're migrating from Authorize.net, then you need to use Authorize.net's API Login ID and Transaction Key to connect Authorize.net as a secondary payment gateway.

To connect a merchant's current Authorize.net account to Shopify as a secondary gateway, redirect the merchant to the following URL:

https://admin.shopify.com/store/{shop}/settings/payments/legacy_subscription_authorize_net

We recommend that you open the redirect URL in a new browser window so that merchants can return to your migration page when they complete the process.

Merchants are redirected to Shopify and asked to enter their credentials for Authorize.net. After merchants successfully enter their credentials, they're redirected back to the payment settings page and a banner notifies them of a successful connection.

Anchor to Checking if your payment gateway is configured for subscriptionsChecking if your payment gateway is configured for subscriptions

Poll the shop setting to determine whether Shopify has successfully established a connection with Stripe, Braintree, or Authorize.net:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
shop {
features {
legacySubscriptionGatewayEnabled
}
}
}

JSON response

{
"data": {
"shop": {
"features": {
"legacySubscriptionGatewayEnabled": true
}
}
}
}

Anchor to Migrate from PayPal ExpressMigrate from PayPal Express

If you use the PayPal Express payment gateway, then you need to verify that PayPal Express is enabled and the merchant is approved to use reference transactions from PayPal.

Poll the shop setting to determine whether Shopify has successfully verified that the PayPal account is ready to be used for subscriptions:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
shop {
features {
paypalExpressSubscriptionGatewayStatus
}
}
}

JSON response

{
"data": {
"shop": {
"features": {
"paypalExpressSubscriptionGatewayStatus": "ENABLED"
}
}
}
}

If the field value is DISABLED, then the merchant must contact PayPal to be approved for reference transactions. The Payments settings page will display a banner to the merchant with instructions. A value of PENDING means that Shopify is still determining the merchant's eligibility.

Anchor to Determine eligibility to use subscriptions with ShopifyDetermine eligibility to use subscriptions with Shopify

The following query verifies that at least one payment gateway allows customers to purchase subscriptions. For stores on a Shopify Plus plan, the query verifies that checkout can display subscription information.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
shop {
features {
eligibleForSubscriptionMigration
}
}
}

JSON response

{
"data": {
"shop": {
"features": {
"eligibleForSubscriptionMigration": true
}
}
}
}

Anchor to Step 2: Import payment methods for customersStep 2: Import payment methods for customers

Tip

Follow the Determine customer payment methods status tutorial to know when Shopify successfully processes a payment method.

You can associate Stripe credit cards with the customers that you import into Shopify by using the CustomerPaymentMethodRemoteCreate mutation.

The following example uses a mutation to create a payment method for a customer:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

mutation CreateRemoteCreditCard(
$customerId: ID!,
$remoteReference: CustomerPaymentMethodRemoteInput!) {
customerPaymentMethodRemoteCreate(
customerId: $customerId,
remoteReference: $remoteReference
) {
customerPaymentMethod {
id
instrument {
... on CustomerCreditCard {
brand
lastDigits
}
}
}
}
}

Example input

{
"customerId": "gid://shopify/Customer/1",
"remoteReference": {
"stripePaymentMethod": {
"customerId": "cus_stripe",
"paymentMethodId": ""
}
}
}

JSON response

{
"data": {
"customerPaymentMethodRemoteCreate": {
"customerPaymentMethod": {
"id": "gid://shopify/CustomerPaymentMethod/5ccb49cf4f4a4a0c75e4351066b761cb",
"instrument": {
"brand": "bogus",
"lastDigits": ""
}
}
}
},
"extensions": {
"cost": {
"requestedQueryCost": 11,
"actualQueryCost": 11
}
}
}
Note

If the Stripe payment method ID isn't available, then Shopify will use the default payment method of the customer.

Note

If you have any missing customers, then you can use the customerCreate and customerUpdate mutations to add customers to Shopify. Customer records must include the email address, first name, and last name fields. Shopify uses this data to send automated email messages to customers, such as subscription contracts updates.

I cannot continue without seeing the MDX content that needs to be fixed. Please provide the MDX content you would like me to analyze and correct according to the rules specified. I will then return only the corrected MDX content without any explanations.

Anchor to Bulk import customers and payment methodsBulk import customers and payment methods

You can use bulk operations to import large volumes of customers and payment methods without incurring any API limit costs.

Note

If the solutions suggested on this page don't adequately resolve your situation, then contact our support team.

Anchor to Next stepsNext steps

Was this page helpful?