Order: Browse Orders
list_orders[Order]
[What it does] Browses orders, returning order summaries, per-tab counts, and cursor pagination; it is the entry point for obtaining order IDs. Set only_count=true to return only those per-tab counts with an empty orders array and no next page. An explicit supplier_platform_id limits results to that supplier; omitting it searches across suppliers.
[When to use] Use it when the user wants to find orders, see pending volume, or filter by store, buyer, or time, and whenever the agent needs real order IDs before reading detail or processing. For how many orders or tab volume only, set only_count=true and read counts; do not follow with a second browse unless the user then asks for the list. Trigger words: recent orders, pending orders, this buyer's order, problem orders, how many orders.
[When not to use] For Failed/cancelled inspection or order-blocker repairs, use get_order. Ordinary Awaiting Order placement uses these list summaries plus diagnose_order_issue; it does not require a detail read for every order. To place orders, use place_orders_to_suppliers. For shipment tracking, use get_package_details.
[How to use]
only_countdefaults to false. Set true only when the user asks how many orders or tab volume. Thenordersis always empty and is not proof of zero orders; usecounts. Emptyordersmust not be copied intoget_orderor placement.cursor,page_size, andsort_orderare ignored. Do not fan out a count call into an exact order-number scan.supplier_platform_idis optional. When the user names no supplier, omit it: orders and returned line items are not limited to one supplier. The string0searches Unmapped only and still filters items to Unmapped. Copy a positive ID fromlist_storessupplier_apps[].supplier_platform_idwhen the user names a supplier, and never substitute a sales channel ID.statusis optional. Omit it by default when the user does not name a tab, and for exact order-number lookup; that returns cross-tab rows within the selected supplier scope in one call. Do not fan out tabs. An explicit status filters returned line items to that tab. Statuses are tab memberships, not exclusive states: an order can sit in several tabs, counts overlap and must not be summed into a total, and pending and awaiting order are distinct values that both belong in any summary.Each
line_items[]row exposessupplier_platform_idandtab_statuses. If this call omittedsupplier_platform_idorstatus, copy the omitted field from the sameline_items[]row intoget_order. Mixedtab_statuses: pick the tab matching the user intent, else the first known value. Do not invent supplier/tab pairs. Iftab_statusesis empty, do not callget_order; re-list with an explicitstatus. Do not fill item tabs fromorders[].order_status.Each row includes
dsers_store_idand, when available,sales_channel_id; resolve recognizable store and supplier names from current account context.line_items[]includes verbatim seller title, SKU when available, quantity, and known fulfillable quantity. Its supplier rows include verbatim product/variant names, quantity, selected shipping method name, and supplier order number. Missing optional fields are unavailable, not zero.other_supplier_platform_countsummarizes items with other suppliers.has_other_supplier_itemsindicates whether any exist;other_supplier_items_countlists eachsupplier_platform_id, itstabs, and its itemcount. Only positive counts are included. Use it to explain the order's additional supplier items to the user.Each row's
order_statusis the tab requested for that call whenstatuswas set; whenstatuswas omitted it is the first known item tab, not a complete status set or an exclusive whole-order state.Money is reported in several bases: order income is authoritative in the seller-platform currency, the setting-currency amount may appear only as a labeled conversion, and item prices and supplier costs use the DSers default currency. Row money follows this request's supplier filter; when
supplier_platform_idis omitted, that scope is not limited to one supplier.To search multiple seller order numbers, set
search_by=order_noand pass a comma-separatedquery, for example1001,1002orABC-1001,ABC-1002. English and Chinese commas are accepted. Only the first 100 non-empty keywords are searched. Results match any supplied keyword as a substring, so1001can also match10010; verify returnedsales_order_numbervalues before selecting orders. When both time fields are omitted, order-number lookups search all available non-archived order history through the end of today; ordinary browsing defaults to the last 30 days. Store, supplier, status, and time filters still apply. Passnext_cursorwith the same query and filters to retrieve more results.only_count=truecounts orders matching the same batch filter.Pages hold up to 100 rows; pass the returned cursor back unchanged for more. [Side effects] None; read-only. [Confirmation] Not required.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_orders"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional search text. For multiple seller order numbers, set search_by=order_no and separate values with English or Chinese commas, for example 1001,1002. Only the first 100 non-empty keywords are searched. Batch results match any supplied keyword as a substring; verify returned sales_order_number values before selecting orders. A single numeric value is treated as an order number when search_by is omitted or default. | |
| cursor | No | Opaque next_cursor returned by a previous call. | |
| status | No | Optional DSers order-tab membership filter. Omit it by default when the user does not name a tab, and for exact order-number lookup; do not fan out tabs. An order matches when at least one item belongs to this tab; it can simultaneously belong to other tabs. pending and awaiting_order are distinct values; received selects the Received tab and can be copied into get_order tab_status. | |
| end_time | No | Optional Unix end timestamp. Omitted or zero defaults to the end of today (23:59:59 in Asia/Shanghai). If only end_time is supplied, the start defaults to 30 days before today. | |
| page_size | No | Items per page, up to 100. Single exact order-number lookup resolves the matched order directly without paging; comma-separated batch lookup honors page_size and cursor. | |
| search_by | No | How query is interpreted. Omit, or use order_no, for an exact lookup of a single numeric seller order number. For comma-separated seller order numbers, always set order_no: results match any supplied keyword as a substring and support cursor pagination. Both lookup modes search all available non-archived order history when both time fields are omitted. Omit status to search across tabs. Use dsers_order_id only for an exact DSers internal order ID. | |
| only_count | No | When true, return only counts for the current filters. orders is always empty and is not proof of zero orders; read counts. cursor, page_size, and sort_order are ignored. Set true only for how many / tab volume; omit or false when order IDs or a browse list are needed. | |
| sort_order | No | Creation-time sort order. | desc |
| start_time | No | Optional Unix start timestamp. For single exact or comma-separated batch order-number lookups, omitting both time fields searches all available non-archived order history. Otherwise an omitted or zero start_time defaults to 30 days before today. Store, supplier, status, and other filters still apply. | |
| dsers_store_ids | No | Copy DSers store IDs from list_stores. Optional. Paste JSON example: ["1999323491106619392"]. | |
| supplier_platform_id | No | Optional supplier platform filter. Omit when the user names no supplier: orders and returned line items are not limited to one supplier. Use 0 only for Unmapped orders with Unmapped item filtering; otherwise copy a positive ID from list_stores supplier_apps[].supplier_platform_id. | |
| sales_order_destination_country_code | No | Optional sales-order destination country code in ISO 3166-1 alpha-2 format, uppercase, for example US for United States or CA for Canada. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| counts | Yes | Counts by DSers order tab | |
| orders | Yes | Order list rows | |
| pagination | Yes | Stable cursor pagination | |
| toolcall_response_at | Yes | UTC timestamp when the Tool response was returned, formatted as RFC3339. |