ce-orders

LLM ドキュメントのヘッダー：https://llm-docs.commercengine.io へのすべてのリクエストには、Accept: text/markdown ヘッダーを必ず含めてください（または URL パスに .md を追加してください）。含めない場合、解析可能な Markdown ではなく HTML が返されます。

注文管理

前提条件：注文を作成するには、商品と住所が設定されたカートが必要です。cart-checkout/ を参照してください。

クイックリファレンス

タスク	SDK メソッド
注文を作成	sdk.order.createOrder({ cart_id, payment_method? })
注文一覧を取得	sdk.order.listOrders({ page, limit })
注文詳細を取得	sdk.order.getOrderDetails({ order_number })
配送一覧を取得	sdk.order.listOrderShipments({ order_number })
支払い一覧を取得	sdk.order.listOrderPayments({ order_number })
支払いステータス	sdk.order.getPaymentStatus(orderNumber) — { order_number } ではなく、文字列を直接渡します
支払いを再試行	sdk.order.retryOrderPayment({ order_number }, { payment_method })
注文をキャンセル	sdk.order.cancelOrder({ order_number }, { cancellation_reason, refund_mode })
返金一覧を取得	sdk.order.listOrderRefunds({ order_number })

注：返品はストアフロントではなく、ブランド管理者（管理ポータル）が管理します。顧客はキャンセル可能期間内にキャンセルできます（is_cancellation_allowed）。その後、管理者が返品配送を手配するか、直接返金するかを決定します。期間内にキャンセルされた場合は、デフォルトで返金されます。ストアフロント向けの返品・交換リクエスト API は開発中です。

判断ツリー

User Request
    │
    ├─ "Place order" / "Checkout"
    │   └─ sdk.order.createOrder() → handle payment_info
    │       → See cart-checkout/ for full checkout flow
    │
    ├─ "My orders" / "Order history"
    │   └─ sdk.order.listOrders({ page, limit })
    │
    ├─ "Order detail" / "Order #123"
    │   └─ sdk.order.getOrderDetails({ order_number })
    │
    ├─ "Track shipment"
    │   └─ sdk.order.listOrderShipments({ order_number })
    │       → tracking_url, awb_no, status, eta_delivery
    │
    ├─ "Payment failed" / "Retry"
    │   ├─ Check → sdk.order.getPaymentStatus(orderNumber)
    │   └─ Retry → sdk.order.retryOrderPayment({ order_number }, { payment_method })
    │
    └─ "Cancel order"
        ├─ Check is_cancellation_allowed first
        └─ sdk.order.cancelOrder({ order_number }, { ... })

注文ステータス

ステータス	説明
draft	注文が作成され、支払い待ちです
confirmed	支払いが成功し、注文が確定しました
processing	発送の準備中です
shipped	配送中です
delivered	顧客に配達済みです
cancelled	注文がキャンセルされました

支払いステータス

ステータス	説明	対応
pending	支払いはまだ処理されていません	時間をおいて再度確認します
success	支払いが成功しました	確認メッセージを表示します
failed	支払いに失敗しました	is_retry_available を確認します

主なパターン

カートから注文を作成する

すべての payment_method の形式については、cart-checkout/references/payment-patterns.md §「支払いペイロードの構築」を参照してください。

const { data: order, error } = await sdk.order.createOrder({
  cart_id: cartId,
  payment_method: {
    payment_provider_slug: "juspay",
    integration_type: "hyper-checkout",
    gateway_reference_id: gatewayRefId,
    return_url: "https://yoursite.com/order/confirm",
    action: "paymentPage",
  },
});

if (order.payment_required) {
  // Use payment_info to redirect or handle payment flow
}

フィルターを使って注文一覧を取得する

const { data, error } = await sdk.order.listOrders({
  page: 1,
  limit: 10,
  sort_by: JSON.stringify({ order_date: "desc" }),
});

// data.orders → OrderList[] (summary view)
// data.pagination → { total_records, total_pages, next_page }

支払いステータスをポーリングする

async function pollPaymentStatus(orderNumber: string) {
  // Note: getPaymentStatus takes a string, not an object
  const { data, error } = await sdk.order.getPaymentStatus(orderNumber);

  if (data.status === "pending") {
    setTimeout(() => pollPaymentStatus(orderNumber), 3000);
    return;
  }

  if (data.status === "success") {
    showConfirmation(orderNumber);
  } else if (data.is_retry_available) {
    showRetryOption(orderNumber);
  } else {
    showPaymentFailed();
  }
}

注文をキャンセルする

// First check if cancellation is allowed
const { data: order } = await sdk.order.getOrderDetails({
  order_number: orderNumber,
});

if (order.is_cancellation_allowed) {
  const { data, error } = await sdk.order.cancelOrder(
    { order_number: orderNumber },
    {
      cancellation_reason: "Changed my mind",
      refund_mode: "original_payment_mode",
      feedback: "Optional feedback",
    }
  );
}

配送状況を追跡する

const { data, error } = await sdk.order.listOrderShipments({
  order_number: orderNumber,
});

data.shipments.forEach((shipment) => {
  console.log(shipment.status);        // "shipped", "delivered", etc.
  console.log(shipment.tracking_url);  // Courier tracking link
  console.log(shipment.awb_no);        // Air waybill number
  console.log(shipment.eta_delivery);  // Estimated delivery date
});

よくある落とし穴

重大度	問題	解決策
CRITICAL	住所を設定せずに注文を作成する	createOrder() を呼び出す前に、カートに請求先住所と配送先住所を設定する必要があります
HIGH	支払いステータスをポーリングしない	ゲートウェイからリダイレクトされた後、必ず getPaymentStatus() をポーリングします
HIGH	キャンセル不可の場合にキャンセルボタンを表示する	まず注文詳細から is_cancellation_allowed を確認します
MEDIUM	複数の配送を処理しない	1 つの注文に複数の配送が含まれる場合があります — data.shipments を反復処理します
MEDIUM	return_url が設定されていない	支払いゲートウェイのコールバックには return_url を指定する必要があります
MEDIUM	ストアフロントに返品フローを実装する	返品は管理者が管理します。ストアフロントで対応するのはキャンセルのみです（cancelOrder）。「返品をリクエスト」フォームではなく、注文・返金ステータスを表示します。
LOW	ステータスで注文をフィルタリングしない	タブごとに関連する注文を表示するには、status[] クエリパラメーターを使用します

関連項目

• cart-checkout/ - カート管理とチェックアウトフロー
• webhooks/ - Webhook によるリアルタイムの注文ステータス更新

ドキュメント

• チェックアウトフロー：https://www.commercengine.io/docs/storefront/checkout
• マイアカウント - 注文：https://www.commercengine.io/docs/storefront/my-account
• API リファレンス：https://www.commercengine.io/docs/api-reference/orders
• LLM リファレンス：https://llm-docs.commercengine.io/storefront/operations/create-order