All Tutorials

Subscriptions API migration guide

All Tutorials

Subscriptions API migration guide

Subscriptions API migration guide

In October 2020, Shopify released APIs for subscriptions, which allows apps to facilitate subscription-based products for merchants. For an overview of subscriptions on Shopify, refer to Shopify subscriptions overview.

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 Online store UX requirements for subscriptions.

What you'll learn

This tutorial covers the following concepts:

Merchant eligibility for subscriptions

To be eligible to use Shopify subscriptions, merchants must meet the following set of qualifying criteria:

  1. The merchant must use Shopify Payments. The improved subscription experience is available only through Shopify Payments.
  2. If the merchant is on the Plus plan, then the plan must not be locked to a specific version of Shopify Checkout.

The following query determines if a shop is eligible to use the new APIs for subscriptions:

 shop {
   features {

View response

JSON response:

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

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 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 buyers, refer to Online store UX guidelines for subscriptions.

Next steps