Admin GraphQL API / Permission change

To "add" a discount to a draft order,
the staff member's discount permission is now required

draftOrderCreate / draftOrderUpdate called as a staff member: if the appapply_discounts_to_draft_orders tries to add a discount for a staff member without the permission, it gets ACCESS_DENIED. The draft order isn't saved, and the error is returned not in userErrors but in the top-level errors . Applies to all supported API versions.

On this page
  1. What's changing (30-second overview)
  2. How it works: the path to a rejected request
  3. Operations that count as "adding a discount" vs. those that don't
  4. How errors are returned (sample request and response)
  5. Affected vs. unaffected apps
  6. How to respond (3 steps)
  7. 5 key points for developers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

When an app acting as a staff member tries toadd a newdiscount to a draft order and that staff member doesn't have the apply_discounts_to_draft_orders permission, the entire mutation is rejected with ACCESS_DENIED .
The draft order isn't saved, and the payload returns null. The error doesn't appear in userErrors .

Staff without permission + adding a discount

Top-level errors contains ACCESS_DENIED.data.draftOrderUpdate(or draftOrderCreate) returns null. No changes are saved at all.

Keeping or removing existing discounts

Existing discounts on a draft order can still bekept as is, orremovedjust as before. Only adding discounts is rejected.

2How it works: the path to a rejected request

App Runs as staff draftOrderCreate/Update Adding a discount? No (keep/remove only) Yes Staff permission? apply_discounts_ to_draft_orders? Yes No ACCESS_DENIED Returned in top-level errors payload = null Draft order is not saved Processed as before On failure, userErrors as before
The check is based onwhether the request is acting as a staff member. Requests that don't act as staff, such as those using an offline access token, are not subject to this check.

3Operations treated as adding a discount vs. not

Operation (DraftOrderInput)draftOrderUpdatedraftOrderCreate
discountCodes set with a code Counts as adding Contains a codenot already onthe draft order Counts as adding Always, if not empty(since the draft order doesn't exist yet)
acceptAutomaticDiscounts: true Counts as adding Set to true on a draft order that doesn't yet accept automatic discounts Counts as adding Always, if true
Keep existing discounts Works as before —
Remove existing discounts Works as before —
Rejection applies to the entire mutation.Even if the same request also updates non-discount fields (line items, customer, etc.), none of those changes are saved if the request includes adding a discount.

4How the error is returned (example request and response)

Request: Add a discount code to an existing draft order and also turn on automatic discounts

mutation
mutation draftOrderUpdate($id: ID!, $input: DraftOrderInput!) {
 draftOrderUpdate(id: $id, input: $input) {
 draftOrder {
 id
 discountCodes
 acceptAutomaticDiscounts
 }
 userErrors {
 field
 message
 }
 }
}
variables
{
 "id": "gid://shopify/DraftOrder/276395349",
 "input": {
 "discountCodes": ["SUMMER10"],
 "acceptAutomaticDiscounts": true
 }
}

Response: When the staff member doesn't have the apply_discounts_to_draft_orders permission

response
{
 "errors": [
 {
 "message": "Access denied for draftOrderUpdate field. Required access: `write_draft_orders` access scope. Also: The user must have access to manage draft orders.",
 "locations": [{ "line": 2, "column": 3 }],
 "path": ["draftOrderUpdate"],
 "extensions": {
 "code": "ACCESS_DENIED",
 "documentation": "https://shopify.dev/api/usage/access-scopes",
 "requiredAccess": "`write_draft_orders` access scope. Also: The user must have access to manage draft orders."
 }
 }
 ],
 "data": {
 "draftOrderUpdate": null
 }
}
Point 1

userErrors isn't empty — it doesn't exist at all

The payload itself is null , so code that readsdata.draftOrderUpdate.userErrors breaks at that point.

Point 2

The identifier is extensions.code

The error type is identified by extensions.code = "ACCESS_DENIED", and the target by path .

Point 3

Create works the same way

draftOrderCreate returns the same error. The message and path become draftOrderCreate , anddata.draftOrderCreate is null.

5Apps that are affected / not affected

Affected (all three conditions apply)

Condition 1

Calls as a staff member

draftOrderCreate or draftOrderUpdate is run as a staff member.

Condition 2

Adds discounts

Relies on adding discount codes or turning on automatic discounts.

Condition 3

Doesn't check permissions

Doesn't make sure the staff member has the apply_discounts_to_draft_orders permission.

Not affected

Not applicable

Requests not made as a staff member

For example, requests made with an offline access token.

Not applicable

Requests that don't add discounts

Requests that only keep or remove existing discounts.

6How to respond (3 steps)

1

Find the call sites

Find places that, acting as staff, call draftOrderCreate / draftOrderUpdate and passdiscountCodes or acceptAutomaticDiscounts .

2

Check top-level errors too

userErrors alone isn't enough. Add handling that checks the top-level errors array for ACCESS_DENIED .

3

Ask the merchant to grant permissions

If you need to add discounts, ask the merchant to give staff the Apply discounts permission under Draft orders.

Related docs: draftOrderCreate / draftOrderUpdate / DraftOrderInput / Store permissions (both on shopify.dev).

75 key points for developers

null

1. Handling that relies on userErrors will break

If you detect failures using only userErrors.length , the payload null may throw an exception or be misread as a success. The article explicitly states that error handling needs to be updated.

ALL ver.

2. Applies to all supported versions

This isn't a change starting from a specific API version. It applies to all supported versions, so the behavior changes even if you stay on your current version.

3. Check the code, not the message text

In the example response, message / requiredAccess mention the write_draft_orders scope. The wording doesn't make it clear that the cause is the discount permission, so it's safer to branch onextensions.code and path .

Diff New

4. Update is judged by the diff, Create by whether a value is present

Update only covers adding codes that don't already exist, or newly turning on automatic discounts. For Create, a non-empty discountCodes or acceptAutomaticDiscounts: true isalwaystreated as an addition. On Update, simply resending existing values as-is won't trigger it.

5. Impact depends on the token type

The change affectsrequests acting as staffonly. Requests that don't act as a staff member, such as those using offline access tokens, are not affected. The fastest way to assess impact is to inventory which token type your apps use to call the draft order API.

8Three use cases you can put to work

!
USE CASE 1

An "error-handling audit" for a draft order app under contract development

Challenge
Quote and proxy-ordering apps may detect draft order creation failures using userErrors alone, which means this ACCESS_DENIED could be missed.
Action
Inventory every place that, acting as staff, calls draftOrderCreate / draftOrderUpdate , then add shared handling that checks the top-level errors for ACCESS_DENIED .
Impact
Prevents the "I thought it saved, but the draft order doesn't exist" bug before it happens. You can use this as-is as an impact assessment report for maintenance clients.
Technical notes
Detect it using extensions.code and path(draftOrderCreate / draftOrderUpdate). Write null-safe code, assuming the payload will be null .
USE CASE 2

Proposing a review of "staff permission design" to merchants

Challenge
Staff handling phone and chat orders can no longer create discounted draft orders through the app, which brings operations to a halt.
Action
Identify the staff who need to apply discounts, and ask the merchant to grant them the Apply discounts permission under "Draft orders". Don't grant it to staff who don't need it.
Impact
Lets merchants explicitly limit who can apply discounts while avoiding operational disruptions.
Technical notes
When ACCESS_DENIED is detected, showing a message in the app UI such as "Ask your admin to grant you the Apply discounts permission" reduces support inquiries.
Discount Add Line items Update
USE CASE 3

Separate discount additions from the request to prevent collateral failures

Challenge
A single draftOrderUpdate call sends both line item changes and discount additions, so when permissions are insufficient, even the line item changes aren't saved.
Action
Before sending, check whether the input adds a discount (new codes indiscountCodes ,acceptAutomaticDiscounts: true) and, if needed, redesign the flow so non-discount updates are sent first.
Impact
Staff without the permission can still reliably save all non-discount changes.
Technical notes
Updates that only keep or remove existing discounts work as before. In Create, a non-empty discountCodes is always treated as adding a discount, so you need a branch that creates the order without discounts for staff who lack the permission.

9One-line summary for proposals

"For staff toadddiscounts to draft orders, theapply_discounts_to_draft_orders permission is now required.
Without it, the entire save fails with ACCESS_DENIED, and the error appears in top-level errors rather than userErrors.
Update your error handling and grant staff the permission: those two steps are all it takes."