list_orders

Paginates the consenting user’s order history, sorted by creation time in descending order (newest first). Before returning, the status of every open order on the page is refreshed automatically, so the status you get is normally the current one — no need to confirm order by order.

Completed and cancelled orders are not refreshed. Those orders are already settled and their status will not change again. The one exception is a refund issued after an order completes — that will not show up in the list, so query the order with get_order_status.

Use get_order_status when you need rider and delivery information. list_orders returns an overview (status / shop / payable amount / item breakdown / time). When you need rider and delivery information, or paid/completed times, call get_order_status with an order_id from the list.

Consent rotation does not affect visibility. Orders are attached to the user’s consent relationship (not to a single consent_grant_id): after the user re-binds or the grant rotates, the newly issued consent_grant_id can still see all of that user’s order history. The list is scoped to the current consenting user and never returns another user’s orders.

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix, from `verify_user_bind`), identifying the consenting user
`limit`	integer	No	`20`	Page size, max 50 (values above 50 are clamped to 50, below 1 to 1)
`offset`	integer	No	`0`	Pagination offset, starting at 0; pass the previous response’s `next_offset` for the next page. Capped at 1000000 (above is clamped, negatives become 0)
`lang`	string	No	—	Language for this response. One of `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`; defaults to the language set at binding time (Chinese if unset)
`include_chinese`	boolean	No	false	When `true`, the response also includes the Chinese original (`<key>_zh`) — see Bilingual responses

Returns

{
  "orders": [
    {
      "order_id": "ord_c47fb84108b74404aa1abd01310c8b8f",
      "status": "completed",
      "status_text": "已完成",
      "shop_name": "茶百道(星光大道24h店)",
      "payable_price": 2300,
      "items_snapshot": [
        {
          "name": "Mango Pomelo Sago",
          "line_total": 2300,
          "quantity": 1,
          "description": "Regular ice / 70% sugar",
          "image_url": "https://img.alicdn.com/i3/2215646075688/O1CN01SeLKKLgum8F1hk6i_!!2215646075688-2-koubei.png"
        }
      ],
      "address_id": "addr_9198205b27df48b7bd2cc4ba894b7045",
      "address": {
        "display_name": "Orange Hub (Gate 2)",
        "address_detail": "621",
        "city": "",
        "lat": 30.276617,
        "lng": 120.030885,
        "contact_name": "Wang",
        "contact_phone_masked": "188****2920",
        "tag": "home"
      },
      "detail_url": "https://g.clawdot.ai/9Kd3T",
      "created_at": "2026-07-20T11:27:06",
      "updated_at": "2026-07-20T11:52:31"
    }
  ],
  "next_offset": null
}

The amount field payable_price is in cents (integer), not yuan. e.g. payable_price: 2300 means ¥23.00.

Field	Type	Description
`orders`	array	Order list, sorted by creation time descending (newest first)
`orders[].order_id`	string	Platform order ID (`ord_` prefix), usable directly with `get_order_status`
`orders[].status`	string	Order status, normalized platform status enum (see table below)
`orders[].status_text`	string	Localized (Chinese) status label, one-to-one with `status`
`orders[].shop_name`	string	Shop name
`orders[].payable_price`	integer	Payable amount (cents)
`orders[].items_snapshot`	array \| null	What was ordered. `null` for orders placed before this feature shipped
`orders[].items_snapshot[].name`	string	Item name
`orders[].items_snapshot[].line_total`	integer \| null	Line total in cents, quantity already included — do not multiply by `quantity`
`orders[].items_snapshot[].quantity`	integer \| null	Quantity ordered
`orders[].items_snapshot[].description`	string	Spec / preparation summary (including specs applied by default); empty string when there is none
`orders[].items_snapshot[].image_url`	string \| null	Item image link, ready to show to the user. It is the image as of the time the order was placed, so a later change by the merchant does not affect it. `null` for orders placed before this feature shipped
`orders[].address_id`	string \| null	Delivery address ID for this order; pass it to `select_address` to send the next order to the same place. It points at that address in the address book, so if the user edited it later you get the edited content; passing it after the address was deleted returns an error. `null` for orders placed before this feature shipped
`orders[].address`	object \| null	Delivery address content for this order, ready to show to the user. Points at the same address-book entry as `address_id`: if the user edited it later you get the edited content. `null` when the address was deleted, or when the order has no `address_id`
`orders[].address.display_name`	string	Address display name
`orders[].address.address_detail`	string	Address detail (building / room)
`orders[].address.city`	string	City; may be an empty string for addresses saved early on
`orders[].address.lat`	number \| null	Latitude (AMap GCJ-02 coordinate system)
`orders[].address.lng`	number \| null	Longitude (AMap GCJ-02 coordinate system)
`orders[].address.contact_name`	string \| null	Contact name
`orders[].address.contact_phone_masked`	string \| null	Masked contact phone, e.g. `188****2920`
`orders[].address.tag`	string	Address tag (free-form string); empty string when not set
`orders[].detail_url`	string \| null	Order detail page link — share it with the user to track the order; for unpaid orders it also opens the checkout. Same page as `detail_url` from `get_order_status`. Each call may return a different link, and all of them work — do not use it as an order identifier or compare it across calls. Valid for 30 days. For orders created with `require_phone_verify: true`, the link first asks for the last 4 digits of the ordering phone number
`orders[].created_at`	string	Order creation time (ISO 8601)
`orders[].updated_at`	string	Time the order status last changed (ISO 8601); equals `created_at` when it never changed
`next_offset`	integer \| null	Next-page cursor, used as the `offset` of the next request; `null` when there are no more

status enum vs status_text:

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

In rare cases the status refresh times out; that order falls back to its last known status while the rest of the list is unaffected. For especially time-sensitive cases you can double-check that order with get_order_status. Unrecognized statuses safely fall back to created and never leak the channel’s raw status code to the caller.

Pagination

On the first call, omit offset (or pass 0) to get the first page.
When the response’s next_offset is non-null, use it as the offset of the next call; null means you’ve reached the last page.
An empty orders array means the user has no orders.

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing consent grant (no `consent_grant_id`)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CAP_NOT_BOUND`	The delivery capability is not enabled for this agent
`CONSENT_GRANT_WRONG_CAP`	The consent grant belongs to another capability and cannot be used for this tool

See Error Handling for the full list.

Example Call

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

Overview

Integration

Guides

Authorization

Shops

Addresses

Order

Payment

list_orders

list_orders

Parameters

Returns

Error Codes

Example Call

​list_orders

​Parameters

​Returns

​Pagination

​Error Codes

​Example Call

list_orders

Parameters

Returns

Pagination

Error Codes

Example Call