list_orders
Updated October 12, 20262 min read
List orders with paging, sorting, search, merchant filters, date filters, hold filters, and fulfillment-order-aware filters. For the on-hold review queue, filter with status on_hold and sort by on_hold_details.sla_timestamp; each order carries on_hold_details. Use select with json-mask syntax to trim the returned payload.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tenantId | string | Yes | — |
agg_by | string | No | — |
assigned_to_user | oneOf | No | ID of the user or team the latest order-level hold is assigned to. A released hold still matches, so combine with status on_hold for the open queue. |
billing_country | oneOf | No | — |
country_access | oneOf | No | — |
creation_date_from | string | No | — |
creation_date_to | string | No | — |
creation_source_type | oneOf | No | — |
customer_key | oneOf | No | Customer key of the order, to list the orders of one customer. |
fields | oneOf | No | — |
fulfillment_order_item_cancellation_reason | oneOf | No | — |
fulfillment_order_item_status | oneOf | No | — |
hold_date_from | string | No | First day of the hold date range, yyyy-MM-dd. Used with hold_metric held; defaults to six days before today. |
hold_date_to | string | No | Last day of the hold date range, yyyy-MM-dd. Used with hold_metric held; defaults to today. |
hold_metric | string | No | Automatic holds only. awaiting_review returns orders currently held by an order hold rule; held returns orders that an order hold rule put on hold between hold_date_from and hold_date_to. The hold can still be active, already released, or followed by another hold. Values: held, awaiting_review. |
hold_rule_id | string | No | Narrow hold_metric to one order hold rule. Requires hold_metric. |
location_access | oneOf | No | — |
location_id | oneOf | No | — |
merchant | oneOf | No | — |
on_hold | oneOf | No | true returns orders where the order or any of its fulfillment orders is on hold; false returns the rest. Status on_hold matches only orders held as a whole. |
order_date_from | string | No | — |
order_date_to | string | No | — |
order_ids | oneOf | No | — |
order_refs | oneOf | No | — |
page | oneOf | No | — |
page_size | oneOf | No | — |
sales_channel | oneOf | No | — |
search_mode | string | No | — |
search_string | string | No | — |
select | string | No | json-mask expression to filter response fields. |
shipping_city | oneOf | No | — |
shipping_country | oneOf | No | — |
shipping_state | oneOf | No | — |
sort_by | string | No | Order field to sort by, for example creation_date or on_hold_details.sla_timestamp. |
sort_direction | string | No | Values: asc, desc. |
status | oneOf | No | Order status: open, partially_allocated, allocated, processing, fulfilled, cancelled, closed, on_hold. on_hold returns orders held as a whole. |
sub_agg_by | string | No | — |
total_quantity_from | oneOf | No | — |
total_quantity_to | oneOf | No | — |
tzoffset | oneOf | No | — |
update_date_from | string | No | — |
update_date_to | string | No | — |
update_source_type | oneOf | No | — |
Example agent prompt
"Show me the recent orders."
list_orders(
tenantId="…"
)
Example: the on-hold review queue
"Which orders are on hold, most urgent first?"
list_orders(
tenantId="…",
status="on_hold",
sort_by="on_hold_details.sla_timestamp",
sort_direction="asc",
select="orders(order_id,partner_order_reference,on_hold_details)"
)