Subscription apps

Subscriptions include policy configurations and subscription contracts.

You can create purchase options using the sellingPlanGroupCreate mutation.

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.

The 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 (intervalCount).

The 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 adjustmentType and adjustmentValue. Pricing policies work in conjunction with price lists.

Pricing policies include the following types:

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

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

The 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 (intervalCount).

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.

The 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:

• SUBSCRIPTION
• PRE_ORDER
• TRY_BEFORE_YOU_BUY

If you want to offer a purchase option that isn't listed above, then set the category field to OTHER, and fill out our request form, where we'll review your request for a new purchase option.

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.

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.

The following are known limitations for all purchase options:

• Customers can't use local payment methods for purchase 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.

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:
  • Shopify Payments
  • Stripe
  • PayPal Express
  • Authorize.net
• Subscriptions might not support local delivery or local pickup options for some Plus merchants with custom checkouts.
• 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.
• Subscription APIs don't support duties when subscription orders are created. Duties are available on the customer's first order that creates a subscription because the order goes through checkout. However, when subscription apps subsequently bill customers and create orders using the API, duties won't work.

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.

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.

revision_id is a version identifier that you can use to determine whether your subscription contract record is up to date. Keep a copy of the last revision_id that you received with your contract record, and compare it to the one included in the event payload. If the revision_id of the subscription contract in your record is greater than the revision_id received in the new webhook payload, then your contract is up to date. For example, if a webhook payload for the SubscriptionContractCreate mutation returned a revision_idof 1000, and the subsequent webhook payload for the SubscriptionContractUpdate mutation returns a revision_id of 1050, then the update mutation occurred after the create mutation. New revision_id values are incremental but not continuous. For example, a revision_id of 50 followed by a revision_id of 70 doesn't indicate that there are 20 versions of your contract between the first and second IDs. It should be used as a comparison to determine if the contract on your record is up to date.

Example Response is in the SubscriptionContract section.

• Learn about modeling subscription apps