Shopify 在 2026 年 11 月 18 日把一項草稿訂單折扣權限檢查套用到所有受支援的 Admin API 版本。當 App 以 staff member 身分呼叫 draftOrderCreate 或 draftOrderUpdate,若該人員沒有 apply_discounts_to_draft_orders 權限,新增折扣碼或開啟自動折扣會回傳頂層 GraphQL ACCESS_DENIED,mutation payload 是 null,而且不會儲存草稿訂單。
這是已生效的破壞性行為,不是未來 API 版本才會遇到。最容易漏接的地方是錯誤位置:許多整合只讀 mutation payload 裡的 userErrors,但這次拒絕出現在 response 的頂層 errors。如果程式看到 userErrors 為空就當作成功,可能留下「前台顯示已建立、Shopify 實際沒有訂單」的錯誤狀態。
哪些流程受影響,哪些不受影響
官方列出的必要條件有三個:請求以 staff member 身分執行、呼叫建立或更新草稿訂單、而且嘗試新增 discount code 或把 acceptAutomaticDiscounts 設為 true。建立新草稿訂單時,只要 discountCodes 非空或開啟自動折扣,就算新增折扣;更新既有訂單時,保留或移除現有折扣仍可運作。
使用 offline access token、沒有代入 staff member 的請求不在這次影響範圍。這不代表 offline token 一定是最佳修正,也不代表應為避開權限檢查而改掉身分模型。以操作人員身分執行能保留責任邊界;若流程確實要代表某位員工套用折扣,正確做法是檢查角色與權限、提示商家授權,並在稽核紀錄保存執行者。
受影響場景常見於客服代客下單、B2B 議價報價、電話訂單、POS 後續處理,以及 ERP/CRM 把報價同步成 Shopify draft order。純 storefront 結帳、只讀訂單或不加入折扣的草稿流程,不應因標題而被誤判為全面中斷。
先修錯誤處理,再決定權限策略
GraphQL client 應同時處理 HTTP 狀態、response 頂層 errors、data 是否為 null,以及 mutation payload 的 userErrors。只有四層都符合預期,才能把本地訂單標記為已同步。對 ACCESS_DENIED,記錄 operation、shop、staff 身分識別、request correlation ID 與必要欄位,但不要把 access token、完整顧客資料或折扣敏感內容寫進 log。
前台訊息也應區分可修正權限與一般系統錯誤。例如提示管理者到角色設定授予 Draft orders 的 Apply discounts,且套用 discount code 時還需要 Discounts 權限;一般員工只應看到「你沒有套用草稿訂單折扣的權限,請聯絡管理者」,不應顯示 GraphQL 內部堆疊或 token scope。
不要一遇到拒絕就自動重試。相同 staff 權限不會因重試而改變,反而可能製造重複的本地工作或噪音告警。只有在管理者完成授權、重新驗證 session 後才重送;重送前以 idempotency key 或本地狀態確認沒有另一條路徑已建立訂單。
最小權限、服務帳號與 offline token 怎麼選
人工代客下單介面適合沿用 staff 身分,讓每個人只能做角色允許的操作。管理者可把 Apply discounts 限制給確實負責定價或客服補償的人員,並搭配 Shopify 的 Discounts permission。這種做法稽核清楚,但 onboarding、調職與離職時要同步更新角色。
後台批次整合若本來就代表商店而不是個別員工,可以評估既有官方支援的 offline access token 流程;它仍需正確的 App scopes、token 保護與撤銷機制,不能把 staff permission 與 OAuth access scope 混成同一件事。不要為了快速恢復功能,把人員都升成商店管理者或分享單一高權限帳號。
若折扣不是業務必要,可以讓無權限人員先建立不含折扣的草稿,再由有權限的人員審核套用。這會多一個步驟,但對高折扣、B2B 特價或退款補償,雙人檢查可能比全員授權更合適。系統需明確標示「待折扣審核」,不能默默移除折扣後照原價送出發票。
可重現的修正與驗收步驟
先在程式碼搜尋 draftOrderCreate、draftOrderUpdate、discountCodes、acceptAutomaticDiscounts 與只解析 userErrors 的位置。建立四組測試角色:有完整折扣權限、缺少 Apply discounts、缺少 Discounts,以及不使用 staff session 的合法後台流程。測試建立與更新分開進行,並覆蓋新增、保留、移除折扣和自動折扣開關。
接著在 staging shop 驗證:無權限請求回傳頂層 ACCESS_DENIED、payload 為 null、本地不標記成功、不寄發錯誤金額的 invoice,也不建立重複重試;授權後重送則只產生一張草稿訂單。再測一個非權限錯誤,確認新的 handler 沒有把所有 GraphQL errors 都誤導成請管理者加權限。
上線時先監控兩項比例:草稿訂單 mutation 的頂層錯誤率,以及本地「已同步」但 Shopify ID 為空的數量。兩者都應按 shop 與版本觀察,避免只看總量掩蓋單一商家角色設定。正式發布前通知客服與商家管理者新的權限條件,並準備可撤回的應用程式版本。
這次變更提醒電商整合不能把 GraphQL userErrors 當成唯一失敗通道,也不能把人員角色、App scope 與 token 型態混用。先修正 response 判定,再依流程風險選擇 staff 最小權限、審核分工或正式的後台身分,才能避免用過度授權交換短期恢復。