订单服务 Orders API · 接口参考

概览

Orders API 让你以编程方式创建、查询、更新与删除订单，适合电商、票务、预约等需要订单流转的业务。

所有请求都通过 HTTPS 发送，请求体与响应体均为 application/json。时间字段统一使用 Unix 时间戳（秒）；金额字段统一以最小货币单位（分）表示，例如 39600 表示 ¥396.00。

基础 URL

Base URLtext

https://api.orders.example.com/v1

核心对象：Order

所有端点围绕 order 对象展开。下表列出其字段，后续各端点的响应均基于此结构。

字段	类型	说明
`id`	`string`	订单唯一标识，前缀 `ord_`
`object`	`string`	固定为 `"order"`
`customer_id`	`string`	下单客户标识，前缀 `cust_`
`status`	`string`	`pending` / `paid` / `fulfilled` / `cancelled` / `refunded`
`currency`	`string`	三位 ISO 货币代码，默认 `CNY`
`items`	`array`	订单明细数组，见 items 结构
`amount_subtotal`	`integer`	商品小计（分）
`amount_total`	`integer`	订单总额（分）
`shipping_address`	`object`	收货地址对象
`metadata`	`object`	自定义键值对，最多 20 个
`created_at`	`integer`	创建时间（Unix 秒）
`updated_at`	`integer`	最近更新时间（Unix 秒）

items 结构：每个元素包含 product_id（string）、name（string）、quantity（integer）、unit_price（integer，分）。

鉴权

Orders API 使用 Bearer Token 进行身份认证。每个请求必须在 Authorization 请求头中携带你的 API 密钥。

请求头http

Authorization: Bearer sk_live_********************************

密钥以 sk_live_（生产）或 sk_test_（测试）开头，在控制台的「设置 → API 密钥」中创建。
测试密钥产生的订单仅存在于沙箱，不会触发真实扣款或履约。
密钥等同于账户权限，请勿提交到代码仓库或前端代码中。

鉴权失败：缺少或无效的令牌会返回 401 Unauthorized，错误码为 authentication_error。详见错误码。

限流说明

每个 API 密钥默认限制为 每分钟 100 次请求。超出后返回 429，需等待重置后重试。

每次响应都会在头部返回当前限流状态，便于你在客户端做退避处理：

响应头	说明
`X-RateLimit-Limit`	当前窗口允许的最大请求数（100）
`X-RateLimit-Remaining`	当前窗口剩余可用请求数
`X-RateLimit-Reset`	限流窗口重置时间（Unix 秒）
`Retry-After`	触发 429 时返回，秒数，表示需等待多久

示例：限流响应头http

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1754000460
Retry-After: 12

建议：收到 429 时，使用 Retry-After 的值进行指数退避重试，避免雪崩。批量操作请使用列表端点的分页而非高频单查。

GET /orders

返回当前账户下的订单列表，支持分页与多维筛选。结果按创建时间倒序返回。

查询参数

参数	类型	必填	说明
`limit`	`integer`	可选	返回数量，默认 10，最大 100
`cursor`	`string`	可选	分页游标，取上一页响应的 `next_cursor`
`status`	`string`	可选	按状态筛选：`pending\|paid\|fulfilled\|cancelled\|refunded`
`customer_id`	`string`	可选	按客户筛选
`created_after`	`integer`	可选	仅返回该时间戳之后创建的订单
`created_before`	`integer`	可选	仅返回该时间戳之前创建的订单

请求示例

列出订单curl

curl https://api.orders.example.com/v1/orders?limit=2&status=paid \
  -H "Authorization: Bearer sk_live_********************************"

响应示例

200 · 订单列表json

{
  "object": "list",
  "data": [
    {
      "id": "ord_8f3k2m1n4p",
      "object": "order",
      "customer_id": "cust_9a2b7c",
      "status": "paid",
      "currency": "CNY",
      "items": [
        {
          "product_id": "prod_x12",
          "name": "陶瓷手作体验券",
          "quantity": 2,
          "unit_price": 19800
        }
      ],
      "amount_subtotal": 39600,
      "amount_total": 39600,
      "shipping_address": {
        "line1": "深圳市宝安区新安街道xx号",
        "city": "深圳",
        "state": "广东",
        "postal_code": "518100",
        "country": "CN"
      },
      "metadata": {},
      "created_at": 1754000000,
      "updated_at": 1754000120
    }
  ],
  "has_more": false,
  "next_cursor": null
}

状态码

状态码	含义
200	成功返回订单列表
401	鉴权失败
429	触发限流

POST /orders

创建一个新订单。订单初始状态为 pending，需另行调用支付或更新接口推进状态。

请求体参数

参数	类型	必填	说明
`customer_id`	`string`	必填	客户标识，前缀 `cust_`
`items`	`array`	必填	至少一个明细项，每项含 `product_id`、`quantity`
`shipping_address`	`object`	必填	收货地址，含 line1/city/state/postal_code/country
`currency`	`string`	可选	货币代码，默认 `CNY`
`metadata`	`object`	可选	自定义键值对，最多 20 个

请求示例

创建订单curl

curl https://api.orders.example.com/v1/orders \
  -H "Authorization: Bearer sk_live_********************************" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_9a2b7c",
    "currency": "CNY",
    "items": [
      { "product_id": "prod_x12", "quantity": 2, "unit_price": 19800 }
    ],
    "shipping_address": {
      "line1": "深圳市宝安区新安街道xx号",
      "city": "深圳",
      "state": "广东",
      "postal_code": "518100",
      "country": "CN"
    }
  }'

响应示例

201 · 已创建json

{
  "id": "ord_8f3k2m1n4p",
  "object": "order",
  "customer_id": "cust_9a2b7c",
  "status": "pending",
  "currency": "CNY",
  "items": [
    {
      "product_id": "prod_x12",
      "name": "陶瓷手作体验券",
      "quantity": 2,
      "unit_price": 19800
    }
  ],
  "amount_subtotal": 39600,
  "amount_total": 39600,
  "shipping_address": {
    "line1": "深圳市宝安区新安街道xx号",
    "city": "深圳",
    "state": "广东",
    "postal_code": "518100",
    "country": "CN"
  },
  "metadata": {},
  "created_at": 1754000000,
  "updated_at": 1754000000
}

状态码

状态码	含义
201	订单创建成功
400	参数校验失败
401	鉴权失败
429	触发限流

GET /orders/{id}

按订单 ID 查询单个订单的完整信息。

路径参数

参数	类型	必填	说明
`id`	`string`	必填	订单 ID，前缀 `ord_`

请求示例

查询订单curl

curl https://api.orders.example.com/v1/orders/ord_8f3k2m1n4p \
  -H "Authorization: Bearer sk_live_********************************"

响应示例

200 · 订单详情json

{
  "id": "ord_8f3k2m1n4p",
  "object": "order",
  "customer_id": "cust_9a2b7c",
  "status": "paid",
  "currency": "CNY",
  "items": [
    {
      "product_id": "prod_x12",
      "name": "陶瓷手作体验券",
      "quantity": 2,
      "unit_price": 19800
    }
  ],
  "amount_subtotal": 39600,
  "amount_total": 39600,
  "shipping_address": {
    "line1": "深圳市宝安区新安街道xx号",
    "city": "深圳",
    "state": "广东",
    "postal_code": "518100",
    "country": "CN"
  },
  "metadata": { "source": "wechat_mini" },
  "created_at": 1754000000,
  "updated_at": 1754000120
}

状态码

状态码	含义
200	查询成功
401	鉴权失败
404	订单不存在
429	触发限流

PATCH /orders/{id}

对订单进行部分更新。仅传入需要修改的字段，未传字段保持不变。常用于推进订单状态或更正收货地址。

路径参数

参数	类型	必填	说明
`id`	`string`	必填	订单 ID

请求体参数

参数	类型	必填	说明
`status`	`string`	可选	目标状态，需符合状态机流转规则
`shipping_address`	`object`	可选	完整覆盖收货地址
`metadata`	`object`	可选	合并更新自定义字段

状态机：订单只能按 pending → paid → fulfilled 正向流转，或退回 cancelled / refunded。非法流转会返回 422。

请求示例

更新订单状态curl

curl https://api.orders.example.com/v1/orders/ord_8f3k2m1n4p \
  -X PATCH \
  -H "Authorization: Bearer sk_live_********************************" \
  -H "Content-Type: application/json" \
  -d '{ "status": "fulfilled" }'

响应示例

200 · 更新后的订单json

{
  "id": "ord_8f3k2m1n4p",
  "object": "order",
  "customer_id": "cust_9a2b7c",
  "status": "fulfilled",
  "currency": "CNY",
  "items": [
    {
      "product_id": "prod_x12",
      "name": "陶瓷手作体验券",
      "quantity": 2,
      "unit_price": 19800
    }
  ],
  "amount_subtotal": 39600,
  "amount_total": 39600,
  "shipping_address": {
    "line1": "深圳市宝安区新安街道xx号",
    "city": "深圳",
    "state": "广东",
    "postal_code": "518100",
    "country": "CN"
  },
  "metadata": { "source": "wechat_mini" },
  "created_at": 1754000000,
  "updated_at": 1754005300
}

状态码

状态码	含义
200	更新成功
401	鉴权失败
404	订单不存在
422	状态流转非法或字段冲突
429	触发限流

DELETE /orders/{id}

取消并删除一个订单。仅 pending 或 paid 状态可被删除；已履约（fulfilled）的订单需走退款流程而非删除。

路径参数

参数	类型	必填	说明
`id`	`string`	必填	订单 ID

请求示例

删除订单curl

curl https://api.orders.example.com/v1/orders/ord_8f3k2m1n4p \
  -X DELETE \
  -H "Authorization: Bearer sk_live_********************************"

响应示例

200 · 删除确认json

{
  "id": "ord_8f3k2m1n4p",
  "object": "order",
  "deleted": true
}

状态码

状态码	含义
200	删除成功
401	鉴权失败
404	订单不存在
409	状态冲突，订单不可删除
429	触发限流

错误码

所有错误响应均使用 application/json 并返回统一的错误结构。通过 error.code 进行程序化处理。

错误响应结构json

{
  "error": {
    "code": "validation_error",
    "message": "items is required and must contain at least one item",
    "field": "items"
  }
}

通用错误码表

HTTP 状态码	error.code	说明
400	`validation_error`	请求参数缺失或格式错误，详见 `field`
401	`authentication_error`	缺少或无效的 API 密钥
403	`permission_error`	密钥无权访问该资源
404	`not_found`	订单或资源不存在
409	`conflict_error`	资源状态冲突，操作无法执行
422	`unprocessable_error`	语义校验失败，如非法状态流转
429	`rate_limit_exceeded`	请求过于频繁，参考限流说明
500	`api_error`	服务端内部错误，可安全重试
503	`service_unavailable`	服务暂时不可用，稍后重试

版本变更

文档随 API 版本推进。当前版本 v1.2.0，基础 URL 路径为 /v1。

v1.2.0 · 2026-07-15

为 order 对象新增 metadata 自定义字段（最多 20 个）。
列表端点 GET /orders 新增 created_after 与 created_before 时间筛选。

v1.1.0 · 2026-03-01

新增 PATCH /orders/{id}，支持订单部分更新。
订单新增 amount_subtotal 字段。

v1.0.0 · 2025-11-01

首次发布：支持创建、列出、查询、删除订单。
引入 Bearer Token 鉴权与每分钟 100 次限流。

Orders API 参考

概览

基础 URL

核心对象：Order

鉴权

限流说明

查询参数

请求示例

响应示例

状态码

请求体参数

请求示例

响应示例

状态码

路径参数

请求示例

响应示例

状态码

路径参数

请求体参数

请求示例

响应示例

状态码

路径参数

请求示例

响应示例

状态码

错误码

通用错误码表

版本变更

v1.2.0 · 2026-07-15

v1.1.0 · 2026-03-01

v1.0.0 · 2025-11-01