ce-orders

LLM 文档标头：所有发送到 https://llm-docs.commercengine.io 的请求都必须包含 Accept: text/markdown 标头（或在 URL 路径末尾添加 .md）。否则，响应将返回 HTML，而不是可解析的 Markdown。

订单管理

前置条件：创建订单需要购物车中包含商品和地址。请参阅 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
});

常见问题

级别	问题	解决方案
严重	创建订单时未设置地址	调用 createOrder() 前，购物车必须设置账单／配送地址
高	未轮询支付状态	网关重定向后，始终轮询 getPaymentStatus()
高	不允许取消时仍显示取消按钮	先检查订单详情中的 is_cancellation_allowed
中	未处理多笔配送	一个订单可能包含多笔配送 — 遍历 data.shipments
中	缺少 return_url	必须提供 return_url，以便支付网关回调
中	在店面构建退货流程	退货由管理员处理。店面仅支持取消（cancelOrder）。显示订单／退款状态，而不是“申请退货”表单。
低	未按状态筛选订单	使用 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