Orders
List the orders of an account
Returns a page of the account's orders, the most recent first (sorted by creation date, not configurable). page and per_page paginate (defaults 1 and 20); status and search filter. Each order is a summary: its items, units, customer and recipient, without the prices and shipments of getOrder. The recipient (name and email of the delivery address) replaces shipTo. A test key (sk_test_) only lists test orders, a live key only real orders. For the full detail of one order, call getOrder. Cursor pagination: every page carries pagination.next_cursor and pagination.has_more; pass cursor (the next_cursor of the page before) to get the orders after it, in the same order, without skipping or repeating one when orders are created meanwhile (page is then ignored). limit sets the page size of both ways (1 to 100). A cursor this API did not give is refused with 400 INVALID_CURSOR.
Request
Authorization
Bearer token
Send your API key in the Authorization header: Authorization: Bearer sk_test_…. A sk_test_ key creates and sees test orders only. Keys and test mode.
Path parameters
accountIdstringrequiredUnique identifier of the account, or the alias@mefor the account authenticated by the token.
Query parameters
pagestringPage number, starting at 1 (default 1). A value that is not a positive whole number is replaced by 1. Declared as a string so that a malformed value is never refused: the route has always accepted it.per_pagestringOrders per page (default 20). A value that is not a positive whole number is replaced by 20. The API sets no maximum: ask for pages of 50 at most. Declared as a string so that a malformed value is never refused: the route has always accepted it.statusstringKeeps the orders in one of these statuses: one status, or several separated by commas (draft,in_queue). Statuses are listed byGET /orders/statuses. Do not repeat the parameter.searchstring or array of stringFree text, 100 characters kept. Send it once: a repeated parameter is accepted but ignored. Matches, without regard to case, a part of the order's reference, of its customer's name, company or email, of its recipient's name or email, or the exact order id.cursorstringOpaque cursor: thepagination.next_cursorof the page before. Returns the orders after that one;pageis ignored. Do not build it yourself: a value this API did not give is refused with 400INVALID_CURSOR.limitintegerPage size, 1 to 100 (default:per_page, else 20). Any other value is refused with 400INVALID_LIMIT.
Responses
200A page of orders
successbooleanordersarray of Order + objectThe orders of the page, most recent first. Empty when the page is past the last one.paginationobjectWithoutcursor:total,page,per_page,limit,next_cursorandhas_more. Withcursor:limit,next_cursorandhas_more.pagination.totalintegerNumber of orders matching the filters, all pages togetherpagination.pageintegerThe page returnedpagination.per_pageintegerThe page size usedpagination.limitintegerThe page size usedpagination.next_cursorstring, nullablerequiredPass it ascursorto get the next page; null on the last pagepagination.has_morebooleanrequiredWhether orders follow this page
400cursor is not a next_cursor of this API (INVALID_CURSOR), or limit is not 1 to 100 (INVALID_LIMIT)
Type: Error
401Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (INVALID_TOKEN)
Type: Error
403The API key is inactive or revoked (INACTIVE_API_KEY), or targets another account (ACCOUNT_ACCESS_DENIED, refused once the account guard is enforced); with an OAuth access token: a token of scope mcp (INSUFFICIENT_SCOPE), a path naming another account or a person no longer a member of it (ACCOUNT_ACCESS_DENIED), a real token on the sandbox host (SANDBOX_REQUIRES_TEST_KEY)
Type: Error
429
500Server error
Type: Error