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.
Requirements
Anchor link to section titled "Requirements"This tutorial assumes that you've already completed the Subscriptions API migration guide.
What you'll learn
Anchor link to section titled "What 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
Step 1: Configure your payment gateway to work with subscriptions
Anchor link to section titled "Step 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.
Migrating from Stripe
Anchor link to section titled "Migrating 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.
To connect a merchant's current Stripe account to Shopify as a secondary gateway, redirect the merchant to the following URL:
We recommend that you open 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.
Migrating from Braintree
Anchor link to section titled "Migrating 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:
We recommend that you open 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.
While Stripe allows you to toggle test mode in your Stripe dashboard, Braintree has a separate sandbox account for test mode.
To connect to a Sandbox Braintree account, use the following URL:
Migrating from Authorize.net
Anchor link to section titled "Migrating 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:
We recommend that you open 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.
Checking if your payment gateway is configured for subscriptions
Anchor link to section titled "Checking 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:
Request: POST /admin/api/2023-07/graphql.json
View response
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:
Request: POST /admin/api/2023-07/graphql.json
View response
JSON response:
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.
If you use the Authorize.net payment gateway, then you don't need to do any additional configuration.
Determine eligibility to use subscriptions with Shopify
Anchor link to section titled "Determine 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.
Request: POST /admin/api/2023-07/graphql.json
View response
JSON response:
Step 2: Import any missing customers
Anchor link to section titled "Step 2: Import any missing customers"You need to import the customer records to connect them to payment methods and subscription contracts. You can use the customerCreate and customerUpdate mutations to add customers to Shopify.
Step 3: Create new payment methods for customers
Anchor link to section titled "Step 3: Create new payment methods for customers"You can associate Stripe payment methods 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:
Request: POST /admin/api/2023-07/graphql.json
Example input:
View response
JSON response:
You can associate Braintree payment methods 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:
Request: POST /admin/api/2023-07/graphql.json
Example input:
View response
JSON response:
You can associate PayPal billing agreements with the customers that you import into Shopify. Use the CustomerPaymentMethodPaypalBillingAgreementCreate mutation to associate the Shopify customer ID with the PayPal billing agreement ID.
The following example shows a mutation that creates a payment method for a customer:
Request: POST /admin/api/2023-07/graphql.json
You can associate Authorize.net customer profiles with the customers that you import into Shopify. To make the association, use the CustomerPaymentMethodRemoteCreate mutation to associate the Shopify customer ID with the Authorize.net customer profile ID and payment method ID. If the Authorize.net payment method ID isn't available, then the customer's default source is used.
The following example mutation creates a payment method for a customer:
Request: POST /admin/api/2023-07/graphql.json
Example input:
Bulk import customers and payment methods
Anchor link to section titled "Bulk 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.
- Learn how to migrate existing subscription contracts to Shopify.