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). 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

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

View response

JSON response:

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

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

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

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

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

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

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:

Next steps