ce-orders

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LLM Docs Header: All requests to
https://llm-docs.commercengine.io
must include the
Accept: text/markdown
header (or append
.md
to the URL path). Without it, responses return HTML instead of parseable markdown.

LLM文档提示: 所有发往
https://llm-docs.commercengine.io
的请求必须携带
Accept: text/markdown
请求头（或者在URL路径末尾追加
.md
）。如果没有该头，接口会返回HTML而非可解析的markdown格式。

Order Management

订单管理

Prerequisite: Order creation requires a cart with items and addresses. See
cart-checkout/
.

前置条件: 创建订单需要包含商品和地址的购物车。参见
cart-checkout/
。

Quick Reference

快速参考

Task	SDK Method
Create order	`sdk.order.createOrder({ cart_id, payment_method? })`
List orders	`sdk.order.listOrders({ page, limit })`
Get order detail	`sdk.order.getOrderDetails({ order_number })`
Get shipments	`sdk.order.listOrderShipments({ order_number })`
Get payments	`sdk.order.listOrderPayments({ order_number })`
Payment status	`sdk.order.getPaymentStatus(orderNumber)` — takes a string
Retry payment	`sdk.order.retryOrderPayment({ order_number }, { payment_method })`
Cancel order	`sdk.order.cancelOrder({ order_number }, { cancellation_reason, refund_mode })`
Get refunds	`sdk.order.listOrderRefunds({ order_number })`

Note: Returns are managed by the brand admin (Admin Portal), not the storefront. Customers can cancel within the cancellation window (
is_cancellation_allowed
); the admin then decides whether to schedule a return shipment or issue a direct refund. The default behavior is to refund if cancelled within the window. Return/replacement request APIs for storefront are under development.

任务	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)` — 接收字符串类型参数
重试支付	`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正在开发中。

Decision Tree

决策流程

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 }, { ... })

User Request
    │
    ├─ "下单" / "结算"
    │   └─ sdk.order.createOrder() → 处理payment_info
    │       → 完整结算流程参见cart-checkout/
    │
    ├─ "我的订单" / "订单历史"
    │   └─ sdk.order.listOrders({ page, limit })
    │
    ├─ "订单详情" / "订单#123"
    │   └─ sdk.order.getOrderDetails({ order_number })
    │
    ├─ "跟踪物流"
    │   └─ sdk.order.listOrderShipments({ order_number })
    │       → tracking_url, awb_no, status, eta_delivery
    │
    ├─ "支付失败" / "重试"
    │   ├─ 查询 → sdk.order.getPaymentStatus(orderNumber)
    │   └─ 重试 → sdk.order.retryOrderPayment({ order_number }, { payment_method })
    │
    └─ "取消订单"
        ├─ 先校验is_cancellation_allowed字段
        └─ sdk.order.cancelOrder({ order_number }, { ... })

Order Statuses

订单状态

Status	Description
`draft`	Order created, awaiting payment
`confirmed`	Payment successful, order confirmed
`processing`	Being prepared for shipment
`shipped`	In transit
`delivered`	Delivered to customer
`cancelled`	Order cancelled

状态	描述
`draft`	订单已创建，等待支付
`confirmed`	支付成功，订单已确认
`processing`	正在备货待发
`shipped`	运输中
`delivered`	已送达消费者
`cancelled`	订单已取消

Payment Statuses

支付状态

Status	Description	Action
`pending`	Payment not yet processed	Poll again after delay
`success`	Payment successful	Show confirmation
`failed`	Payment failed	Check `is_retry_available`

状态	描述	操作建议
`pending`	支付尚未处理	延迟后再次轮询
`success`	支付成功	展示确认信息
`failed`	支付失败	检查 `is_retry_available` 判断是否可重试

Key Patterns

核心使用模式

Create Order from Cart

从购物车创建订单

See
cart-checkout/references/payment-patterns.md
§ "Building Payment Payloads" for all payment_method shapes.

typescript

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
}

参见
cart-checkout/references/payment-patterns.md
§ 「构建支付载荷」了解所有
payment_method
的结构定义。

typescript

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) {
  // 使用payment_info跳转或处理支付流程
}

List Orders with Filters

带筛选条件查询订单列表

typescript

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 }

typescript

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

// data.orders → OrderList[] (概览视图)
// data.pagination → { total_records, total_pages, next_page }

Poll Payment Status

轮询支付状态

typescript

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();
  }
}

typescript

async function pollPaymentStatus(orderNumber: string) {
  // 注意: getPaymentStatus接收字符串参数，而非对象
  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();
  }
}

Cancel Order

取消订单

typescript

// 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",
    }
  );
}

typescript

// 首先检查是否允许取消
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",
    }
  );
}

Shipment Tracking

物流跟踪

typescript

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
});

typescript

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

data.shipments.forEach((shipment) => {
  console.log(shipment.status);        // "shipped", "delivered"等
  console.log(shipment.tracking_url);  // 快递跟踪链接
  console.log(shipment.awb_no);        // 空运运单号
  console.log(shipment.eta_delivery);  // 预计送达日期
});

Common Pitfalls

常见注意事项

Level	Issue	Solution
CRITICAL	Creating order without address	Cart must have billing/shipping addresses set before `createOrder()`
HIGH	Not polling payment status	After gateway redirect, always poll `getPaymentStatus()`
HIGH	Showing cancel button when not allowed	Check `is_cancellation_allowed` from order detail first
MEDIUM	Not handling multiple shipments	One order can have multiple shipments — iterate `data.shipments`
MEDIUM	Missing `return_url`	Must provide `return_url` for payment gateway callback
MEDIUM	Building a returns flow on storefront	Returns are admin-managed. Storefront supports cancellation only ( `cancelOrder` ). Show order/refund status, not a "Request Return" form.
LOW	Not filtering orders by status	Use `status[]` query param to show relevant orders per tab

严重性	问题	解决方案
严重	创建订单时未设置地址	调用 `createOrder()` 前必须为购物车设置账单/收货地址
高	未轮询支付状态	从支付网关跳转回来后，务必轮询 `getPaymentStatus()` 接口
高	不满足取消条件时展示取消按钮	先通过订单详情接口查询 `is_cancellation_allowed` 字段判断是否可取消
中	未处理多物流包裹场景	单个订单可能对应多个物流包裹，请遍历 `data.shipments` 字段
中	缺少 `return_url` 参数	必须提供 `return_url` 用于支付网关回调
中	在前端店铺实现退货流程	退货由管理员处理，前端店铺仅支持取消订单（ `cancelOrder` ）功能。仅展示订单/退款状态即可，不要提供「申请退货」表单
低	未按状态筛选订单	使用 `status[]` 查询参数按标签页展示对应状态的订单

另请参阅

```
cart-checkout/
```
- Cart management and checkout flow
```
webhooks/
```
- Real-time order status updates via webhooks

```
cart-checkout/
```
- 购物车管理和结算流程
```
webhooks/
```
- 通过webhook接收订单状态实时更新

Documentation

文档链接

Checkout Flow: https://www.commercengine.io/docs/storefront/checkout
My Account - Orders: https://www.commercengine.io/docs/storefront/my-account
API Reference: https://www.commercengine.io/docs/api-reference/orders
LLM Reference: https://llm-docs.commercengine.io/storefront/operations/create-order

结算流程: 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

ce-orders

Original

Translation

Order Management

订单管理

Quick Reference

快速参考

Decision Tree

决策流程

Order Statuses

订单状态

Payment Statuses

支付状态

Key Patterns

核心使用模式

Create Order from Cart

从购物车创建订单

List Orders with Filters

带筛选条件查询订单列表

Poll Payment Status

轮询支付状态

Cancel Order

取消订单

Shipment Tracking

物流跟踪

Common Pitfalls

常见注意事项

See Also

另请参阅

Documentation

文档链接