下書き注文に割引を「追加」するには スタッフの割引権限が必須に
原題: draftOrderCreate and draftOrderUpdate require the apply_discounts_to_draft_orders permission to add discounts
- Admin API
- GraphQL
- Draft Orders
- Discounts
- スタッフ権限
- ACCESS_DENIED
- エラーハンドリング
- Orders
- 仕様変更
図解 : draftOrderCreate / draftOrderUpdate で割引を追加するには apply_discounts_to_draft_orders 権限が必須に Admin GraphQL API / 権限変更 下書き注文に割引を「追加」するには スタッフの割引権限が必須に draftOrderCreate / draftOrderUpdate をスタッフとして実行するアプリが、 apply_discounts_to_draft_orders 権限の無いスタッフで割引を追加しようとすると ACCESS_DENIED 。下書き注文は保存されず、エラーは userErrors ではなく トップレベル errors に返る。全サポート対象 API バージョンで適用。 このページの構成 そもそも何が変わるのか(30秒で理解) 仕組み図解 : リクエストが拒否されるまで 「割引の追加」と判定される操作/されない操作 エラーの返り方(リクエスト例とレスポンス例) 影響を受けるアプリ/受けないアプリ 対応手順(3ステップ) 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか スタッフとして動くアプリが下書き注文に割引を 新しく追加 しようとしたとき、そのスタッフが apply_discounts_to_draft_orders 権限を持っていなければ、ミューテーション全体が ACCESS_DENIED で拒否される。 下書き注文は保存されず 、ペイロードは null 。エラーは userErrors には出ない。 権限なしスタッフ + 割引の追加 トップレベル errors に ACCESS_DENIED 。 data.draftOrderUpdate (または draftOrderCreate )は null 。変更は一切保存されない。 既存割引の維持・削除 下書き注文の既存割引を そのまま残す 、または 外す 操作はこれまで通り動く。拒否されるのは「追加」だけ。 2 仕組み図解 : リクエストが拒否されるまで 判定は 「スタッフとして動いているリクエストかどうか」 が前提。offline アクセストークンでのリクエストなど、スタッフとして動かないリクエストはこのチェックの対象外。 3 「割引の追加」と判定される操作/されない操作 操作(DraftOrderInput) draftOrderUpdate draftOrderCreate discountCodes にコードを入れる 追加扱い 下書き注文に まだ無いコード を含む場合 追加扱い 空でなければ常に (下書き注文がまだ存在しないため) acceptAutomaticDiscounts: true 追加扱い まだ自動割引を受け付けていない下書き注文で true にする場合 追加扱い true なら常に 既存の割引を維持する 従来通り — 既存の割引を外す 従来通り — 拒否はミューテーション単位。 割引以外の項目(明細・顧客など)を同じリクエストで更新していても、割引の追加が含まれていればその変更もまとめて保存されない。 4 エラーの返り方(リクエスト例とレスポンス例) リクエスト : 既存の下書き注文に割引コードを追加し、自動割引も ON にする 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 } } レスポンス : スタッフに apply_discounts_to_draft_orders 権限が無い場合 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 } } ポイント1 userErrors は空ではなく「存在しない」 ペイロード自体が null なので、 data.draftOrderUpdate.userErrors を読む実装はそこで止まる。 ポイント2 識別子は extensions.code エラーの種別は extensions.code = "ACCESS_DENIED" 、対象は path で判別できる。 ポイント3 Create も同じ形 draftOrderCreate も同じエラー。message と path が draftOrderCreate になり、 data.draftOrderCreate が null 。 5 影響を受けるアプリ/受けないアプリ 影響を受ける(次の3条件をすべて満たす) 条件 1 スタッフとして呼び出す draftOrderCreate または draftOrderUpdate をスタッフとして実行している。 条件 2 割引を追加する 割引コードの追加、または自動割引の有効化を前提にしている。 条件 3 権限を確認していない スタッフが apply_discounts_to_draft_orders 権限を持っていることを担保していない。 影響を受けない 対象外 スタッフとして動かないリクエスト offline アクセストークンでのリクエストなど。 対象外 割引を追加しないリクエスト 既存割引の維持・削除のみを行うリクエスト。 6 対応手順(3ステップ) 1 呼び出し箇所を洗い出す スタッフとして draftOrderCreate / draftOrderUpdate を呼び、 discountCodes や acceptAutomaticDiscounts を渡している箇所を特定。 2 トップレベル errors も見る userErrors だけでなく、トップレベルの errors 配列で ACCESS_DENIED を検知する処理を入れる。 3 マーチャントに権限付与を依頼 割引の追加が必要なら、スタッフに「下書き注文」配下の Apply discounts 権限を付けてもらう。 関連ドキュメント : draftOrderCreate / draftOrderUpdate / DraftOrderInput / Store permissions(いずれも shopify.dev)。 7 技術者が押さえるべき5つのポイント 1. userErrors 依存のハンドリングは壊れる 失敗判定を userErrors.length だけで行うと、ペイロード null で例外になるか「成功」と誤判定する恐れがある。記事は エラー処理の更新が必要 と明記。 2. 全サポート対象バージョンで適用 特定 API バージョンからの変更ではなく、サポートされている全バージョンが対象。バージョンを据え置いても挙動は変わる。 3. message 文面ではなく code で判定する 例のレスポンスの message / requiredAccess には write_draft_orders スコープの文言が出ている。原因が割引権限であることは文面からは読み取りにくいため、 extensions.code と path で分岐するのが安全。 4. Update は「差分」、Create は「値の有無」で判定 Update は既存に無いコードの追加/自動割引の新規 ON だけが対象。Create は空でない discountCodes や acceptAutomaticDiscounts: true が 常に 追加扱い。既存値をそのまま送り直すだけなら Update では引っかからない。 5. トークン種別で影響範囲が分かれる 影響を受けるのは スタッフとして動くリクエスト のみ。offline アクセストークンなどスタッフとして動かないリクエストは対象外。自社アプリがどちらのトークンで下書き注文 API を叩いているかの棚卸しが、影響調査の最短ルート。 8 業務に活かせる3つのユースケース USE CASE 1 受託開発中の下書き注文アプリの「エラー処理監査」 課題 見積・代理注文系のアプリで、下書き注文作成の失敗を userErrors だけで判定しており、今回の ACCESS_DENIED を取りこぼす可能性がある。 打ち手 スタッフとして draftOrderCreate / draftOrderUpdate を呼ぶ箇所を棚卸しし、トップレベル errors の ACCESS_DENIED を検知する共通処理を追加。 効果 「保存されたと思ったら下書き注文が存在しない」不具合を未然に防止。保守契約先への影響調査レポートとしてそのまま使える。 技術メモ 判定は extensions.code と path ( draftOrderCreate / draftOrderUpdate )で。ペイロードが null になる前提で null 安全に書く。 USE CASE 2 マーチャント向け「スタッフ権限設計」の見直し提案 課題 電話・チャット受注を担当するスタッフが、アプリ経由で割引付きの下書き注文を作れなくなり、現場で業務が止まる。 打ち手 割引を付ける必要があるスタッフを特定し、「下書き注文」配下の Apply discounts 権限を付与するようマーチャントに依頼。不要なスタッフには付けない。 効果 割引を付けられる人を明示的に絞った運用に整理でき、業務停止も避けられる。 技術メモ ACCESS_DENIED を検知したら「管理者に Apply discounts 権限の付与を依頼してください」とアプリ UI で案内すると、問い合わせ対応が減る。 USE CASE 3 割引の追加をリクエストから切り離して巻き添え失敗を防ぐ 課題 1 回の draftOrderUpdate で明細変更と割引追加をまとめて送っているため、権限不足だと明細の変更まで保存されない。 打ち手 割引を追加する入力( discountCodes の新規コード、 acceptAutomaticDiscounts: true )を含むかどうかを送信前に判定し、必要に応じて割引以外の更新を先に送るよう設計を見直す。 効果 権限が無いスタッフでも、割引以外の作業は確実に保存される。 技術メモ Update で既存割引を維持・削除するだけなら従来通り動く。Create は空でない discountCodes が常に追加扱いなので、権限が無いスタッフでは割引なしで作成する分岐が必要。 9 提案で使える1行サマリ 「スタッフとして下書き注文に割引を 追加 するには、 apply_discounts_to_draft_orders 権限が必須に。 権限が無いと ACCESS_DENIED でまるごと保存されず、エラーは userErrors ではなくトップレベル errors に出る。 エラー処理の見直しとスタッフ権限の付与、この2点で対応完了。」 source : shopify.dev / changelog / draft-order-discount-permission 公開日 2026-11-18(Developer Changelog)