Modeling subscription apps
This guide provides an overview of how subscriptions work in Shopify and explains our approach to building support for subscriptions.
Lifecycle of a subscription appAnchor link to section titled "Lifecycle of a subscription app"
The following diagram illustrates the lifecycle of a subscription based on the actions of the merchant, customer, Shopify, and your app:
- Merchants create and manage how they want to sell their products.
- Customers purchase subscriptions and update their subscriptions (such as changing their payment method).
- When a customer purchases a subscription, Shopify first creates a transaction and then an order. After the transaction and order are created, Shopify generates a subscription contract and creates a billing attempt on the initial purchase.
- Subsequent customer orders are automated by the app. The app creates a billing attempt based on the existing subscription contract using the API. When the app creates a billing attempt, a transaction and an order are created.
- Your app receives webhooks when subscription-related events occur, handles billing failures and scheduling, and provides a subscription management user interface for both customers and merchants.
Building subscriptions in your appAnchor link to section titled "Building subscriptions in your app"
Building subscriptions in your app involves the following tasks:
Set up and manage purchase options for products or variants.
Anchor link to section titled "SellingPlanGroup and SellingPlan"
You can use the
SellingPlan objects to store purchase options and associate them with products or variants. Regardless of whether your app has an internal representation of purchase options, you need to save the purchase options in Shopify using the
Learn more about GraphQL Admin API objects for purchase options.
Using app extensionsAnchor link to section titled "Using app extensions"
Your app provides the user experience to merchants to manage their purchase options. The app should implement an embedded UX that enables the merchant to set up purchase options directly from the product page, using an app extension.
If there aren't any app extensions to modify purchase options that are associated with a given product or variant, then the purchase options are listed in a read-only state on the product page in the Shopify admin.
Plan purchase and checkoutAnchor link to section titled "Plan purchase and checkout"
Display purchase options to customers in the purchase flow.
Liquid drops and the Ajax APIAnchor link to section titled "Liquid drops and the Ajax API"
Shopify provides Liquid drops and the Ajax API to enable theme developers to display the purchase options for a given product in the purchase flow.
To purchase a product with a purchase option, a variant ID and a
SellingPlan ID need to be submitted through the Cart API.
To learn more about how to implement purchase options in a theme, refer to Purchase options.
Checkout and customer-facing UXAnchor link to section titled "Checkout and customer-facing UX"
Checkout handles carts containing line items that have plans associated with them. It also handles pricing, messaging, and payment method vaulting and customer consent, which the merchant should customize to their needs.
Subscription contractsAnchor link to section titled "Subscription contracts"
When a customer successfully purchases a subscription and completes the checkout, Shopify generates a subscription contract.
The subscription contract describes the agreement between merchant and customer. The agreement includes key information, like the variant, plan, payment method to be used for subsequent billing, and the billing and shipping addresses.
To learn more about subscription contracts, refer to Create and manage subscription contracts.
Plan post-purchase and subscription managementAnchor link to section titled "Plan post-purchase and subscription management"
Manage the current state of a subscription agreement between a merchant and a customer.
Shopify provides a subscription contract API for managing the current state of each subscription agreement.
Your app needs to handle the following tasks:
Prohibited actionsAnchor link to section titled "Prohibited actions"
The following are prohibited actions for all purchase options:
- Vaulting payment methods: Don't vault payment methods for any purpose other than processing recurring or deferred payments.
- Overbilling: A purchase option specifies how to bill a customer. Don't overbill a customer.
- Unsupported usage: APIs are built to support only authorized purchase options, such as pre-orders, try before you buys, and subscriptions. Don't use the APIs to solve for other business use cases, such as installments, layaways, and crowdfunding campaigns.
The following are prohibited actions for subscriptions:
- Updating contracts inappropriately: Subscription contracts only need to be updated to reflect what the customer has agreed to.
- Unclear contracts: The customer needs to understand what they're agreeing to. The storefront needs to clearly state the conditions of the contract.
- Stale contracts: Don't let contracts become stale in Shopify. As soon as a customer agrees to a contract change, the updates need to be reflected in Shopify. This helps to ensure that merchants are never locked into a particular subscription provider.
Division of responsibilities between Shopify and appsAnchor link to section titled "Division of responsibilities between Shopify and apps"
The division of responsibilities enables Shopify to provide a fully-integrated purchase option experience and enables apps to provide innovative user-facing workflows and purchase option management automation.
The following table describes the division of responsibilities between Shopify and subscription apps.
|Modeling and storing purchase option business data||✔|
|Billing and processing purchase payments (both initial purchase and renewals)||✔|
|Labeling the purchase option as a subscription||✔|
|Scheduling and automating payments, authorizing capture through the Shopify APIs and handles billing failures||✔|
|Providing customer & merchant UX for managing purchase options, both pre-purchase and post-purchase||✔|
- Create and manage selling plans: Follow a step-by-step workflow to create and manage selling plans in your subscription app.
- Create and manage subscription contracts: Follow a step-by-step workflow to create and manage subscription contracts, and get familiar with how billing and webhooks for subscriptions work.