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 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
• Prohibited actions associated with using the subscription APIs

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 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 must 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 Shopify

To maximize merchant success, Shopify must 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 must 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 Shopify

By modeling and storing subscription data, Shopify is able to offer merchants many benefits, including but not limited to:

• Recurring revenue reports on active subscribers, new subscribers, churned subscribers
• Shopify Email campaigns targeted to new subscribers or churned subscribers
• Shopify Flow workflows triggered by a subscribed churned or a new subscriber

We encourage partners and developers to use the subscription data in Shopify and go beyond the above examples to provide creative solutions for merchants.

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 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 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 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.

Responsibility	Shopify	App
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 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 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.

Plan setup

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 must save the plans in Shopify using the selling plan API.

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 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 must be submitted through the Cart API.

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 must provide the customer-facing UX for purchasing a subscription by injecting code in the theme.

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 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 must handle the following:

• Update contracts as necessary to reflect the true current state of the contract.
• Provide the customer-facing and merchant-facing UX for managing subscriptions, such as upgrades/downgrades, pausing, canceling, and changing products.
• Provide the automation for billing and renewing subscriptions.

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.

Requirement

Apps are required to build a product subscription app extension using Argo to allow merchants to create and manage subscription plans.

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.

Apps can also include contextual links to active subscriptions in the Customers and Order detail pages.

Example product subscription app extension

Developer tools and resources

To help you build and manage subscriptions, Shopify offers the following developer tools and resources:

App proxy

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 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 extensions

To surface your app’s subscriptions in the Shopify admin, you must 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.

Prohibited actions

This section specifies the prohibited actions associated with using the selling plan and subscription contract APIs. The list is not exhaustive and might be updated at any time:

• Overbilling: Billing against a customer's card can only be done as specified by the contract. Don't overbill against any card.
• Updating contracts inappropriately: Subscription contracts must only be updated to reflect what the customer has agreed to.
• Unclear contracts: It must be clear to the customer what they're agreeing to. The storefront must 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 must be reflected in Shopify. This helps to ensure that merchants are never locked into a particular subscription provider.
• Selling plans without subscription contracts: Don't create selling plans as a means to only have additional pricing control without handling the resulting subscription contracts.
• Unsupported usage: The APIs are built to support subscriptions. Don't use the APIs to solve for other business use cases like instalments, layaways, or pre-orders.

Any failure to abide by these prohibitions constitutes a breach of Shopify’s API Terms. We might update these prohibitions from time to time, so please check back for any changes that might impact you.

Next steps

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