Shopify注文の編集APIガイド：安全な開始から確定までのフローを構築する

APIを3段階で使う理由#

注文の編集は、単一の更新ではなく一連の処理です。 Shopifyは注文の計算済みバージョンを作成します。アプリはそこに変更を仮適用し、確定時にその内容を注文へ反映します。

Revizeを利用するストアの1,000万件以上の注文では、約19件に1件、つまり5.2%の注文がチェックアウト後に編集されました（Revize, 2026）。この件数を踏まえると、注文の編集は例外的なサポート対応ではなく、日常の業務フローとして設計する必要があります。

CalculatedOrderは、倉庫のピッキングリストの校正刷りのようなものです。明細を追加・削除し、結果を確認してから、最終版を反映できます。

API呼び出しの正しさと同じくらい、タイミングも重要です。Revizeを利用するストアでは、編集が行われる時点の中央値はチェックアウトから4.6分後です（Revize, 2026）。その間にピッキングが始まると、コードが技術的に正しくても、誤った商品を発送しかねません。

Shopify注文の編集APIの仕組み#

Shopify Admin API 2026-07では、orderEditBegin、1回以上の変更の仮適用、orderEditCommitの順に処理します。 Shopifyのミューテーションリファレンスでは、仮適用と確定に計算済み注文IDまたは注文編集セッションIDのどちらも使用できます。このガイドでは一貫してcalculatedOrder.idを使用します。

1. Shopifyの注文IDを指定してorderEditBeginを呼び出します。
2. calculatedOrder.idを$calculatedOrderIdとして保存します。
3. そのIDを使って各ミューテーションで変更を仮適用します。
4. 計算済みの明細、合計金額、すべてのuserErrors配列を確認します。
5. 同じIDをorderEditCommitに渡します。

Shopifyは、この開始、仮適用、確定のモデルを文書化しています。アプリにはwrite_order_editsのアクセススコープが必要です。

最小限の開始ミューテーションでも、診断用に両方のオブジェクトを取得し、その後の処理に使うIDを1つ選べます。

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

userErrorsが空でなければ処理を止めてください。ネットワークリクエストの成功が示すのは、Shopifyがリクエストを受信したことだけです。操作が受け入れられたことまでは示しません。

バージョン別の編集ガイドには、バリエーション、数量、カスタム商品、明細単位のディスカウント、配送明細に対する変更の仮適用が記載されています。実装前とAPIバージョンの変更前に、該当する2026-07のミューテーションリファレンスを確認してください。

バリエーションの変更を最後まで実装する方法#

バリエーションの変更では、1つの編集セッション内で代替品を追加し、元の計算済み明細の数量をゼロにします。 両方の操作が成功し、計算結果が顧客の確認した内容と一致してから確定してください。

たとえば、顧客が注文したMサイズをLサイズに変更する場合です。

1. 編集を開始し、calculatedOrder.idを保存します。
2. そのIDを使ってLサイズのバリエーションを追加します。

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. 計算済み注文の中から元のMサイズを探します。返された計算済みの状態を確認せずに、元の注文の明細IDをそのまま使わず、計算済み明細のIDを使用してください。

4. 元の明細の数量をゼロにします。

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. 計算済み注文を再取得します。代替品が含まれること、元の商品の数量がゼロであること、合計金額が顧客の確認内容と一致することを確かめます。
6. 同じ計算済み注文IDを使って確定します。

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

注意： 代替品の追加が成功しても、元の商品を削除する前に確定しないでください。変更のつもりが、商品を1点追加した注文になってしまいます。

確認ボタンの重複クリックを拒否し、完了した段階を記録してください。別の処理が注文を変更した可能性がある場合は、確定前に再取得します。

編集内容ごとに使うミューテーション#

明細、数量、ディスカウント、配送明細の変更には、計算済み注文のフローを使用します。 orderUpdate、キャンセル、返金のミューテーションは、各バージョンのリファレンスに記載された用途に使用してください。

2026-07のorderUpdateリファレンスは、顧客のメールアドレス、配送先住所、タグ、メタフィールドなどの属性を対象とし、例の中でメモの更新も説明しています。明細の追加・削除、数量の変更、ディスカウントの変更といった大きな変更には、orderEditBeginを使用するよう案内しています。

Shopifyの注文編集に関する考慮事項によると、ディスカウントコード、自動ディスカウント、スクリプトディスカウントは編集できません。注文単位のディスカウントも追加、削除、変更できません。明細単位のディスカウント用ミューテーションがあっても、これらの制限は変わりません。

Shopify注文の編集APIでできることの限界#

編集の確定と決済・返金の処理は、別々に確認する必要があります。 Shopifyは、編集によって合計金額が変わると、顧客に差額の支払いまたは返金が必要になる場合があると説明しています。

合計金額が増えた場合は、確定後の注文を再取得し、差額をどう回収するか確認してからフルフィルメントに進めてください。orderEditCommitの成功応答だけで、支払いが完了したと判断してはいけません。

合計金額が減った場合も、確定だけで返金処理が済むわけではありません。返金予定額を計算し、適切な返金操作を呼び出して応答を確認します。差額がゼロなら追加の支払いや返金は不要ですが、最終的な注文の状態は確認してください。

Shopifyのorders/editedWebhookを購読し、後続システムが処理する前に注文を再取得します。Webhookは現在のレコードを読み直す合図です。以前保存したローカルの内容をそのまま信用する根拠にはなりません。

編集や支払いの状態が未確定の注文を、外部物流業者（3PL）にピッキングさせないでください。実際に注文を取り込む倉庫システムに対して、保留、支払い状況のルール、または処理開始の合図をテストします。

編集エラーの調査方法#

まず編集可能かどうか、ID、入力値の検証、同時に行われた変更を確認します。 顧客情報や決済上の機密情報を記録せず、ミューテーション名、Shopify注文ID、選択した編集ID、userErrors配列全体をログに残します。

Shopifyの注文編集の要件によると、アプリにはwrite_order_editsが必要です。編集できるのは未フルフィルメントの明細だけで、アーカイブ済みの注文や2019年1月1日より前に行われた注文は編集できません。アプリが標準でアクセスできる注文は過去60日分です。それより古い注文の照会にはread_all_ordersが必要です。

これらは別々のルールです。read_all_ordersによって古い注文を参照できるようになっても、アーカイブ済みの注文や2019年より前の注文を編集できるようにはなりません。

推測したエラー文字列を前提にアプリの動作を決めないでください。該当リクエストで返されたフィールドとメッセージを読み、管理されたテスト注文でエラーを再現します。

Revizeを使うか、APIから開発するか#

フルフィルメント前に顧客自身で注文を編集できるようにするなら、Revizeが有力な選択肢です。独自の社内処理を組み立てるなら、カスタムコードが適しています。 判断のポイントは、顧客向けの一連の操作を利用するか、画面、状態の遷移、倉庫への誤送信を防ぐ仕組みをすべて自社で管理するかです。

独自のスタッフ向け管理画面や、社内システムをまたぐ承認プロセスが必要な場合、カスタムコードには明確な役割があります。Revizeは汎用の注文編集APIやマーチャント向けの承認キューを提供していません。

制作会社は、文書化されたShopify FlowトリガーをRevizeの編集イベントに接続したり、Revizeの編集タグと解除タグをフルフィルメントのロジックで使ったりできます。外部のキャンセル画面にはPublic Cancellation APIも使用できます。Public Cancellation APIはPro限定で、サポートによる有効化が必要です。また、ポータルの編集可能期間、制限、返金ポリシーが適用されます。

Revizeを利用するストアで購入後に編集された注文のうち、92.2%はサポート担当者を介さず顧客が完了しました（Revize, 2026）。制作会社向けの購入後注文編集ガイドでは、実装前に確認すべき事項を説明しています。

利用できる機能はプランによって異なります。商品の追加と変更、ストアクレジットによる返金、ディスカウント・配送・税金の再計算、ルールエンジン、Reverse Unpaid Edits、Public Cancellation APIはPro限定です。詳しくはRevizeの請求に関するドキュメントをご覧ください。

社内向けの編集画面をもう1つ作るのではなく、顧客が自分で操作できる仕組みを導入したい場合は、Revize: Order Editing & Upsellをインストールしてください。

Revizeが処理を完了するまで#

Revizeは、Shopifyの注文状況ページで、顧客が設定された範囲内で注文を編集できるフローを提供します。 マーチャントは編集可能期間、利用できる操作、返金ポリシー、注文処理モードを設定します。

編集によって合計金額が増えると、RevizeはPay nowを表示し、差額の支払いだけを行うために顧客をShopifyのチェックアウトへ移動させます。金額が減るとRefund、変わらなければConfirmが表示されます。Revizeの顧客向けワークフローに記載されているとおり、支払いや返金はShopifyが実行します。

マーチャントはOrder Editing > Order edit windowで期間を設定します。編集可能期間の設定ガイドには、所定の期間、任意の期間、予定された締め切り、フルフィルメントまでのモードが記載されています。フルフィルメントまでのモードだけでは、注文は自動的に保留されません。

推奨の処理モードでは、Revizeが編集可能期間中にShopifyのフルフィルメントを保留し、編集終了時に解除します。保留を無視するシステムでは、文書化された決済の手動確定への切り替えが必要になる場合があります。また、解除タグを合図として、そのタグを待つよう設定したフルフィルメントシステムに処理を進めさせることもできます。

Revizeは顧客によるバリエーションの変更を許可する前に、配送地域を考慮した最新の在庫を確認します。フルフィルメント保留のガイドでは、倉庫側のフローを説明しています。

今週テストすること#

チェックアウトから修正後のフルフィルメントまで、失敗するケースも含めて1件の注文をテストしてください。 GraphQLクライアントでミューテーションが成功するのは、最初の確認項目にすぎません。

1. 実際の運用を想定した開発用注文または下書き注文を作成します。
2. 差額のない変更、金額が増える変更、金額が減る変更をテストします。
3. 開始、各変更の仮適用、確定の後にuserErrorsを確認します。
4. 確定前に計算済み注文を確認します。
5. 差額の回収と返金の処理を別々に検証します。
6. 編集後の注文を実際のフルフィルメントシステムに流します。
7. アーカイブ済みの注文、古い注文、操作の重複、編集途中での離脱をテストします。
8. 本番環境でアクセスを有効にする前に、Shopify標準の注文編集の制限を確認します。