Create and manage discounts on subscriptions

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

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:

This section describes the conditions that Shopify provides for code discounts that apply to subscriptions.

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.

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.

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.

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.

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

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

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

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

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

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

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

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

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