Subscriptions API migration guide

This guide outlines the process of migrating an existing subscription system to one that merchants can access directly in the Shopify admin.

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.

What you'll learn

This tutorial covers the following concepts:

Merchant eligibility for subscriptions

To be eligible to use Shopify subscriptions, merchants need to meet the qualifying criteria. 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.


POST /admin/api/2021-01/graphql.json

View response

JSON response:

Create selling plans and selling plan groups for your subscriptions

To create selling plans for your products, you can use the selling plans. Selling plans can then be grouped into selling plan groups that are associated with specific products.

For more information, refer to Create and manage selling plans.

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 price rules and discount codes objects.

For more information, refer to Create and manage discounts on subscriptions.

Create delivery profiles for shipping

To set up delivery methods on the store, you can use delivery profiles. 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](/api/admin/graphql/reference/shipping-and-fulfillment/deliveryprofile object to continue being available at checkout.

For specific instructions on setting up delivery profiles and associating them with products, refer to Manage advanced shipping information with delivery profiles.

Charging taxes

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

To learn more about creating tax rules on Shopify, refer to the merchant documentation about 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 purchase options 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. These selling plan details can be included in a call to the POST /cart/add.js AJAX API.

For more information, refer to Showing selling plan groups and selling plans on a product page.

For information on the UX guidelines and requirements around presenting selling plans to customers, refer to Online store UX guidelines for subscriptions.

Next steps