Create and manage discounts with the Admin API
This guide describes how to create and retrieve discounts by using the GraphQL Admin API. It provides examples for two different types of discounts (automatic discounts and code discounts), and the recommended best practices for each type.
For a full list of the schema, see the GraphQL Admin API reference.
If you aren’t familiar with GraphQL, then refer to the Getting started with the GraphQL Admin and REST Admin APIs guide or The GraphQL Learning Kit to learn more.
- The mutations described here require the
- The queries described here require the
Creating automatic discounts
Automatic discounts refer to the set of objects and mutations in GraphQL that let you create and manage discounts that are automatically applied to a cart if prerequisites are met. This method is available only in the GraphQL Admin API.
The following examples show two different types of automatic discounts:
Buy X Get Y or Spend X Get Y automatic discount
This example shows how to create an automatic Buy One Get One discount that will be applied to a single product any time it’s included in a cart. In this case, it applies a 100% discount on the second item in a cart, as long as it’s the same product as the first item.
Based on that example, you can make a few different changes to offer specific types of discounts:
- If you want to change the discount amount, then edit
- If you want to apply the discount to a different item, then use
customerGets.items.products.productsToRemoveto update the entitlements.
- If you want to apply the discount to all items, then use
customerGets.items.allinstead of a specific product ID.
- If you want a customer to get a discount no matter which item they purchase, then set the
trueinstead of a specific product.
Percentage or fixed-amount automatic discount
This example shows how to create an automatic discount of 10% that will be applied to a single product any time it’s included in a cart. The
percentage input requires a value between 0 and 1. In the example below
0.10 represents 10% off. A 100% discount would be
1.0 and a 50% discount would be
Creating code discounts
Code discounts refer to the set of objects and mutations in GraphQL that let you create and manage discounts that include a unique code. Code discounts enable specific discounts to be redeemed when the codes are applied manually by the customer during the checkout. This method is available only in the GraphQL Admin API.
The following examples show three different types of code discounts:
- Buy X Get Y or Spend X Get Y code discount
- Free Shipping code discount
- Percentage or fixed-amount discount code
Buy X Get Y or Spend X Get Y code discount
This example shows how to create a Spend $100 Get One discount that requires the customer to enter a code at checkout. In this case, it lets all customers use this code, and offers a spend $100 and get one discount on the same product. You can also change the discount so that it applies to a different product than the original.
Percentage or fixed-amount discount code
This example shows how to associate a flat percentage or fixed-amount discount with a code that the customer can use at checkout. Similar in format to creating a buy one get one discount, here we will create a $1.00 off discount for a specific product.
Free Shipping code discount
This example shows how to associate a Free Shipping discount with a code that will grant the customer free shipping when they use it. In this example, the discount applies to a saved search of customers in
customerSelection.customerSavedSearches if those customers are from Canada. If you want to provide the discount to all countries, then you can replace
destination.all set to
true. Note that if you specify a country where you want to offer free shipping, the shop must have a shipping zone configured for that country before it will work.
You can use the API to manage and make changes to your current discounts.
Query automatic discounts on a shop
When making GraphQL queries, you can return multiple objects at a time. The following example shows how to request the first 10 automatic discount codes, which returns the details about whether they’re either the
Query a specific automatic discount
To query a specific automatic discount, all you need is its ID. The following example query might look complicated because it uses a concept called fragments. This lets you create a query that returns the information only if it matches your criteria. In this case, we are requesting all possible information about this discount no matter what type it is, in case we don’t know the details of the automatic discount beforehand.