Subscriptions API migration guide

This tutorial covers the following concepts:

• Merchant eligibility for subscriptions
• Create selling plans and selling plan groups for your subscriptions
• Create checkout discount codes
• Create delivery profiles for shipping
• Charging taxes
• Add code to the storefront
• Determine customer payment methods status
• Extract Paypal payment methods from Braintree

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.

To create selling plans for your products, you can use the SellingPlan object. Selling plans can then be grouped into a SellingPlanGroup object that's associated with specific products.

For more information, refer to Selling plans.

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 and PriceRuleDiscountCode objects.

For more information, refer to Subscription discounts.

To set up delivery methods on the store, you can use the 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.

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.

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. 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 Subscription UX guidelines and the Pre-orders and try before you buy UX guidelines.

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
   • CUSTOMER_PAYMENT_METHODS_UPDATE
   • CUSTOMER_PAYMENT_METHODS_REVOKE
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.

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, you need to extract the PayPal payment methods information from the Braintree customers.

Braintree enables you to export 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. To extract Paypal payment methods, query for the customer information using the Customers resource to get their payment methods list.

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.

• Learn how to migrate existing customer information to Shopify.
• Learn how to migrate existing subscription contracts to Shopify.