This guide outlines the process of migrating a legacy subscriptions app to one that is integrated to Shopify Checkout and that merchants can access directly in the Shopify admin.

> Caution:
> Starting October 18 2024, Shopify will only support subscription apps that are integrated with Shopify checkout.

Migrating to Shopify comes with a set of UX guidelines and requirements to ensure the best possible merchant experience. For more information, refer to [UX guidelines for building migration experiences](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/ux-for-migration).

## What you'll learn

This tutorial covers the following concepts:

- [Merchant eligibility for subscriptions](#merchant-eligibility-for-subscriptions)
- [Create selling plans and selling plan groups for your subscriptions](#create-selling-plans-and-selling-plan-groups-for-your-subscriptions)
- [Create checkout discount codes](#create-checkout-discount-codes)
- [Create delivery profiles for shipping](#create-delivery-profiles-for-shipping)
- [Charging taxes](#charging-taxes)
- [Add code to the storefront](#add-code-to-the-storefront)
- [Determine customer payment methods status](#determine-customer-payment-methods-status)
- [Extract Paypal payment methods from Braintree](#extract-paypal-payment-methods-from-braintree)

## Merchant eligibility for subscriptions

To be eligible to use Shopify subscriptions, merchants need to meet the [qualifying criteria](https://help.shopify.com/en/manual/products/subscriptions/setup#eligibility-requirements). You can execute the following request using the GraphQL Admin API to determine if a shop is eligible to use the new APIs for subscriptions.

<p>
<div class="react-stacked-code-block ThemeMode-dim" data-preset="stacked">
<script data-option="title" data-value="POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json"></script>


<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="GraphQL request"></script>

<script type="text/plain" data-language="graphql">
RAW_MD_CONTENT{
 shop {
   features {
     eligibleForSubscriptions
   }
 }
}
END_RAW_MD_CONTENT</script>

</div>
</p>

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="JSON response"></script>

<script type="text/plain" data-language="json">
RAW_MD_CONTENT{
   "data": {
       "shop": {
           "features": {
               "eligibleForSubscriptionMigration": true
           }
       }
   }
}
END_RAW_MD_CONTENT</script>

</div>
</p>


</div>
</p>


## Create selling plans and selling plan groups for your subscriptions

To create selling plans for your products, you can use the [`SellingPlan`](/docs/api/admin-graphql/latest/objects/sellingplan) object. Selling plans can then be grouped into a [`SellingPlanGroup`](/docs/api/admin-graphql/latest/objects/sellingplangroup) object that's associated with specific products.

For more information, refer to [Selling plans](/docs/apps/build/purchase-options/subscriptions/selling-plans).

> Note:
> Subscriptions that include bundles of different products aren't supported.

## Create checkout discount codes

If your checkout currently uses discount codes, then those discount codes need to be created on Shopify. To programmatically add these discount codes to the store, you can use the [`PriceRule`](/docs/api/admin-graphql/latest/objects/pricerule) and [`PriceRuleDiscountCode`](/docs/api/admin-graphql/latest/objects/pricerulediscountcode) objects.

For more information, refer to [Subscription discounts](/docs/apps/build/purchase-options/subscriptions/contracts#subscription-discounts).

> Note:
> Free shipping discount codes on Shopify need to have a max limit added. If you're migrating existing discount codes, then you need to ask the merchant what value they want to use for this maximum limit.

## Create delivery profiles for shipping

To set up delivery methods on the store, you can use the [`DeliveryProfile`](/docs/api/admin-graphql/latest/objects/deliveryprofile) object. A delivery profile stores information about what delivery methods and rates apply to specific products. If the store's products are physical items that need to be shipped, then delivery profiles let you show these shipping methods at checkout.

If your app has defined subscription-specific delivery settings, then these delivery settings need to be added to Shopify using the `DeliveryProfile` object to continue being available at checkout.

For specific instructions on setting up delivery profiles and associating them with products, refer to [Manage delivery profiles](/docs/apps/build/purchase-options/deferred/delivery-and-deferment/build-delivery-profiles).

## Charging taxes

If your app enables merchants to create custom taxation rules for their subscription products, then these tax rules need to be created in the Shopify admin to continue to be applicable.

To learn more about creating tax rules on Shopify, refer to the merchant documentation about [Taxes](https://help.shopify.com/manual/taxes).

## Add code to the storefront

Customers need to be able to purchase products as a subscription from the online store. To make subscription products available from the online store, you need to enable customers to select selling plan from the online store product pages.

The Shopify storefront needs to allow selecting a selling plan, and the "add to cart" button needs to include the selling plan ID when it adds the product to the cart to create subscription orders. The selling plan details, including the ID, selling plan group, pricing, and options, are all available through the [Liquid reference](/docs/api/liquid). These selling plan details can be included in a call to the [POST `/cart/add.js`](/docs/api/ajax/reference/cart) Ajax API.

For more information, refer to [Showing selling plan groups and selling plans on a product page](/docs/storefronts/themes/pricing-payments/subscriptions/add-subscriptions-to-your-theme).

For information on the UX guidelines and requirements around presenting selling plans to customers, refer to Online store [Subscription UX guidelines](/docs/storefronts/themes/pricing-payments/subscriptions/subscription-ux-guidelines) and the [Pre-orders and try before you buy UX guidelines](/docs/storefronts/themes/pricing-payments/preorder-tbyb/preorder-tbyb-ux-guidelines).

> Note:
> Some themes provide default support for subscriptions, making code injection redundant. Theme injections should be optional for the merchant to prevent displaying duplicate subscriptions.

## Determine customer payment methods status

We process the payment methods with background jobs to improve processing time. Therefore, the initial response of a mutation to create a payment method might return a `bogus` payment method. Use the following steps to keep track of the payment method status during migration:

1. Subscribe to customer payment methods webhooks to get updates as each payment method is imported.
  - [`CUSTOMER_PAYMENT_METHODS_CREATE`](/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-customerpaymentmethodscreate)
  - [`CUSTOMER_PAYMENT_METHODS_UPDATE`](/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-customerpaymentmethodsupdate)
  - [`CUSTOMER_PAYMENT_METHODS_REVOKE`](/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic#value-customerpaymentmethodsrevoke)
2. Execute GraphQL queries to create customer payment methods. The specific GraphQL queries depend on the payment gateway that you're migrating from.
3. Listen for webhooks to determine whether the payment methods have been imported successfully.

> Note
> To subscribe to a webhook event, refer to [Webhooks](/docs/apps/build/webhooks/subscribe/https).

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/api/subscriptions/customer-payment-method-create-flow-7988c989d607b57f181d56c6e3fc09010092f7de4c771e25256fd1555aaf8a50.png" class="lazyload" alt="A flowchart illustrating the general workflow for creating new payment methods. The flow begins with a subscription to customer payment methods webhooks and making a request to the create payment method endpoint. If the payment method is not created, then a failure response is handled. If the payment method is created, then Shopify processes the customer_payment_methods/create webhook. If successful, then Shopify processes the customer_payment_methods/update webhook. If unsuccessful, then Shopify processes the customer_payment_methods/revoke webhook" width="75%" height="1388"></figure>

## Extract Paypal payment methods from Braintree

We don't support migrating PayPal payment methods from Braintree. However, we support PayPal Express as a subscription gateway. Before [creating new Paypal Express payment methods](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information#step-2-import-payment-methods-for-customers), you need to extract the PayPal payment methods information from the Braintree customers.

Braintree enables you to [export](https://developer.paypal.com/braintree/articles/get-started/data-migration/exports) the list of customers and credit card payment methods to a CSV file. However, the export doesn't give you the list of PayPal payment methods.

You need to extract the list of PayPal payment methods using the [Braintree SDK](https://developer.paypal.com/braintree/docs/start/overview). To extract Paypal payment methods, query for the customer information using the [Customers resource](https://developer.paypal.com/braintree/docs/guides/customers/ruby) to get their payment methods list.

> Tip
> You can obtain the `merchant_id`, `public_key`, and `private_key` in your [Braintree dashboard](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials#api-keys).

The following is a minimal Ruby code snippet to extract a PayPal payment method from a customer. While this method isn't scalable if you have a large number of customers, it's a good starting point to build on.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>


<script type="text/plain" data-language="ruby">
RAW_MD_CONTENTrequire "rubygems"
require "braintree"

gateway = Braintree::Gateway.new(
  :environment => :sandbox,
  :merchant_id => "merchant_id",
  :public_key => "public_key",
  :private_key => "private_key",
)

customer = gateway.customer.find('customer_id')
paypal_payment_method = customer.payment_methods.find { |pm| pm.is_a?(Braintree::PayPalAccount) }

puts "customer_id: #{customer.id}, billing_agreement_id: #{paypal_payment_method.billing_agreement_id}"
END_RAW_MD_CONTENT</script>

</div>
</p>


## Next steps

- Learn how to [migrate existing customer information to Shopify](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-customer-information).
- Learn how to [migrate existing subscription contracts to Shopify](/docs/apps/build/purchase-options/subscriptions/migrate-to-subscriptions-api/migrate-subscription-contracts).