orders_searchOrders
Search orders (Orders v2026-01-01): ONE Amazon page plus data.nextToken, the full v2026 filter set, and line items INLINE on each order (order.orderItems) — no separate items call.
readAmazon Seller (SP-API)sp.orders_2026-01-01
To sync a window, repeat with the same filters and pagination_token = data.nextToken until it is null; for an incremental sync pass last_updated_after = your last watermark. For one known order id use orders_getOrder. Amazon SP-API · searchOrders · GET /orders/2026-01-01/orders
Call it
In an AI client (MCP)
{
"name": "orders_searchOrders",
"arguments": {
"store": "myStore-US"
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/orders_searchOrders \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US"}'Early access — the Tool API is open on request, contact us.
Arguments
| Name | Type | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
created_after | string · date-time | ISO 8601 with the Z suffix ('2026-04-20T00:00:00Z') — v2026 rejects a naive timestamp. Exactly ONE of created_after or last_updated_after is required (Amazon refuses none or both). |
created_before | string · date-time | ISO 8601 with the Z suffix ('2026-04-20T00:00:00Z') — v2026 rejects a naive timestamp. Exactly ONE of created_after or last_updated_after is required (Amazon refuses none or both). |
last_updated_after | string · date-time | the same rule; last_updated_after is the incremental-sync watermark. |
last_updated_before | string · date-time | the same rule; last_updated_after is the incremental-sync watermark. |
fulfillment_statuses | string[] | the fulfillment states to keep. v2026 has no orderStatuses filter and no flat orderStatus field — filter here, or pass included_data ['FULFILLMENT'] and read order.fulfillment.fulfillmentStatus. Allowed: PENDING_AVAILABILITY | PENDING | UNSHIPPED | PARTIALLY_SHIPPED | SHIPPED | CANCELLED | UNFULFILLABLE.PENDING_AVAILABILITYPENDINGUNSHIPPEDPARTIALLY_SHIPPEDSHIPPEDCANCELLEDUNFULFILLABLE |
marketplace_ids | object[] | OMIT it — the search is then scoped to the store ref's marketplace; a list (≤50) searches exactly those marketplaces and mixes their orders. |
fulfilled_by | string[] | who fulfils the order; omit for both. Allowed: MERCHANT | AMAZON.MERCHANTAMAZON |
included_data | string[] | expansion selectors per order, as on orders_getOrder — PACKAGES carries tracking inline. Allowed (the subset that needs no Restricted Data Token): RECIPIENT | PROCEEDS | EXPENSE | PROMOTION | CANCELLATION | FULFILLMENT | PACKAGES | TAX | PAYMENT | FULFILLMENT_ORDERS.RECIPIENTPROCEEDSEXPENSEPROMOTIONCANCELLATIONFULFILLMENTPACKAGESTAXPAYMENTFULFILLMENT_ORDERS |
max_results_per_page | integer | 1–100 (default 100). |
pagination_token | string | the cursor from the previous call's data.nextToken; omit for the first page. |
Result
Every tool answers {notification, data, human_action}; data carries:
data.orders / data.count— this page's orders (line items at order.orderItems) and how many.data.nextToken— pass it as pagination_token; null on the last page.data.createdBefore / data.lastUpdatedBefore— the upper bound Amazon actually applied (clamped to ~2 minutes before the request) — whichever is non-null is the "after" watermark of your next incremental sync; use it instead of your own clock or you leave a gap.
Gotchas
- Provide EXACTLY ONE of created_after or last_updated_after (the matching "before" is optional); mixing the two pairs is InvalidInput.