Admin GraphQL API / 権限変更

下書き注文に割引を「追加」するには
スタッフの割引権限が必須に

draftOrderCreate / draftOrderUpdate をスタッフとして実行するアプリが、apply_discounts_to_draft_orders 権限の無いスタッフで割引を追加しようとすると ACCESS_DENIED。下書き注文は保存されず、エラーは userErrors ではなく トップレベル errors に返る。全サポート対象 API バージョンで適用。

このページの構成
  1. そもそも何が変わるのか(30秒で理解)
  2. 仕組み図解 : リクエストが拒否されるまで
  3. 「割引の追加」と判定される操作/されない操作
  4. エラーの返り方(リクエスト例とレスポンス例)
  5. 影響を受けるアプリ/受けないアプリ
  6. 対応手順(3ステップ)
  7. 技術者が押さえるべき5つのポイント
  8. 業務に活かせる3つのユースケース
  9. 提案で使える1行サマリ

1そもそも何が変わるのか

スタッフとして動くアプリが下書き注文に割引を新しく追加しようとしたとき、そのスタッフが apply_discounts_to_draft_orders 権限を持っていなければ、ミューテーション全体が ACCESS_DENIED で拒否される。
下書き注文は保存されず、ペイロードは null。エラーは userErrors には出ない。

権限なしスタッフ + 割引の追加

トップレベル errors に ACCESS_DENIED。data.draftOrderUpdate(または draftOrderCreate)は null。変更は一切保存されない。

既存割引の維持・削除

下書き注文の既存割引をそのまま残す、または外す操作はこれまで通り動く。拒否されるのは「追加」だけ。

2仕組み図解 : リクエストが拒否されるまで

アプリ スタッフとして実行 draftOrderCreate/Update 割引を 追加する? いいえ(維持・削除のみ) はい スタッフに apply_discounts_ to_draft_orders? あり なし ACCESS_DENIED トップレベル errors に格納 payload = null 下書き注文は保存されない これまで通り処理 失敗時は従来どおり userErrors
判定は「スタッフとして動いているリクエストかどうか」が前提。offline アクセストークンでのリクエストなど、スタッフとして動かないリクエストはこのチェックの対象外。

3「割引の追加」と判定される操作/されない操作

操作(DraftOrderInput)draftOrderUpdatedraftOrderCreate
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つのポイント

null

1. userErrors 依存のハンドリングは壊れる

失敗判定を userErrors.length だけで行うと、ペイロード null で例外になるか「成功」と誤判定する恐れがある。記事は エラー処理の更新が必要と明記。

ALL ver.

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点で対応完了。」