fulfillmentOrderReportProgress 3PL・配送アプリが「作業始めました」をマーチャントに返せる

図解 ： fulfillmentOrderReportProgress mutation（フルフィルメント進捗の報告） Admin GraphQL API / 新ミューテーション fulfillmentOrderReportProgress 3PL・配送アプリが「作業始めました」をマーチャントに返せる API バージョン 2026-04 から、3PL や配送アプリが fulfillmentOrderReportProgress でフルフィルメント注文の進捗を報告できる。「着手した」ことを伝え、任意で短いステータスメモを添えられる。マーチャントは配送パイプラインの状況が見えるようになる。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： mutation を呼んでからの流れ 管理タイプ別の利用条件（3PL管理 vs マーチャント管理） 新しい2つの Webhook reasonNotes と supportedActions 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか これまでフルフィルメント注文は「未着手」か「完了」かが中心で、 「いま作業中です」を構造化して報告する手段がなかった 。 新しい fulfillmentOrderReportProgress mutation で、3PL や配送アプリが「着手した」ことを Shopify に通知でき、マーチャント側からその進捗が見えるようになる。 従来 ： 進捗は「ブラックボックス」 注文を渡したあと、3PL が実際に作業を始めたのか、まだ手付かずなのかをマーチャントが API 経由で知る標準手段がなかった。 新方式 ： 「着手」を構造化して報告 配送側が mutation で進捗を報告 → ステータスが更新され、webhook が発火。任意のメモ（reasonNotes）も添えられる。 2 仕組み図解 ： mutation を呼んでからの流れ 進捗報告が可能な状態になると、 fulfillmentOrder.supportedActions が REPORT_PROGRESS アクションを返すようになる。 アプリ側は「いまこの注文は進捗報告できるか」をこのフィールドで判定できる。 3 管理タイプ別の利用条件 報告できる前提ステータスは、その注文が「3PL 管理」か「マーチャント管理」かで異なる。 項目 3PL 管理のフルフィルメント注文 マーチャント管理のフルフィルメント注文 報告できるステータス IN_PROGRESS OPEN または IN_PROGRESS 必要なスコープ 記載なし（フルフィルメントサービス向け） write_merchant_managed_fulfillment_orders reasonNotes 任意 最大 256 文字の補足メモを添付可能 3PL 管理 ： 着手後に報告 既にフルフィルメントサービスへ引き渡され作業が走っている（IN_PROGRESS）注文に対して進捗を返す想定。 マーチャント管理 ： OPEN からも可 まだ OPEN の段階でも報告でき、IN_PROGRESS に遷移させられる。ただし書き込みスコープが必要。 4 新しい2つの Webhook Topic fulfillment_orders/progress_reported フルフィルメント注文に進捗が報告されたときに発火する。 ペイロードに含まれるもの ： フルフィルメント注文の ID と status 更新前のステータス initial_status progress_report の詳細（ reason_notes 、および報告したアプリ／ユーザーの attribution data ） Topic fulfillment_orders/manually_reported_progress_stopped 進捗を手動報告した（ fulfillmentOrderReportProgress 経由の） マーチャント管理 のフルフィルメント注文が、その後「fulfillment 準備完了（ready for fulfillment）」とマークされ、 IN_PROGRESS から OPEN に戻った ときに発火する。 ＝ マーチャントが、前に報告した「作業中」状態を「取り消した／キャンセルした」ことをアプリが検知できる。 2つは対になる ： 片方が「進捗が報告された」、もう片方が「報告された進捗が取り消された（OPEN に戻った）」。両方を購読すると、in-progress 状態の付与と解除を双方向で追える。 5 reasonNotes と supportedActions reasonNotes（最大256文字・任意） 「ピッキング開始」「在庫待ち」など、状況を表す短いメモを添えられる。マーチャントが配送パイプラインの今を把握する手がかりになる。webhook の reason_notes にも反映される。 supportedActions に REPORT_PROGRESS 進捗報告が可能な注文では fulfillmentOrder.supportedActions が REPORT_PROGRESS を返す。事前にこのアクションの有無を確認してから mutation を投げれば、無駄なエラーを避けられる。 6 技術者が押さえるべき5つのポイント 1. API バージョン 2026-04 から この mutation・webhook・ REPORT_PROGRESS アクションは API バージョン 2026-04 以降で利用可能。古いバージョンを叩いているアプリは更新が必要。 2. 前提ステータスは管理タイプ次第 3PL 管理は IN_PROGRESS のみ、マーチャント管理は OPEN ／ IN_PROGRESS の両方。送る前に対象注文のタイプとステータスを確認する。 3. マーチャント管理は書き込みスコープ必須 マーチャント管理注文に報告するには write_merchant_managed_fulfillment_orders スコープが要る。OAuth のスコープ設定を見直すこと。 4. webhook は「報告」と「取り消し」の対 progress_reported で着手を、 manually_reported_progress_stopped で OPEN への巻き戻しを検知。後者はマーチャント管理注文が「準備完了」に戻された時のみ。 5. attribution data で「誰が報告したか」が残る progress_reported webhook のペイロードには、報告したアプリ／ユーザーの attribution data と initial_status （更新前ステータス）が含まれる。 監査ログや「どの 3PL がいつ着手したか」の追跡 に使える。複数の配送アプリが共存する環境で特に有用。 進捗ステータスの完了処理（fulfillment 確定）や、エラー時の挙動など mutation の詳細仕様は本記事に記載なし。実装前に対象 API バージョンのリファレンスで確認すること。 7 業務に活かせる3つのユースケース USE CASE 1 3PL 連携の「いま作業中」をマーチャント管理画面に可視化 課題 外部倉庫に注文を渡したあと、実際にピッキングが始まったのかが見えず、問い合わせ対応が後手に回る。 打ち手 3PL アプリが着手時に fulfillmentOrderReportProgress を発行 → reasonNotes に「ピッキング開始」等を添える。 効果 マーチャントが配送パイプラインの状態をリアルタイムに把握でき、CS の遅延問い合わせを削減。 技術メモ 送信前に supportedActions に REPORT_PROGRESS があるか確認してから叩く。 USE CASE 2 進捗イベントを外部 OMS / Slack に流す通知パイプライン 課題 フルフィルメントの着手・巻き戻しを、社内の OMS や Slack で即時に共有したいが標準イベントがなかった。 打ち手 fulfillment_orders/progress_reported と manually_reported_progress_stopped を購読し、受信を起点に通知を発火。 効果 「着手」と「取り消し（OPEN 復帰）」を双方向で検知し、運用チームの状況認識を統一。 技術メモ ペイロードの initial_status と progress_report を使い、状態遷移とメモを通知本文に整形する。 USE CASE 3 複数 3PL 環境での「誰がいつ着手したか」監査トレイル 課題 複数の配送アプリ／倉庫が同居する環境で、各注文をどのサービスがいつ処理開始したかの記録が散逸。 打ち手 progress_reported webhook の attribution data（報告元アプリ／ユーザー）と時刻を保存し、注文単位の進捗ログを構築。 効果 SLA 遵守の検証、ベンダー別パフォーマンス比較、トラブル時の原因切り分けが容易に。 技術メモ attribution data と reason_notes を注文 ID に紐づけて時系列保存。完了系イベントと突き合わせると着手→完了のリードタイムも算出可能。 8 提案で使える1行サマリ 「3PL・配送アプリが 『作業を始めました』をマーチャントに構造化して返せる 新ミューテーション（API 2026-04〜）。 任意メモ付きで着手を報告、専用 webhook で着手と取り消しを双方向に検知。 配送パイプラインの可視化・通知連携・監査トレイルに使える。」 source ： shopify.dev / changelog / fulfillmentOrderReportProgress published 2026-04-01