All Tutorials

Create and manage discounts on subscriptions

All Tutorials

Create and manage discounts on subscriptions

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

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:

Purchase type options screenshot

You can also limit the number of times a discount can be used on recurring payments for subscriptions:

Recurring payments for subscriptions screenshot

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
              }
            }
          }
        }
      }
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

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
    }
  }
}

View response

JSON response:

{
 "data": {
   "subscriptionDraftDiscountRemove": {
     "discountRemoved": {
       "id": "gid://shopify/SubscriptionManualDiscount/18945661-27c0-4cd5-8914-9cbaa81ea4b6"
     },
     "draft": {
       "id": "gid://shopify/SubscriptionDraft/1"
     },
     "userErrors": []
   }
 }
}

Next steps