# 管理订单

> 用 Open API 读取和管理 Shoplazza 店铺订单：列表查询、查询单个订单、更新订单与取消订单。

用 Open API 读取和管理店铺订单——查询列表、按订单查找、更新、取消。

## 适用场景

搭建订单管理面板、把订单同步到 ERP，或做一个对订单执行操作的客服工具。

## 前置需求

- 一个已跑通 OAuth 与 token 存储的公开应用——先完成 [开发独立应用](/docs/app/getting-started/create-public-app/develop-app)。下面的每个请求都带 `Access-Token: {token}` 头，使用你为每个店铺保存的 token。
- OAuth 时已授予订单相关的 access scope。

### 查询订单列表

游标分页：传 `per_page`（最大 250），第一页之后再带上一页响应里的 `cursor`。

`GET /openapi/2026-01/orders`

响应（节选，列表在 `data.data.orders` 下，游标在 `data.data.cursor` 下）：

```json
{
  "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..."
  }
}
```

完整过滤参数与字段见 [查询订单列表](/api/orders)。

### 查找单个订单

按订单 id，或按面向用户的订单号查找。

`GET /openapi/2026-01/orders/{id}`

响应（节选，订单在 `data.data.order` 下）：

```json
{
  "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",
        "email": "jane@example.com",
        "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"
      }
    }
  }
}
```

完整字段见 [查询订单详情](/api/order-detail) 与 [按订单号查询](/api/order-by-number)。

### 更新订单

用 `PUT` 修改可编辑的订单字段，只有传入的字段会被更新。

`PUT /openapi/2026-01/orders/{id}`

请求体：

```json5
{
  "order": {
    // 要改的字段，如 note、tags
  }
}
```

返回更新后的订单，在 `data.data.order` 下。可更新的字段见 [更新订单](/api/order-update) 参考。

### 取消订单

取消一个已下单的订单，可选带上 `reason`。

`POST /openapi/2026-01/orders/{id}/cancel`

请求体（可选）：

```json5
{
  "reason": "..." // 可选，说明取消原因
}
```

响应（节选，订单在 `data.data.order` 下；关键信号是 `status` 变为 `cancelled`）：

```json
{
  "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"
    }
  }
}
```

:::note
取消**已支付**订单会触发资金召回（等于退款）。如果支付方式无法召回，取消可能不会完全生效——判断是否取消成功要看订单的 `status` 字段（`cancelled`），不要只看 `financial_status`，召回失败时它可能仍停在 `paid`。若只想退款而不取消订单，改用 [退款与售后](/docs/app/use-cases/orders-and-fulfillment/refunds-and-post-sales)。见 [取消订单](/api/order-cancel)。
:::

## 下一步

- [发货与履约](/docs/app/use-cases/orders-and-fulfillment/fulfill-orders)
- [用 Webhook 监听订单事件](/docs/app/use-cases/orders-and-fulfillment/listen-for-order-events)