下書き注文への割引追加に
スタッフ権限「apply_discounts_to_draft_orders」が必須に
ACCESS_DENIEDエラーはuserErrorsではなく、トップレベルのerrorsに返る点に注意
この変更はスタッフとして動作するアプリがdraftOrderCreate/draftOrderUpdateで割引を追加しようとした際に影響します。対象APIバージョン: すべてのサポート済みバージョン。apply_discounts_to_draft_orders権限を持たないスタッフ経由のリクエストはACCESS_DENIEDエラーとなり、下書き注文は保存されません。
1変更内容のBefore / After
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日






Share:
在庫入荷APIにキャンセル受領アクション追加
管理画面カスタムアプリがDev Dashboardへ統合