DRAFT ORDERS

下書き注文への割引追加に
スタッフ権限「apply_discounts_to_draft_orders」が必須に

ACCESS_DENIEDエラーはuserErrorsではなく、トップレベルのerrorsに返る点に注意

アプリ(スタッフ代理)draftOrderCreatedraftOrderUpdate+ 割引コード追加+ 自動割引ON権限チェックapply_discounts_to_draft_orders✓ 権限あり → 正常保存下書き注文が更新される✗ 権限なし → ACCESS_DENIEDnull返却・保存なしerrors[]に格納(userErrorsではない)

この変更はスタッフとして動作するアプリがdraftOrderCreate/draftOrderUpdateで割引を追加しようとした際に影響します。対象APIバージョン: すべてのサポート済みバージョン。apply_discounts_to_draft_orders権限を持たないスタッフ経由のリクエストはACCESS_DENIEDエラーとなり、下書き注文は保存されません。

1変更内容のBefore / After

BEFORE(変更前)AFTER(変更後)権限なしでも割引コード追加・自動割引ONが可能エラーなし / userErrors: [] で返却エラーハンドリングはuserErrorsのみ確認で十分だった△ 権限チェックなし権限なしの場合ACCESS_DENIEDエラーで拒否errors[].extensions.code: ACCESS_DENIEDdata.draftOrderUpdate: nulluserErrorsには出ない!トップレベルerrorsの確認が必須✓ 権限チェック強制

2影響を受けるケース / 受けないケース

🔴 影響あり
  • スタッフとして動作するアプリがdraftOrderCreate/draftOrderUpdateを呼び出す
  • かつ割引コード追加または自動割引の有効化を行う
  • かつエラーハンドリングがuserErrorsのみ
  • かつスタッフがapply_discounts_to_draft_orders権限を持っていない
🟢 影響なし
  • オフラインアクセストークンによるリクエスト(スタッフ代理でない)
  • 既存の割引コードの維持・削除のみの操作
  • スタッフが権限を持っている場合
  • 割引コードも自動割引も設定しないリクエスト

3具体的なユースケース

課題
営業スタッフが使う受注管理アプリで、顧客対応中にクーポンコードを下書き注文に付与しようとするが、権限不足でエラーになりアプリが無言で失敗する
打ち手
トップレベルのerrors配列をチェックし、code: ACCESS_DENIEDを検知した場合に「割引適用権限がありません。管理者に「Apply discounts」権限の付与を依頼してください」と明示的なエラーメッセージを表示する
効果
スタッフが状況を把握し、管理者に適切な権限付与を依頼できるため、無言の失敗による混乱を防げる
技術メモ
レスポンスのdata.draftOrderUpdateがnullになるため、null安全な処理も合わせて実装すること
課題
新規受注フローで下書き注文作成時(draftOrderCreate)に自動割引(acceptAutomaticDiscounts: true)を設定しているが、特定スタッフのリクエストだけ注文が作成されず、原因究明に時間がかかる
打ち手
draftOrderCreate時にもerrors[]をチェックする実装を追加。ACCESS_DENIEDの場合はログ記録とアラート送信を行い、管理画面で該当スタッフに下書き注文 > 割引の適用権限を付与する
効果
問題を即座に検知・対処でき、受注漏れのリスクを排除できる
技術メモ
新規作成の場合、discountCodesが空でない、またはacceptAutomaticDiscounts: trueのいずれか一方でも権限チェックの対象となる
課題
受注代行サービスでスタッフごとに操作権限を細かく管理したく、一般スタッフには割引適用を許可したくない
打ち手
Shopify管理画面のスタッフ権限設定で「下書き注文 > Apply discounts」をオフに設定。アプリ側でACCESS_DENIEDを受け取った場合は割引入力欄をグレーアウトし「この操作には追加権限が必要です」と表示する
効果
不正割引の適用を防止しつつ、スタッフへの適切なフィードバックにより業務効率を維持できる
技術メモ
オフラインアクセストークン(非スタッフ代理)でのリクエストは今回の権限チェックの対象外のため、バックエンド処理は影響を受けない

4開発者向け技術ポイント

観点 詳細
対象APIバージョン すべてのサポート済みAPIバージョン(記載なし・特定バージョン限定ではない)
エラー返却場所 userErrorsではなくトップレベルのerrors[]。extensions.code: ACCESS_DENIEDで識別する
ミューテーション戻り値 権限エラー時はdata.draftOrderCreate/data.draftOrderUpdateがnullになる。null安全な処理が必要
対象操作の範囲 ①discountCodesへの新規コード追加、②acceptAutomaticDiscountsをfalse→trueへの変更のみ。既存割引の維持・削除は影響なし
影響を受けないリクエスト オフラインアクセストークン使用時(スタッフ代理でないリクエスト)はチェック対象外
必要な権限 Shopify管理画面でスタッフに「Apply discounts」(下書き注文セクション)を付与。権限名: apply_discounts_to_draft_orders
移行対応 ①errors[]のチェック追加、②ACCESS_DENIEDの適切なハンドリング実装、③必要に応じてスタッフへの権限付与を案内するUIの追加

※ 公式ドキュメントで最新の仕様を必ずご確認ください: Access Scopes / draftOrderCreate / draftOrderUpdate

「スタッフ代理で動作するアプリは、draftOrderCreate/draftOrderUpdateにおける割引追加操作のエラーハンドリングをuserErrorsだけでなくerrors[]のACCESS_DENIEDにも対応し、必要なスタッフ権限の付与フローを整備することで、割引適用の失敗を確実に検知・案内できます。」

Source: https://shopify.dev/changelog/draft-order-discount-permission | 公開日: 2026年11月18日