order-processing-pipeline

注文処理パイプライン

概要

すべての EC 注文には、注文受付 → 決済確認 → フルフィルメント開始 → 発送 → 配達というライフサイクルがあります。Shopify、WooCommerce、BigCommerce はそれぞれ、各段階の移行時に Webhook イベントを発生させる、組み込みの注文ステータスシステムとしてこれを実装しています。各移行を正しく設定し、3PL またはフルフィルメントシステムを適切な Webhook に接続し、各段階で副次的な処理（注文確認メール、在庫の引き当て、追跡通知）を自動化することが目標です。

カスタムのステートマシンコードが必要なのは、ヘッドレスストアフロントや、プラットフォームではネイティブに対応できない複雑な複数ステップの B2B ワークフローに限られます。

このスキルを使用する状況

• 注文ステータスに不整合が生じる場合（例：フルフィルメント済みの注文が保留中と表示される）
• 3PL またはフルフィルメントプロバイダーへの注文振り分けを自動化する場合
• ERP、配送、返品との連携用に注文ステータスの Webhook を追加する場合
• カスタムのヘッドレス注文管理システムを構築する場合

主な手順

ステップ 1：プラットフォームの注文ステータスと移行を把握する

プラットフォーム	注文ステータス	移行の仕組み
Shopify	オープン → 一部フルフィルメント済み → フルフィルメント済み → キャンセル済み。決済ステータス：保留中 → 承認済み → 支払い済み → 返金済み	Shopify Admin と Webhook。Shopify Payments とフルフィルメントアプリによる自動化
WooCommerce	保留中 → 処理中 → 保留 → 完了 → キャンセル済み → 返金済み → 失敗	WooCommerce のステータスシステム。管理画面、プラグイン、または wc_update_order_status() による移行
BigCommerce	保留中 → 支払い待ち → フルフィルメント待ち → 発送待ち → 発送済み → 完了、その他	BigCommerce Admin と Orders API の Webhook
カスタム／ヘッドレス	独自のステートマシンを定義	明示的な移行検証を使用して構築

ステップ 2：注文処理の自動化を設定する

---

Shopify

決済 → 注文確認のフローを設定する：

1. Shopify Payments が請求を確認すると、Shopify は注文を オープン から 支払い済み に自動的に移行します
2. Settings → Notifications に移動し、Order confirmation メールが有効になっていることを確認します。このメールは決済時に自動送信されます
3. Shopify 以外の決済方法を使用する場合は、ゲートウェイから Shopify に決済成功シグナルが送信されることを確認します。決済後も注文が Pending payment のままの場合は、ゲートウェイの設定を確認してください

デジタル商品向けの自動フルフィルメントを設定する：

1. Settings → Shipping and delivery → Fulfillment に移動します
2. デジタル商品の場合は、Automatically fulfill the digital items in the order を有効にします

3PL またはフルフィルメントセンターを接続する：

1. Shopify App Store からフルフィルメントプロバイダーの Shopify アプリ（ShipBob、ShipHero、Whiplash、Amazon FBA など）をインストールします
2. Settings → Shipping and delivery → Fulfillment services に移動し、サービスを追加します
3. アプリは Shopify の Order created または Order paid Webhook を購読し、新しい注文を自動的に受信します
4. 3PL が注文を発送すると、Fulfillment API を介して追跡番号が Shopify に返送されます。これにより注文が Fulfilled に更新され、発送確認メールが自動送信されます

手動フルフィルメントのワークフロー：

1. Orders → Unfulfilled タブに移動し、フルフィルメント待ちの注文をすべて確認します
2. 注文をクリックし、発送後に Mark as fulfilled を選択して、追跡番号を入力します
3. 注文がフルフィルメント済みとしてマークされると、顧客に追跡情報メールが自動送信されます

外部システム（ERP など）向けの注文 Webhook を設定する：

1. Settings → Notifications → Webhooks に移動します（またはアプリレベルの Webhook には Partner Dashboard を使用します）
2. 次の Webhook を追加します：Order creation、Order payment、Order fulfillment、Order cancellation
3. 各 Webhook は、処理用に注文の完全な JSON をエンドポイントに送信します

WooCommerce

デフォルトの注文フローを理解する：

• Pending payment → 顧客が注文しましたが、まだ支払いは完了していません
• Processing → 支払いが完了し、注文の準備中です（支払い済みの注文のデフォルト）
• Completed → 注文が配送済みです。手動で設定するか、配送プラグインによって自動設定されます
• On hold → 支払いが不確定です（例：銀行振込の確認待ち）

ステータスの自動遷移を設定する：

1. 支払い方法ごとに WooCommerce → Settings → Payments → [Gateway] → Order status に移動し、支払い完了時のステータスを設定します（通常、即時決済の方法では「Processing」です）
2. バーチャル商品／ダウンロード商品を含む注文の場合は、WooCommerce → Settings → Products → Downloadable products に移動し、「Grant access to downloadable products after payment」を設定すると、注文が自動的に「Completed」に変更されます

配送／フルフィルメントプラグインを接続する：

1. 配送プラグインをインストールします：WooCommerce ShipStation、WooCommerce ShipBob、または ELEX WooCommerce DHL/FedEx/UPS
2. プラグインを設定して、「Processing」ステータスの注文をフルフィルメント用に取得します
3. プラグインが注文を発送し、追跡番号を取得すると、注文ステータスを「Completed」に更新し、追跡情報のメールを自動送信します

フックによるカスタムステータス遷移：

// In functions.php or a custom plugin — auto-complete virtual orders
add_action('woocommerce_payment_complete', 'auto_complete_virtual_orders');
function auto_complete_virtual_orders($order_id) {
    $order = wc_get_order($order_id);
    if ($order && $order->get_status() === 'processing') {
        $all_virtual = true;
        foreach ($order->get_items() as $item) {
            $product = $item->get_product();
            if (!$product->is_virtual()) { $all_virtual = false; break; }
        }
        if ($all_virtual) {
            $order->update_status('completed', 'All virtual items — auto-completed.');
        }
    }
}

注文のWebhook： WooCommerce Webhooks（組み込み）をインストールし、WooCommerce → Settings → Advanced → Webhooks に移動して、注文の作成、更新、削除イベント用のWebhookを追加します。

BigCommerce

注文ステータスのフローを設定する：

1. Orders → View に移動します。支払いが確認されると、BigCommerceは注文を自動的に Awaiting Fulfillment に設定します
2. 決済ゲートウェイの注文ステータスマッピングを設定します。Settings → Payment Methods → [Gateway] に移動し、支払い後のステータスを設定します

フルフィルメントプロバイダーを接続する：

1. BigCommerce App Marketplace に移動し、フルフィルメントセンターのアプリ（ShipBob、ShipStation など）をインストールします
2. アプリはBigCommerceの注文Webhookに接続し、新しい注文を自動的に取得します
3. 3PLが発送すると、Orders API経由でBigCommerceを更新し、追跡番号を設定してステータスを Shipped に変更します

注文のWebhook： Settings → Advanced Settings → WebHooks に移動し、注文ステータス変更用のWebhookを追加します。これらはERPや会計システムなどの連携で使用されます。

---

カスタム／ヘッドレス

カスタムストアフロントでは、遷移の検証を明示的に行うステートマシンを実装します：

// Valid order state transitions
const VALID_TRANSITIONS = {
  pending:    ['confirmed', 'cancelled'],
  confirmed:  ['processing', 'cancelled'],
  processing: ['shipped', 'cancelled'],
  shipped:    ['delivered', 'returned'],
  delivered:  ['returned', 'refunded'],
  cancelled:  ['refunded'],
};

async function transitionOrder(orderId, newStatus, metadata = {}) {
  return db.$transaction(async (tx) => {
    const order = await tx.orders.findUnique({ where: { id: orderId } });

    if (!VALID_TRANSITIONS[order.status]?.includes(newStatus)) {
      throw new Error(`Invalid transition: ${order.status} → ${newStatus}`);
    }

    const updated = await tx.orders.update({
      where: { id: orderId },
      data: { status: newStatus, [`${newStatus}At`]: new Date() },
    });

    // Append-only event log for audit trail
    await tx.orderEvents.create({
      data: { orderId, fromStatus: order.status, toStatus: newStatus, triggeredBy: metadata.triggeredBy ?? 'system' },
    });

    return updated;
  });
}

// Wire to Stripe webhook — payment confirmation drives the transition
async function onPaymentSucceeded(paymentIntent) {
  const orderId = paymentIntent.metadata.order_id;
  const order = await db.orders.findUnique({ where: { id: orderId } });

  // Idempotency — ignore if already confirmed
  if (order.status !== 'pending') return;

  await transitionOrder(orderId, 'confirmed', { triggeredBy: 'stripe_webhook' });
  await sendOrderConfirmationEmail(orderId);
  await deductInventory(orderId);
}

各遷移での副作用（ブロックを避けるため、DBトランザクションの外で実行します）：

• confirmed：確認メールを送信し、在庫を差し引き、フルフィルメントプロバイダーに通知します
• shipped：追跡番号を記載した発送メールを送信し、顧客ポータルの追跡情報を更新します
• delivered：配達完了通知を送信し、レビュー依頼を予約します（3日後）
• cancelled：在庫引当を解除し、支払い済みの場合は返金を開始して、キャンセルメールを送信します

ステップ 3：よくあるエッジケースに対処する

Webhookの重複配信： 主要な決済処理サービスはいずれも、同じWebhookを複数回配信する可能性があります。遷移を処理する前に、必ず現在の注文ステータスを確認してください：

if (order.status !== 'pending') return; // Already processed

在庫を差し引くタイミング： 在庫を差し引くのは、注文時ではなく、支払いが確認された後（confirmed 遷移時）のみにしてください。支払いに失敗した場合、在庫を無期限に引き当てたくはないはずです。

一部フルフィルメント後の注文キャンセル： 一部の商品は発送済みで、残りは未発送の場合、プラットフォームによって対応が異なります。Shopifyでは、フルフィルメント済みの商品を維持したまま、未フルフィルメントの明細項目を一部キャンセルできます。WooCommerceでは、WooCommerce Cancel Abandoned Order をインストールするか、WooCommerce REST APIで管理します。

ベストプラクティス

• プラットフォーム標準の注文管理を利用する — Shopify、WooCommerce、BigCommerce は、決済 → フルフィルメント → 配送という主要なフローを正しく処理します。置き換えるのではなく、その上に構築してください
• フルフィルメントアプリを適切なステータストリガーに接続する — フルフィルメントプロバイダーには、注文作成時ではなく、決済確認時（Shopify では order.paid、WooCommerce では Processing）に注文を送信してください
• すべてのステータス遷移を記録する — プラットフォームを利用している場合でも、監査目的で注文メモ（Shopify と WooCommerce はどちらも対応しています）を追加するか、データベースイベントを記録してください
• Webhook の冪等性を処理する — Webhook をトリガーとする遷移を適用する前に、必ず現在の注文ステータスを確認してください
• 外部連携向けに Webhook を送信する — すべての注文ステータス変更に対して Webhook を設定し、ERP、会計、CRM との連携を同期させてください

よくある落とし穴

問題	解決策
Webhook の重複により、Shopify で注文が二重に確定される	Shopify は冪等性ヘッダーで重複を排除します。処理する前に、こちら側でも order.financial_status !== 'paid' を確認してください
PayPal で決済した後も、WooCommerce の注文が「Pending payment」のままになる	PayPal アカウントで PayPal IPN（Instant Payment Notification）を有効にする必要があります。WooCommerce → Settings → Payments → PayPal で IPN URL を確認してください
注文を手動で完了するまで在庫が差し引かれない	在庫の差し引きをフルフィルメント Webhook ではなく、決済確認 Webhook に移してください
3PL が新しい注文を自動で受信しない	フルフィルメントアプリが正しい注文ステータスを購読していることを確認してください。多くの 3PL アプリは「Processing」（WooCommerce）または「Unfulfilled + Paid」（Shopify）の注文を取得します
注文ステータスの Webhook が発火しない	Shopify → Settings → Notifications → Webhooks または WooCommerce → Settings → Advanced → Webhooks で Webhook の登録を確認し、エンドポイントが 200 を返していることを確認してください

関連スキル

• @stripe-integration
• @inventory-tracking
• @subscription-billing
• @guest-checkout