A subscription is a business model that enables customers to pay a recurring price at scheduled intervals for goods or services. For example, customers can buy a product as a recurring subscription. Learn more about purchase option types.
Subscription apps enable developers and merchants to build subscription experiences directly into Shopify's checkout. This guide describes what a subscription is, subscription APIs, migration to subscription APIs, and limitations for subscription apps.
How do subscriptions work?Anchor link to section titled "How do subscriptions work?"
Subscriptions include policy configurations and subscription contracts.
Policy configurationsAnchor link to section titled "Policy configurations"
You can create purchase options using the
A subscription includes delivery, pricing, and billing policies. This enables you to build more flexible and extensible apps that support various ways to sell and buy products.
Delivery policyAnchor link to section titled "Delivery policy"
deliveryPolicy field defines when the order should be fulfilled, from the time that the order is created to the time that it leaves the merchant's possession. Merchants can specify the delivery interval (
interval) and the interval count (
Pricing policiesAnchor link to section titled "Pricing policies"
pricingPolicies field defines pricing changes on a given product variant, including any shipping costs, taxes, duties, or discounts. Pricing policies enable merchants to adjust prices on subscription orders by setting
adjustmentValue. Pricing policies work in conjunction with price lists.
Pricing policies include the following types:
fixedpricing policy: A single pricing policy. For example, all billing cycles can have a flat 15% discount. An initial pricing policy is applied until a defined recurring policy kicks in.
recurringpricing policy: A follow-up pricing policy that applies if the initial pricing policy expires. For example, the first billing cycle has a 20% discount, and the subsequent recurring cycles have a 15% discount.
Billing policyAnchor link to section titled "Billing policy"
billingPolicy field defines the intervals of time between the placement of an order, its fulfillment, and payment collection. Merchants can specify the billing interval (
interval) and the interval count (
Subscription contractsAnchor link to section titled "Subscription contracts"
A subscription contract is the agreement between a customer and a merchant over a specific term for recurring purchases over a set or undefined period of time. Learn more about subscription contracts.
Purchase option categoryAnchor link to section titled "Purchase option category"
category field represents the purchase option category that's used to filter orders by purchase option on the order page. The
category field supports the following approved categories:
If you want to offer a purchase option that isn't listed above, then set the
category field to
OTHER for further review by our app team.
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: Create and manage various ways to sell and buy products.
Subscription contract APIs: Create and manage subscription agreements between a customer and merchant.
Customer payment method APIs: Store payment methods that can be used to pay for future orders without requiring the customer to manually go through checkout.
Migrating to use Subscription APIsAnchor link to section titled "Migrating to use Subscription APIs"
If you already have a subscription app and need to migrate to use Subscription APIs, then refer to the Subscription API migration guide.
If your existing subscription app uses Stripe to process subscription payments, then you can import pay-as-you-go contracts directly into Shopify without the need to migrate credit cards. For more information, refer to Migrating existing subscription contracts to Shopify.
LimitationsAnchor link to section titled "Limitations"
The following are known limitations for all purchase options:
- Customers can't use accelerated checkouts or local payment methods for purchase options.
- Purchase options don't support local delivery or local pickup options.
- Merchants can't use purchase options through Shopify POS.
- Merchants can't use purchase options on draft orders.
- Purchase options don't support "Buy X get Y" discounts.
SellingPlandoesn't support translations for multi-language storefronts.
The following are known limitations for subscriptions:
- Customers can only use Shop Pay on some stores.
- To use subscriptions, merchants need to use the following payment gateways:
- Scripts that discount subscription price or shipping rates apply to the first payment only.
- Gift cards used to pay for subscriptions only apply to the first payment.
- The Order Edits API doesn't support subscriptions.
- Apple Pay support for subscriptions is only available in the United States, Canada, Australia, and New Zealand for Visa and Mastercard.
Product roadmapAnchor link to section titled "Product roadmap"
Some subscription features are in development and will be released later this year. Below you’ll find the features on our roadmap and our estimated launch dates. These dates might change but represent our current best estimates.
|Feature||Target launch date|
|(Plus) Checkout.liquid support||Launched Feb 2021|
|(Plus) Script Editor app for Shopify Scripts support
Note: A new Shopify Scripts experience is currently available in beta.
|Launched Feb 2021|
|Paying for subscriptions with a gift card||Launched Feb 2021|
|Improvements to shipping calculation for carts containing subscriptions and one-time purchases||Launched April 2021|
|Additional gateways: PayPal Express||Launched May 2021|
|Additional gateways: Authorize.net||Launched June 2021|
|Storefront API||Launched July 2021|
|Wallets support: Shop Pay||Launched October 2021|
|Additional gateways: Stripe||Launched January 2022|
|Wallets support: Apple Pay||Launched February 2022|
|Wallets support: G Pay||Launched April 2022|
|Local pickup||H2 2022|
|Local delivery||H2 2022|
|Shopify POS||H2 2022|
Frequently asked questionsAnchor link to section titled "Frequently asked questions"
What should I do if I have merchants dependent on features in my legacy subscription app that are currently unresolved limitations of the new APIs?Anchor link to section titled "What should I do if I have merchants dependent on features in my legacy subscription app that are currently unresolved limitations of the new APIs?"
Any existing installs can continue to use your app at this time. All new installs, apps, and opportunities should use the new Subscription APIs. We'll continue to release more features and support for subscriptions over the coming months, as outlined above and going forward.
Where can I learn more about subscriptions?Anchor link to section titled "Where can I learn more about subscriptions?"
For more information on subscriptions, refer to our Partner Blog post, where we give some background information on why we built this feature.
We are always looking for feedback on our APIs. If you have any specific questions, concerns, or feedback on the Subscription APIs, then visit our Subscriptions API forums.
- Learn about modeling subscription apps