Getting started with subscriptions
A subscription is a business model that allows customers to pay a recurring price at scheduled intervals for goods or services. With subscription APIs, you can sell goods and services in multiple ways. For example, you can sell a product as a one-time purchase or as a recurring subscription.
This guide provides an overview of how subscriptions work in Shopify and explains our approach to building support for subscriptions. It also introduces the developer tools and resources that can be used to build and manage subscriptions in your app.
What you'll learnAnchor link to section titled "What you'll learn"
This guide covers the following concepts:
- Shopify's principles and approach to supporting subscriptions
- The subscription APIs
- The division of responsibilities between Shopify and apps
- How to model your app for subscriptions
- High level steps for building subscriptions in your app
- The user experience guidelines for building an optimal subscription management experience for merchants
- Developer tools and resources you can use to build and manage a subscription app
Shopify's principlesAnchor link to section titled "Shopify's principles"
The following principles have guided our approach to extending the Shopify platform to support subscriptions. They have also guided our decisions about APIs, user experience, and the division of responsibilities between Shopify and apps.
Using checkout to ensure performance, integration, and sustainabilityAnchor link to section titled "Using checkout to ensure performance, integration, and sustainability"
Checkout is where the key business rules of the commerce platform come together and determine how much will be charged, on what terms, and how. It's also the place where binding agreements are made and money is exchanged. Checkout needs to be both accurate and have the highest standards of performance and reliability at global scale.
Ensuring that subscription merchants are using Shopify’s checkout guarantees performance and integration with Shopify’s core feature set and ecosystem of apps — both today and into the future. As both Shopify and its ecosystem evolve, checkout is crucial to ensure a sustainable long-term journey for merchants.
Modeling and storing subscription data in ShopifyAnchor link to section titled "Modeling and storing subscription data in Shopify"
To maximize merchant success, Shopify needs to model and store information about how the business truly operates. This ensures that both Shopify and apps can access critical information to help merchants understand and grow their business.
The following data is foundational to how a merchant's business works:
- What subscriptions are offered
- Who the subscribers are
- What products they are subscribed to
- How customers are paying for their subscriptions
- How subscription data changes over time
Subscription data needs to be stored in Shopify to optimize the merchant’s experience. Having key business data in a single, central place is advantageous for merchants and helps reduce synchronization cost and risk across multiple systems.
Benefits of modeling and storing subscription data in ShopifyAnchor link to section titled "Benefits of modeling and storing subscription data in Shopify"
By modeling and storing subscription data, Shopify can offer merchants many benefits, including but not limited to:
- Recurring revenue reports on active subscribers, new subscribers, and churned subscribers
- Shopify Email campaigns targeted to new subscribers or churned subscribers
- Shopify Flow workflows triggered by a subscribed, churned, or new subscriber
We encourage Partners and developers to use the subscription data in Shopify to provide creative solutions for merchants.
Selling a product in multiple waysAnchor link to section titled "Selling a product in multiple ways"
Previously, Shopify treated what a product is and how it is sold as the same thing.
A shoe is priced at $10 and you can buy it now. That's it.
We're advancing merchandising by beginning to separate the “what” and “how”. A single product might be sold in multiple ways. For example, a product can be sold both as a one-time purchase as well as a subscription.
We strive to give merchants the opportunity to sell their products and grow in all the creative ways that help drive their business forward, and to give developers the tools to help enable new ways of selling that go beyond “buy now”.
Creating solutions for subscription managementAnchor link to section titled "Creating solutions for subscription management"
Subscription management is a hard problem that has many creative solutions. It's a deep and complex domain that operates quite differently across industries, physical versus digital goods, and large versus small companies.
We believe that multiple great solutions are both possible and desirable. Each solution can target a different merchant segment. Shopify’s role is to create a platform that enables these multiple solutions to emerge.
Subscription APIsAnchor link to section titled "Subscription APIs"
Shopify provides the following APIs to help you build and manage subscriptions in your app:
Selling plan APIs: An alternative way to sell a product or variant, other than "buy now".
Subscription contract APIs: The subscription agreements between a customer and merchant.
Customer payment method APIs: Stored payment methods that can be used to pay for future orders without requiring the customer to manually go through checkout.
Division of responsibilities between Shopify and appsAnchor link to section titled "Division of responsibilities between Shopify and apps"
The following table describes the division of responsibilities between Shopify and apps. The division of responsibilities allows Shopify to provide a fully-integrated subscriptions experience and allows apps to provide innovative user-facing workflows and subscription management automation.
|Models and stores subscription business data|
|Bills and processes subscription payments (both initial purchase and renewals)|
|Schedules and automates the billing of subscriptions|
|Provides a subscription management user interface|
Modeling your app for subscriptionsAnchor link to section titled "Modeling your app for subscriptions"
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 steps:
Plan setup: Allow merchants to set up and manage how they want products or variants to be sold.
Plan purchase and checkout: Display subscriptions to customers in the purchase flow.
Plan post-purchase and subscription management: Manage the current state of a subscription agreement between a merchant and a customer.
You can use the selling plan API to store plans and associate them with products or variants. Whether or not your app has an internal representation of plans, you need to save the plans in Shopify using the selling plan API.
Plan managementAnchor link to section titled "Plan management"
Your app provides the user experience (UX) to allow merchants to manage their plans. It should implement an embedded UX that allows the merchant to set up the plan directly from the product page itself using a product subscription app extension.
The plans that are associated with a given product or variant 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"
Shopify provides Liquid drops and the Product Ajax API to allow theme developers to display the plans for a given product in the purchase flow. To purchase a product on a plan, a variant ID and a selling plan ID needs to be submitted through the Cart API.
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 (where necessary) credit card vaulting and customer consent.
Your app needs to provide the customer-facing UX for purchasing a subscription by injecting code in the theme.
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"
Shopify provides a subscription contract API for managing the current state of each subscription agreement. This allows Shopify to interact with subscriptions.
Your app needs to handle the following:
User experience guidelinesAnchor link to section titled "User experience guidelines"
Apps are responsible for designing an optimal experience that allows merchants to create and manage their subscription products. To provide a good subscription management experience for merchants, keep the following user experience guidelines in mind:
Work with merchants' existing workflows: Shopify provides the tooling for apps to build subscription experiences. Subscription experiences can be accessed directly from the Shopify admin. This allows merchants to access your app from the surface areas they are familiar with.
If a resource exists in Shopify, don't duplicate it in your app: Shopify-managed resources such as customers, discounts, and products should be managed in a single place to reduce complex workflows and duplication.
RequirementsAnchor link to section titled "Requirements"
Shopify renders the product subscription app extension in the product page, which contains a set of extension modes. Apps are required to integrate with these extension modes, allowing merchants to complete their tasks or access app functionality directly from the Shopify admin.
Example product subscription app extensionAnchor link to section titled "Example product subscription app extension"
Developer tools and resourcesAnchor link to section titled "Developer tools and resources"
To help you build and manage subscriptions, Shopify offers the following developer tools and resources:
An app proxy fetches data from an app proxy server to display on a page of the online store. By using an app proxy, customers can have a seamless experience managing their subscriptions under the shop’s domain.
For more information, refer to Create a secure customer-facing subscription portal.
Storefront Liquid drops and propertiesAnchor link to section titled "Storefront Liquid drops and properties"
Liquid drops and properties allow you to integrate selling plans and subscriptions into a store's theme.
For more information, refer to Showing selling plan groups and selling plans on a product page.
App extensionsAnchor link to section titled "App extensions"
To surface your app’s subscriptions in the Shopify admin, you need to use app extensions. To get started with app extensions, refer to Getting started building a product subscription app extension.
For more information on the available extension modes, refer to Create and manage a product subscription app extension.
- 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.