Create and manage discounts on subscriptions
You can apply different discount types on subscriptions, including percentage, fixed amount, and free shipping discounts.
This tutorial illustrates the calls you can make to manage discounts on subscriptions. It also provides information about customer eligibility for discounts, adding Shopify code discounts, and cancellation discounts.
Requirements
Anchor link to section titled "Requirements"- You've completed our Getting started with the GraphQL Admin and REST Admin APIs guide and you're authenticated with the API.
- You've created products and product variants in your test shop.
- You've completed the Create and manage selling plans and Create and manage subscription contracts tutorials.
- You're familiar with the following API objects: subscription draft and discount codes.
To use the GraphQL mutations, your app needs to request the following access scopes for a Shopify store:
read_own_subscription_contracts
: Allow apps to read subscription contracts mutations for contracts they own.write_own_subscription_contracts
: Allow apps to write subscription contracts mutations for contracts they own.write_discounts
: Allows apps to manage Shopify code 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.00 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 if 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 a specific group 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"When adding a code discount, eligibility of the code discount is only verified on the first application (either at checkout or when adding a discount to an existing subscription contract). After a code discount is successfully applied, it doesn't re-evaluate the conditions 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, the discount is rejected. The usage count of a code discount increases when it is saved on the subscription. The usage count does not 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 will reapply the discount on the remaining applicable items.
Query discount allocations on a subscription contract
Anchor link to section titled "Query discount allocations on a subscription contract"To see the discounts that have been applied to a subscription contract, you can query the discount allocations. The following example illustrates how to query the discount allocations on the first 5 lines of a subscription contract.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Add a percentage discount to a subscription contract
Anchor link to section titled "Add a percentage discount to a subscription contract"You can use the subscriptionDraftDiscountAdd
mutation to add a percentage discount to a subscription contract.
In the following example, the recurringCycleLimit
refers to the number of recurring cycles the discount can be used when applied to any subscription contract. No limit means the discount applies indefinitely. Once the limit has been reached, the discount stops being effective on the subscription lines on a particular subscription contract. Apps can update (adjust contract lines, values, or limits) or remove the discount from the subscription contract.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Add a fixed amount discount to a subscription contract
Anchor link to section titled "Add a fixed amount discount to a subscription contract"To add a fixed amount discount to a subscription contract, use the subscriptionDraftDiscountAdd
mutation. In the following example, a fixed amount discount of $50.00 is applied to the subscription contract.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Add a free shipping discount to a subscription contract
Anchor link to section titled "Add a free shipping discount to a subscription contract"The subscriptionDraftFreeShippingDiscountAdd
mutation updates a free shipping discount on the subscription contract draft. In the following example, free shipping is added on the subscription contract.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Create a subscription discount code
Anchor link to section titled "Create a subscription discount code"You can use the discountCodeBasicCreate
mutation to create a basic code discount. Define the appliesOnSubscription
field as true
to specify that the discount can be applied to a subscription.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Apply a discount code to a subscription contract
Anchor link to section titled "Apply a discount code to a subscription contract"Use the subscriptionDraftDiscountCodeApply
mutation to apply a discount code to a subscription contract. In the following example, a welcome 10% off discount code is applied to the subscription contract.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Update a discount on a subscription contract
Anchor link to section titled "Update a discount on a subscription contract"The subscriptionDraftDiscountUpdate
mutation updates a discount on the subscription contract draft. In the following example, the title
and percentage
value of the discount is updated.
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Remove a discount on a subscription contract
Anchor link to section titled "Remove a discount on a subscription contract"At any time, you can use the subscriptionDraftDiscountRemove
mutation to remove a discount from a subscription contract:
Request
POST /admin/api/2021-01/graphql.json
View response
JSON response:
Create and manage subscription shipping rates and delivery methods: Learn how to update delivery methods on subscriptions and understand the shipping rates customers see during checkout.
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.