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.
A subscription contract is the result of purchasing a selling plan that has recurring policies. After a customer purchases a subscription product or variant at checkout, Shopify generates a subscription contract and shares the contract with your app using a webhook.
Subscription contracts generate new orders for merchants to fulfill at subscription renewal time. They're also the mechanism by which apps bill customers for their subscriptions.
Requirements
Anchor link to section titled "Requirements"- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
read_own_subscription_contractsandwrite_own_subscription_contractsaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth. You've created products and product variants in your development store.
You've completed the Create and manage selling plans guide.
Subscription contract object relationships
Anchor link to section titled "Subscription contract object relationships"The following diagram shows the relationship between subscription contracts, orders, contract drafts, and billing attempts.
| API object | Description |
|---|---|
| Subscription contract | Represents the agreement for a set of items delivered to a customer, on a specific billing and delivery schedule and at a specific price.
A subscription contract is different from an order. An order is a customer's completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process, during which time they provide an email address or phone number, billing address, and payment information. Subscription contracts might not be immediately available when an order is created. It's best to rely on subscription contract webhooks to be notified when contracts are created. |
| Contract lines | Represents the price and quantity of items in a subscription contract. |
| Pricing policy | Represents the future intent to change the price after a given number of billing cycles. When the customer completes a checkout, Shopify creates a contract, and the app developer is notified of which policies the customer chose. |
| Subscription order line | Links a subscription contract to its related order line items, and optionally, to the billing attempt that created this order line. A subscription order line is created when one of the following events occurs:
|
| Subscription draft | Represents the intent to change a subscription. If a customer wants to change their subscription, then the app needs to create a subscription draft and commit the change to make the changes active. |
| Draft change | Represents a change made to a subscription draft, such as changing a contract line. |
| Billing attempt | Represents an attempt at executing a billing cycle and charging the customer payment method for a subscription contract. |
Subscription discounts
Anchor link to section titled "Subscription discounts"You can apply different discount types on subscriptions, including percentage, fixed amount, and free shipping discounts.
Discount types
Anchor link to section titled "Discount types"There are two ways that you can apply discounts on subscriptions:
- Manual custom discounts: Defined on the subscription.
- Shopify code discounts: Defined on a shop and applied to a subscription.
For both manual custom discounts and Shopify code discounts, you can apply the following discount types:
- Percentage discount: A percentage amount deducted from the original product price. For example, 10% off.
- Fixed amount discount: A specific amount deducted from the original product price. For example, 10 CAD off.
- Free shipping discount: An offer that deducts shipping costs from the original product price. For example, free shipping on a subscription purchase.
You can define whether the discount applies to only one-time purchases, subscriptions, or both:
You can also limit the number of times a discount can be used on recurring payments for subscriptions:
Conditions for code discounts
Anchor link to section titled "Conditions for code discounts"This section describes the conditions that Shopify provides for code discounts that apply to subscriptions.
Customer eligibility for discounts
Anchor link to section titled "Customer eligibility for discounts"You can limit customer eligibility for discounts to certain groups of customers and use the subscription-aware customer filters. The filters are available on the Customers page in the Shopify admin.
Eligibility for code discounts
Anchor link to section titled "Eligibility for code discounts"Eligibility of a code discount is only verified when the code discount is first applied, either at checkout or when adding the discount to an existing subscription contract. After a code discount is successfully applied, it doesn't evaluate the conditions that were used in its first application again. Other conditions, such as recurring cycle limit, still apply.
Usage limits
Anchor link to section titled "Usage limits"The usage limit of a code discount is validated when the code discount is applied to an existing subscription contract or if the code discount is used on a subscription at checkout.
If the usage limit has been reached, then the discount is rejected. The usage count of a code discount increases when it's saved on the subscription. The usage count doesn't decrease when removed from a subscription contract.
Cancellation discounts
Anchor link to section titled "Cancellation discounts"Apps that provide a cancellation discount to potential churning subscribers can configure and save the discount as a manual discount on the subscription contract.
When line items are added, updated, or removed from a subscription contract draft, Shopify reapplies the discount on the remaining applicable items.
Subscription-related webhooks
Anchor link to section titled "Subscription-related webhooks"Your app can subscribe to webhooks that are related to subscription events. The following examples show the JSON responses from each of the available webhooks.
To learn how to set up and consume webhooks, refer to Webhooks configuration overview.
Revision ID
Anchor link to section titled "Revision ID"The revision_id field in the payload for the subscription_contracts/create and subscription_contracts/update webhooks is a version identifier that you can use to determine whether your subscription contract record is up to date. You can 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 the 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.
- Learn how to create a subscription contract, and schedule and automate billing attempts for the subscription contract.
- Learn how to update a subscription contract with new information.