管理订单
用 Open API 读取和管理店铺订单——查询列表、按订单查找、更新、取消。
适用场景
搭建订单管理面板、把订单同步到 ERP，或做一个对订单执行操作的客服工具。
前置需求
- 一个已跑通 OAuth 与 token 存储的公开应用——先完成 开发应用。下面的每个请求都带
Access-Token: {token}头，使用你为每个店铺保存的 token。 - OAuth 时已授予订单相关的 access scope。
查询订单列表
游标分页：传 per_page（最大 250），第一页之后再带上一页响应里的 cursor。
GET /openapi/2026-01/orders
响应（节选，列表在 data.data.orders 下，游标在 data.data.cursor 下）：
{
"code": "Success",
"data": {
"orders": [
{
"id": "2386979206089232618121",
"number": "VMT95165",
"total_price": "205.51",
"currency": "USD",
"financial_status": "refunded",
"status": "placed",
"fulfillment_status": "shipped",
"created_at": "2026-07-01T07:00:32Z",
"line_items": [
{
"id": "ee73a839-61a2-4504-b4b6-ea55f73f1340",
"product_id": "27e4f0cd-a115-475b-a3a8-ac9661ed4ccb",
"product_title": "Denim dress",
"variant_id": "3e88624d-8535-4720-a781-2257bacd222e",
"quantity": 1,
"price": "205.51",
"sku": "A002013",
"fulfillment_status": "shipped"
}
]
}
],
"cursor": "Y3JlYXRlZF9hdCMyMDI2..."
}
}
完整过滤参数与字段见 查询订单列表。
查找单个订单
按订单 id，或按面向用户的订单号查找。
GET /openapi/2026-01/orders/{id}
响应（节选，订单在 data.data.order 下）：
{
"code": "Success",
"data": {
"order": {
"id": "2386979206089232618121",
"number": "VMT95165",
"total_price": "205.51",
"currency": "USD",
"financial_status": "refunded",
"status": "placed",
"fulfillment_status": "shipped",
"placed_at": "2026-07-01T07:00:32Z",
"created_at": "2026-07-01T07:00:32Z",
"line_items": [
{
"id": "ee73a839-61a2-4504-b4b6-ea55f73f1340",
"product_title": "Denim dress",
"quantity": 1,
"price": "205.51",
"sku": "A002013",
"fulfillment_status": "shipped"
}
],
"fulfillments": [
{
"id": "92db3f11-39ca-4253-8b26-6e2408e5ea21",
"order_id": "2386979206089232618121",
"status": "shipped",
"created_at": "2026-07-01T07:05:00Z",
"line_items": [
{ "id": "ee73a839-61a2-4504-b4b6-ea55f73f1340", "quantity": 1, "sku": "A002013" }
]
}
],
"customer": {
"id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"first_name": "Jane",
"last_name": "Doe",
"order_count": 3,
"total_spent": "612.40"
},
"shipping_address": {
"name": "Jane Doe",
"city": "Los Angeles",
"province": "California",
"country": "United States",
"country_code": "US"
}
}
}
}
更新订单
用 PUT 修改可编辑的订单字段，只有传入的字段会被更新。
PUT /openapi/2026-01/orders/{id}
请求体：
{
"order": {
// 要改的字段，如 note、tags
}
}
返回更新后的订单，在 data.data.order 下。可更新的字段见 更新订单 参考。
取消订单
取消一个已下单的订单，可选带上 reason。
POST /openapi/2026-01/orders/{id}/cancel
请求体（可选）：
{
"reason": "..." // 可选，说明取消原因
}
响应（节选，订单在 data.data.order 下；关键信号是 status 变为 cancelled）：
{
"code": "Success",
"data": {
"order": {
"id": "2386979200059560122875",
"number": "NPI71329",
"status": "cancelled",
"cancelled_at": "2026-07-02T03:25:57Z",
"financial_status": "waiting",
"fulfillment_status": "initialled",
"total_price": "7.00",
"currency": "CNY"
}
}
}
备注