Getting started with discounts
The GraphQL Admin API enables you to create and manage many different types of discounts. This guide shows you how to create and manage automatic discounts, and introduces the basic structures for working with other types of discounts.
What you'll learn
Anchor link to section titled "What you'll learn"In this guide, you'll learn how to do the following tasks:
- Create a Buy X Get Y automatic discount
- Add and remove products from the automatic discount
- Query an automatic discount
- Delete an automatic discount
Requirements
Anchor link to section titled "Requirements"- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_discounts
access scope. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth. - You've created a development store that uses generated test data.
- You're familiar with paginating results with GraphQL.
Step 1: Create an automatic discount
Anchor link to section titled "Step 1: Create an automatic discount"A Buy X Get Y or Spend X Get Y automatic discount is an automatic discount that offers customer discounts on select products when they add a specific product to their order. You can use the discountAutomaticBxgyCreate
mutation to create a Buy X Get Y or Spend X Get Y automatic discount.
The following example shows how to create an automatic Buy One Get One discount that's applied to a single product when 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. Note the ID of the created discount, as you'll use the ID to update the discount in the next step.
The discount displays in the Discounts section of the Shopify admin:
Step 2: Add and remove products from the automatic discount
Anchor link to section titled "Step 2: Add and remove products from the automatic discount"You can pass the automatic discount node ID that you retrieved in the first step to the discountAutomaticBxgyUpdate
mutation to update the discount.
The following example updates the Buy One Get One discount that you created in the first step to apply the same discount to a different set of products. As part of the mutation's input, you must explicitly add and remove entitled products by using productsToAdd
and productsToRemove
. You can add or remove multiple products by passing them in a comma-separated list.
Step 3: Query the automatic discount
Anchor link to section titled "Step 3: Query the automatic discount"You can query the discount to retrieve the ID and confirm the details of the discount. If you already have the ID, then you can use the automaticDiscountNode
query to retrieve information about the discount. Otherwise, you can use the automaticDiscountNodes
query to browse through the list of automatic discounts on your store.
The following example uses the automaticDiscountNodes
query to retrieve information about the first three Buy X Get Y automatic discounts on the store:
Step 4 (Optional): Delete the automatic discount
Anchor link to section titled "Step 4 (Optional): Delete the automatic discount"You can pass the discount automatic node ID to the discountAutomaticDelete
mutation to permanently remove an automatic discount from the store.
The following example deletes the discount that you created in the previous steps:
Related mutations and queries
Anchor link to section titled "Related mutations and queries"This guide demonstrated how to interact with Buy X Get Y automatic discounts. However, you can use similar mutations and queries to interact with other types of discounts. The mutations and queries that you use to interact with them share similar structures to the mutations and queries that were showcased in this guide.
The following table outlines some common mutations for creating, updating, and deleting discounts of different types.
Discount type | Mutations |
---|---|
Automatic: Buy X Get Y or Spend X Get Y |
Create: discountAutomaticBxgyCreate Update: discountAutomaticBxgyUpdate Delete: discountAutomaticDelete |
Automatic: Percentage or fixed amount |
Create: discountAutomaticBasicCreate Update: discountAutomaticBasicUpdate Delete: discountAutomaticDelete |
Code: Buy X Get Y or Spend X Get Y |
Create: discountCodeBxgyCreate Update: discountCodeBxgyUpdate Delete: discountCodeDelete |
Code: Percentage or fixed amount |
Create: discountCodeBasicCreate Update: discountCodeBasicUpdate Delete: discountCodeDelete |
Code: Free shipping |
Create: discountCodeFreeShippingCreate Update: discountCodeFreeShippingUpdate Delete: discountCodeDelete |
Automatic: App |
Create: discountAutomaticAppCreate Update: discountAutomaticAppUpdate Delete: discountAutomaticDelete |
Code: App |
Create: discountCodeAppCreate Update: discountCodeAppUpdate Delete: discountCodeDelete |
The following table outlines some common queries for interacting with automatic and code discounts.
Discount type | Query a single discount by ID | Query a list of discounts |
---|---|---|
Automatic discounts | automaticDiscountNode |
automaticDiscountNodes |
Code discounts | codeDiscountNode |
codeDiscountNodes |
- Consult the GraphQL Admin API reference to learn more about the different queries and mutations that you can use to build with discounts.
- Learn how to perform bulk mutations to enable, disable, or delete large numbers of discount codes with a single request.
- Learn how to create new discount types with Shopify Functions by following our tutorial series to build a volume discount.