Manage existing discounts
You can use the GraphQL Admin API to manage existing discounts. This guide shows you how to query and make changes to automatic and code discounts.
Requirements
Anchor link to section titled "Requirements"- You've created automatic or code discounts.
- Your app has the
read_discounts
andwrite_discounts
access scopes. - You're familiar with paginating results with GraphQL.
Step 1: Query discounts
Anchor link to section titled "Step 1: Query discounts"Offering discounts can be a powerful marketing strategy for a Shopify store. You can use the following GraphQL Admin API queries to retrieve automatic discounts and code discounts on a store:
Query | Description | Example |
---|---|---|
automaticDiscountsNodes | Retrieves a list of automatic discounts | Retrieve the first three automatic discounts |
automaticDiscountsNode | Retrieves an automatic discount | Query an automatic discount by its ID |
codeDiscountNodes | Retrieves a list of code discounts | |
codeDiscountNode | Retrieves a code discount | Query a code discount by its ID |
Retrieve the first three automatic discounts
Anchor link to section titled "Retrieve the first three automatic discounts"To retrieve the automatic discounts on a store, query automaticDiscountsNodes
, and specify a query parameter to limit your results.
The following example shows how to request the first three automatic discounts, which returns the details about whether they’re either the BxGy
or Basic
type.
Query an automatic discount by its ID
Anchor link to section titled "Query an automatic discount by its ID"To retrieve an automatic discount on a store, query automaticDiscountsNode
, and supply the ID of the automatic discount node.
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, you're requesting all possible information about this discount no matter what type it is, in case you don’t know the details of the automatic discount beforehand.
Retrieve the first 10 code discounts
Anchor link to section titled "Retrieve the first 10 code discounts"To retrieve the code discounts on a store, query codeDiscountNodes
, and specify a query parameter to limit your results. The following example shows how to query the first 10 basic code discounts on a store.
Query a code discount by its ID
Anchor link to section titled "Query a code discount by its ID"To retrieve a code discount on a store, query codeDiscountNode
, and supply the ID of the code discount node.
The following example shows all possible fields on a basic code discount. You can replace the DiscountCodeBasic
fragment with DiscountCodeBxgy
or DiscountCodeFreeShipping
. Although they all have a slight variation in the return fields, the basic format is the same.
Paginate through code discounts
Anchor link to section titled "Paginate through code discounts"To paginate through code discounts, query codeDiscountNodes
, and specify a query parameter to limit your results.
The following example retrieves the first 10 code discounts, and paginates through the discounts using the pageInfo
and cursor
parameters. The way that the pageInfo
and cursor
parameters are structured in the codeDiscountNodes
object is similar to how they're structured elsewhere in GraphQL.
Step 2: Update discounts
Anchor link to section titled "Step 2: Update discounts"After you've queried discounts, you can use GraphQL Admin API mutations to update discounts. The following table provides some example mutations that can be used to perform different actions on discounts:
Mutation | Description | Example |
---|---|---|
discountAutomaticBxgyUpdate | Updates an existing Buy X Get Y automatic discount | Update an automatic discount |
discountAutomaticActivate | Activates an automatic discount | Activate an automatic discount |
discountAutomaticDeactivate | Deactivates an automatic discount | Deactivate an automatic discount |
discountCodeBxgyUpdate | Updates a Buy X Get Y code discount | Update a code discount |
discountCodeBulkActivate | Asynchronously activates code discounts in bulk using a search query, a customer segment ID, or a list of discount code node IDs | Bulk activate code discounts |
Update an automatic discount
Anchor link to section titled "Update an automatic discount"The mutation that you use to update an automatic discount depends on the type of discount that you want to update:
- If it's a Buy X Get Y discount, then use the
discountAutomaticBxgyUpdate
mutation. - If it's a basic discount, then use the
discountAutomaticBasicUpdate
mutation.
The following example shows how to use the discountAutomaticBxgyUpdate
mutation to update a Buy X Get Y discount. 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.
Update a code discount
Anchor link to section titled "Update a code discount"The mutation that you use to update a code discount depends on the type of discount that you want to update:
- If it's a Buy X Get Y discount, then use the
discountCodeBxgyUpdate
mutation. - If it's a basic discount, then use the
discountCodeBasicUpdate
mutation. - If it's a free shipping discount, then use the
discountCodeFreeShippingUpdate
mutation.
The following example shows how to use the discountCodeBxgyUpdate
mutation to update a Buy X Get Y discount. 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.
Activate an automatic discount
Anchor link to section titled "Activate an automatic discount"You can activate an automatic discount so that it's available to customers. For example, you might want to activate a discount at the start of a promotion.
To activate an automatic discount, use the discountAutomaticActivate
mutation, and pass in the ID of the automatic discount node. The response returns the status of the automatic discount as ACTIVE
.
Deactivate an automatic discount
Anchor link to section titled "Deactivate an automatic discount"You can temporarily deactivate an unexpired automatic discount. For example, you might want to deactivate an automatic discount at the end of the promotion or when a merchant plans to try a different marketing strategy.
To deactivate an automatic discount, use the discountAutomaticDeactivate
mutation, and pass in the ID of the automatic discount node. The response returns the status of the automatic discount as EXPIRED
.
Bulk activate code discounts
Anchor link to section titled "Bulk activate code discounts"You can asynchronously activate code discounts in bulk by using the discountCodeBulkActivate
mutation, and passing in the IDs of the discount code nodes that you want to activate.
The following example bulk activates three code discounts. The response returns a job ID that you can use to check on the job status and determine whether the operation is complete.
Check on the job status
Anchor link to section titled "Check on the job status"To verify if a previous bulk discount operation has completed, you can query the mutation's returned job:
- If
done
istrue
, then the bulk operation has completed. - If
done
isfalse
, then the bulk operation is still in progress.
Step 3: Delete discounts (optional)
Anchor link to section titled "Step 3: Delete discounts (optional)"If you want to permanently remove a discount from a Shopify store, then you can either delete an individual discount or bulk delete discounts using the GraphQL Admin API.
Delete an individual discount
Anchor link to section titled "Delete an individual discount"The mutation that you use to delete a discount depends on the type of discount that you want to delete:
- If it's an automatic discount, then use the
discountAutomaticDelete
mutation. - If it's a code discount, then use the
discountCodeDelete
mutation.
The following example shows how to delete an automatic discount by using the discountAutomaticDelete
mutation and passing in the ID of the discount automatic node.
Bulk delete discounts
Anchor link to section titled "Bulk delete discounts"The mutation that you use to bulk delete discounts depends on the types of discounts that you want to delete:
- If they're automatic discounts, then use the
discountAutomaticBulkDelete
mutation. - If they're code discounts, then use the
discountCodeBulkDelete
mutation.
The following example shows how to delete automatic discounts in bulk by using the discountAutomaticBulkDelete
mutation and passing in the IDs of the discount automatic nodes.
- Create a discount that's automatically applied to a cart if prerequisites are met.
- Create a discount that includes a unique code.