list_orders

分页查询当前授权用户的历史订单列表，按创建时间倒序（新单在前）。返回前会自动刷新本页里未完结订单的状态，因此列表里的 status 通常已经是当前状态，不必再逐单确认。

已完成、已取消的订单不再刷新。 这类订单已经收口，状态不会再变。少数例外是订单完成后才发生的售后退款——它不会反映到列表里，需要用 get_order_status 查询该单。

需要骑手与配送信息时用 get_order_status。 list_orders 给的是概览（状态 / 店铺 / 应付金额 / 商品明细 / 时间）；需要骑手与配送信息、支付与完成时间时，用列表里的 order_id 调 get_order_status。

授权轮换不影响可见范围。 订单挂在用户授权关系上（而非某一个 consent_grant_id）：用户重新绑定 / 授权轮换后换发的新 consent_grant_id 仍能看到该用户的全部历史订单。列表按当前授权用户维度隔离，不会返回他人订单。

参数

参数	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀，来自 `verify_user_bind`），标识已授权用户
`limit`	integer	否	`20`	单页返回条数，最大 50（超过按 50 截断，小于 1 按 1）
`offset`	integer	否	`0`	翻页偏移量，从 0 开始；传上一次响应的 `next_offset` 取下一页。上限 1000000，超过按上限截断，负数按 0
`lang`	string	否	—	本次返回内容使用的语言，枚举 `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`；不传则用绑定时设定的语言（默认中文）
`include_chinese`	boolean	否	false	为 `true` 时响应同时返回中文原文（`<key>_zh`），见双语响应

{
  "orders": [
    {
      "order_id": "ord_c47fb84108b74404aa1abd01310c8b8f",
      "status": "completed",
      "status_text": "已完成",
      "shop_name": "茶百道(星光大道24h店)",
      "payable_price": 2300,
      "items_snapshot": [
        {
          "name": "杨枝甘露",
          "line_total": 2300,
          "quantity": 1,
          "description": "标准冰/七分糖",
          "image_url": "https://img.alicdn.com/i3/2215646075688/O1CN01SeLKKLgum8F1hk6i_!!2215646075688-2-koubei.png"
        }
      ],
      "address_id": "addr_9198205b27df48b7bd2cc4ba894b7045",
      "address": {
        "display_name": "亲橙Hub(2号门)",
        "address_detail": "621",
        "city": "",
        "lat": 30.276617,
        "lng": 120.030885,
        "contact_name": "王xx",
        "contact_phone_masked": "188****2920",
        "tag": "家"
      },
      "detail_url": "https://g.clawdot.ai/9Kd3T",
      "created_at": "2026-07-20T11:27:06",
      "updated_at": "2026-07-20T11:52:31"
    }
  ],
  "next_offset": null
}

金额字段 payable_price 单位为分（整数），不是元。例如 payable_price: 2300 表示 ¥23.00。

字段	类型	说明
`orders`	array	订单列表，按创建时间倒序（新单在前）
`orders[].order_id`	string	平台订单 ID（`ord_` 前缀），可直接用于 `get_order_status`
`orders[].status`	string	订单状态，统一的平台状态枚举（见下表）
`orders[].status_text`	string	状态的中文文案（与 `status` 一一对应）
`orders[].shop_name`	string	店铺名称
`orders[].payable_price`	integer	应付金额（分）
`orders[].items_snapshot`	array \| null	这单点了什么。本功能上线前的旧订单为 `null`
`orders[].items_snapshot[].name`	string	商品名称
`orders[].items_snapshot[].line_total`	integer \| null	该行合计金额（分，已含数量）。不要再乘 `quantity`
`orders[].items_snapshot[].quantity`	integer \| null	购买数量
`orders[].items_snapshot[].description`	string	规格 / 做法摘要（含默认生效规格），无则为空字符串
`orders[].items_snapshot[].image_url`	string \| null	商品图片链接，可直接展示给用户。这是下单当时的图片，商家后来换图不影响。本功能上线前的订单为 `null`
`orders[].address_id`	string \| null	本单的收货地址 ID，可传给 `select_address` 让下一单送到同一地址。它指向地址簿中的这个地址，用户后来编辑过则读到的是编辑后的内容；地址已删除时再传会报错。功能上线前的存量订单为 `null`
`orders[].address`	object \| null	本单收货地址的内容信息，可直接展示给用户。与 `address_id` 指向地址簿中的同一个地址：用户后来编辑过，读到的是编辑后的内容。地址已删除、或订单没有 `address_id` 时为 `null`
`orders[].address.display_name`	string	地址展示名
`orders[].address.address_detail`	string	地址详情
`orders[].address.city`	string	城市；早期保存的地址可能为空字符串
`orders[].address.lat`	number \| null	纬度（高德地图 GCJ-02 坐标系）
`orders[].address.lng`	number \| null	经度（高德地图 GCJ-02 坐标系）
`orders[].address.contact_name`	string \| null	联系人称呼
`orders[].address.contact_phone_masked`	string \| null	脱敏联系电话，如 `188****2920`
`orders[].address.tag`	string	地址标签（自定义字符串）；未打标为空字符串
`orders[].detail_url`	string \| null	订单详情页链接，可直接发给用户查看订单进度；未支付的订单打开后可继续支付。与 `get_order_status` 的同名字段指向同一个页面。每次调用返回的链接可能不同，但都可用——不要用作订单标识或做前后比对。链接有效期 30 天。下单时传了 `require_phone_verify: true` 的订单，打开链接时先要求输入下单手机号后 4 位确认本人
`orders[].created_at`	string	下单时间（ISO 8601）
`orders[].updated_at`	string	订单状态最近变化的时间（ISO 8601）；状态从未变过时等于 `created_at`
`next_offset`	integer \| null	下一页游标，作为下次请求的 `offset`；无更多时为 `null`

status 枚举与 status_text 对照：

`status`	`status_text`
`created`	订单已创建
`pending_payment`	待支付
`paid`	已支付
`preparing`	商家备餐中
`delivering`	配送中
`completed`	已完成
`cancelled`	已取消
`failed`	下单或履约失败
`refunded`	已退款

极少数情况下状态刷新会查询超时，该单会退回上一次已知状态、其余订单不受影响；对时效特别敏感的场景可用 get_order_status 复核该单。无法识别的状态会安全回落为 created，不会向调用方泄露渠道原始状态码。

分页

首次调用不传 offset（或传 0）取第一页。
响应里的 next_offset 非 null 时，作为下一次调用的 offset 取下一页；为 null 表示已到末页。
orders 为空数组表示该用户暂无订单。

错误码

code	说明
`CONSENT_GRANT_REQUIRED`	缺少用户授权（未传 `consent_grant_id`）
`CONSENT_GRANT_INVALID`	用户授权无效
`CONSENT_GRANT_EXPIRED`	用户授权已过期，需重新授权
`CAP_NOT_BOUND`	该 Agent 未开通外卖能力
`CONSENT_GRANT_WRONG_CAP`	授权属于其它能力，不可用于本工具

完整错误码见错误处理。

调用示例

{
  "name": "list_orders",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "limit": 20
  }
}

概览

接入

指南

授权

店铺

地址

下单

支付

list_orders

list_orders

参数

返回

分页

错误码

调用示例

​list_orders

​参数

​返回

​分页

​错误码

​调用示例

list_orders

参数

返回

分页

错误码

调用示例