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
- 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.
Scopes
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
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
This section describes the conditions that Shopify provides for code discounts that apply to subscriptions.
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
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). Once 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
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
Apps that provide a cancellation discount to potential churning subscribers can configure and save the discount as a manual discount on the subscription contract.
Line items
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
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
{
subscriptionDraft(id: "gid://shopify/SubscriptionDraft/1") {
id
lines(first: 5) {
edges {
node {
id
lineDiscountedPrice {
amount
currencyCode
}
discountAllocations {
amount {
amount
currencyCode
}
discount {
... on SubscriptionAppliedCodeDiscount {
id
}
... on SubscriptionManualDiscount {
id
}
}
}
}
}
}
}
}JSON response:
{
"data": {
"subscriptionDraft": {
"id": "gid://shopify/SubscriptionDraft/65558",
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/0a76381a-0382-41cc-a50c-ba116667480c",
"lineDiscountedPrice": {
"amount": "3.13",
"currencyCode": "USD"
},
"discountAllocations": [
{
"amount": {
"amount": "250.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/e444480d-2229-4040-a1e6-cb5790983947"
}
},
{
"amount": {
"amount": "125.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/934dcec6-8a4c-4d24-9aa4-3d8b89a9728e"
}
},
{
"amount": {
"amount": "62.5",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/2a957c6e-8db0-49d7-9d8c-f1c12605e6a8"
}
},
{
"amount": {
"amount": "31.25",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/a61cc79b-101a-4472-a174-6d470e33981c"
}
},
{
"amount": {
"amount": "15.62",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/25cae292-7527-44f0-85fa-deb083312de4"
}
},
{
"amount": {
"amount": "7.81",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/f1cf0ecd-6091-4642-abe2-952fad9c9170"
}
},
{
"amount": {
"amount": "3.91",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/eb308cac-0106-4657-8611-50222b4696de"
}
},
{
"amount": {
"amount": "0.78",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/969bfa83-1d0a-4e40-8b99-7e2121df3208"
}
}
]
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/2ae1c795-0e33-42bb-a74a-b8106545a849",
"lineDiscountedPrice": {
"amount": "500.0",
"currencyCode": "USD"
},
"discountAllocations": []
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/3cd2fc52-4b16-4f1c-9d79-91e2abb3058e",
"lineDiscountedPrice": {
"amount": "0.01",
"currencyCode": "USD"
},
"discountAllocations": [
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/6e080d47-5154-4279-965c-8f6fa8151d72"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/249dafe1-62cc-450a-a475-70bc19f5b0e2"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/70eda768-513e-4bc0-92c8-36a1ea6503f5"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/31c33505-a29b-44e3-8fee-62e646cc44cc"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/dabf2d1f-2698-42f7-86d9-76e2aa3e69db"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/9f52b67b-d030-47d2-b94f-0c5fde1a4483"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/5f0a82b1-7b27-450e-806b-67834e844b57"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/313b754a-715c-4aea-9e84-5576f3882547"
}
},
{
"amount": {
"amount": "49.99",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/49ea8c6e-d2cb-4c80-a76f-5c178df15ddb"
}
},
{
"amount": {
"amount": "50.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/99af7009-5f57-497c-85d5-b3f770b17be1"
}
}
]
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/3e4f1771-4649-4dd9-a066-3fdc5e06f3a5",
"lineDiscountedPrice": {
"amount": "500.0",
"currencyCode": "USD"
},
"discountAllocations": []
}
},
{
"node": {
"id": "gid://shopify/SubscriptionLine/866be7ce-8903-4acb-a3b2-a73a41100c55",
"lineDiscountedPrice": {
"amount": "500.0",
"currencyCode": "USD"
},
"discountAllocations": []
}
}
]
}
}
},
"extensions": {
"cost": {
"requestedQueryCost": 18,
"actualQueryCost": 18,
"throttleStatus": {
"maximumAvailable": 1000.0,
"currentlyAvailable": 982,
"restoreRate": 50.0
}
}
}
}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
mutation {
subscriptionDraftDiscountAdd(
draftId: "gid://shopify/SubscriptionDraft/1"
input: {
title: "Discount title"
recurringCycleLimit: 6
value: { percentage: 50 }
entitledLines: {
all: false
lines: {
add: [
"gid://shopify/SubscriptionLine/f4b1179c-2238-4991-bb47-353b2cae0d68"
]
}
}
}
) {
discountAdded {
id
title
type
value {
... on SubscriptionDiscountPercentageValue {
percentage
}
}
entitledLines {
all
lines(first: 10) {
edges {
node {
id
currentPrice {
amount
currencyCode
}
quantity
lineDiscountedPrice {
amount
currencyCode
}
discountAllocations {
amount {
amount
currencyCode
}
discount {
... on SubscriptionManualDiscount {
id
}
}
}
}
}
}
}
}
draft {
id
}
userErrors {
field
message
}
}
}JSON response:
{
"data": {
"subscriptionDraftDiscountAdd": {
"discountAdded": {
"id": "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6",
"title": "Discount title",
"type": "MANUAL",
"value": {
"percentage": 50
},
"entitledLines": {
"all": false,
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/f4b1179c-2238-4991-bb47-353b2cae0d68",
"currentPrice": {
"amount": "10.0",
"currencyCode": "USD"
},
"quantity": 1,
"lineDiscountedPrice": {
"amount": "5.0",
"currencyCode": "USD"
},
"discountAllocations": [
{
"amount": {
"amount": "5.0",
"currencyCode": "USD"
},
"discount": {
"id": "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6"
}
},
]
}
}
]
}
}
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/1"
},
"userErrors": []
}
}
}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
mutation {
subscriptionDraftDiscountAdd(
draftId: "gid://shopify/SubscriptionDraft/1"
input: {
title: "Discount title"
recurringCycleLimit: 6
value: { fixedAmount: { amount: 50, appliesOnEachItem: false } }
entitledLines: {
all: false
lines: {
add: [
"gid://shopify/SubscriptionLine/f4b1179c-2238-4991-bb47-353b2cae0d68"
]
}
}
}
) {
discountAdded {
id
title
type
value {
... on SubscriptionDiscountFixedAmountValue {
amount {
amount
currencyCode
}
appliesOnEachItem
}
}
entitledLines {
all
lines(first: 10) {
edges {
node {
id
currentPrice {
amount
currencyCode
}
quantity
}
}
}
}
}
draft {
id
}
userErrors {
field
message
}
}
}JSON response:
{
"data": {
"subscriptionDraftDiscountAdd": {
"discountAdded": {
"id": "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6",
"title": "Discount title",
"type": "MANUAL",
"value": {
"amount": {
"amount": 50,
"currencyCode": "USD"
},
"appliesOnEachItem": false,
},
"entitledLines": {
"all": false,
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/f4b1179c-2238-4991-bb47-353b2cae0d68",
"currentPrice": {
"amount": "10.0",
"currencyCode": "USD"
},
"quantity": 1
}
}
]
}
}
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/1"
},
"userErrors": []
}
}
}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
mutation {
subscriptionDraftFreeShippingDiscountAdd(
draftId: "gid://shopify/SubscriptionDraft/1"
input: { title: "Free shipping", recurringCycleLimit: 6 }
) {
discountAdded {
id
title
targetType
value {
... on SubscriptionDiscountPercentageValue {
percentage
}
}
}
draft {
id
}
userErrors {
field
message
}
}
}JSON response:
{
"data": {
"subscriptionDraftFreeShippingDiscountAdd": {
"discountAdded": {
"id": "gid://shopify/SubscriptionManualDiscount/7568195-11w0-4ad3-9014-9toma30ea4b6",
"title": "Free shipping",
"type": "MANUAL",
"targetType": "SHIPPING_LINE",
"value": {
"percentage": 100
}
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/1"
},
"userErrors": []
}
}
}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
mutation {
discountCodeBasicCreate(
basicCodeDiscount: {
title: "WELCOME_10%"
code: "WELCOME_10%"
customerGets: {
value: { percentage: 0.1 }
items: { all: true }
appliesOnSubscription: true
appliesOnOneTimePurchase: false
}
customerSelection: { all: true }
startsAt: "20200202T020202"
}
) {
codeDiscountNode {
id
codeDiscount {
__typename
... on DiscountCodeBasic {
title
}
}
}
userErrors {
code
field
message
}
}
}JSON response:
{
"data": {
"discountCodeBasicCreate": {
"codeDiscountNode": {
"id": "gid://shopify/DiscountCodeNode/1",
"codeDiscount": {
"__typename": "DiscountCodeBasic",
"title": "WELCOME_10%"
}
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 11,
"actualQueryCost": 11,
"throttleStatus": {
"maximumAvailable": 1000.0,
"currentlyAvailable": 989,
"restoreRate": 50.0
}
}
}
}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
mutation {
subscriptionDraftDiscountCodeApply(
draftId: "gid://shopify/SubscriptionDraft/1"
redeemCode: "WELCOME_10%"
) {
appliedDiscount {
id
redeemCode
rejectionReason
}
draft {
id
}
userErrors {
field
message
code
}
}
}JSON response:
{
"data": {
"subscriptionDraftDiscountCodeApply": {
"discountApplied": {
"id": "gid://shopify/SubscriptionAppliedCodeDiscount/17598524-27c1-4cd5-8914-9beca81ea4b6",
"redeemCode": "WELCOME_10%",
"rejectionReason": null,
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/1"
},
"userErrors": []
}
}
}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
mutation {
subscriptionDraftDiscountUpdate(
draftId: "gid://shopify/SubscriptionDraft/1"
discountId: "gid://shopify/SubscriptionManualDiscount/969bfa83-1d0a-4e40-8b99-7e2121df3208"
input: { title: "Edited discount title", value: { percentage: 10 } }
) {
discountUpdated {
id
title
type
value {
... on SubscriptionDiscountPercentageValue {
percentage
}
}
entitledLines {
all
lines(first: 10) {
edges {
node {
id
currentPrice {
amount
currencyCode
}
quantity
}
}
}
}
}
draft {
id
}
userErrors {
field
message
}
}
}JSON response:
{
"data": {
"subscriptionDraftDiscountUpdate": {
"discountUpdated": {
"id": "gid://shopify/SubscriptionManualDiscount/969bfa83-1d0a-4e40-8b99-7e2121df3208",
"title": "Edited discount title",
"type": "MANUAL",
"value": {
"percentage": 10
},
"entitledLines": {
"all": false,
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/SubscriptionLine/0a76381a-0382-41cc-a50c-ba116667480c",
"currentPrice": {
"amount": "25.0",
"currencyCode": "USD"
},
"quantity": 20
}
}
]
}
}
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/65558"
},
"userErrors": []
}
},
"extensions": {
"cost": {
"requestedQueryCost": 24,
"actualQueryCost": 15,
"throttleStatus": {
"maximumAvailable": 1000.0,
"currentlyAvailable": 985,
"restoreRate": 50.0
}
}
}
}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
mutation {
subscriptionDraftDiscountRemove(
draftId: "gid://shopify/SubscriptionDraft/1"
discountId: "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6"
) {
discountRemoved {
... on SubscriptionManualDiscount {
id
}
... on SubscriptionAppliedCodeDiscount {
id
}
}
draft {
id
}
userErrors {
field
message
code
}
}
}JSON response:
{
"data": {
"subscriptionDraftDiscountRemove": {
"discountRemoved": {
"id": "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6"
},
"draft": {
"id": "gid://shopify/SubscriptionDraft/1"
},
"userErrors": []
}
}
}Next steps
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.