Skip to main content
GET
List Orders
Retrieve a list of all orders associated with your account. Orders are returned in reverse chronological order (most recent first).

Response

Returns an array of order objects, each containing:
  • id - Order UUID
  • status - Current order status
  • items - Products in the order
  • shipping_address - Delivery address
  • job_result - Processing results (for completed/failed orders)
  • merchant_order_ids - The retailer’s own order number(s), once placed — see Merchant Order IDs
  • created_at - Order creation timestamp
  • updated_at - Last update timestamp

Order Statuses

Expanding tracking events

By default, list responses keep tracking payloads small: each tracking number includes its status but not the full carrier checkpoint timeline. Pass include=tracking_events to embed the per-scan checkpoints array on every tracking number.
The single-order read (GET /orders/{order_id}) always includes the full checkpoint timeline — include only affects the list endpoint. See Order Tracking for the checkpoint fields.

Pagination

Currently, all orders are returned in a single response. Pagination will be added in a future update.

Authorizations

Authorization
string
header
required

Zinc API key (Bearer zn_...)

Headers

authorization
string | null

Query Parameters

limit
integer
default:50

Number of orders to return

Required range: 1 <= x <= 500
offset
integer
default:0

Number of orders to skip

Required range: x >= 0
order_id
string | null

Filter by order ID (partial match)

search
string | null

Partial match on order ID OR tracking number

merchant_order_id
string | null

Filter by the retailer's own order number (e.g. an Amazon 113-… ID), matched exactly against any of the order's order-placing jobs. Exact, not partial — dashes in the term are matched both as typed and stripped.

Maximum string length: 200
status_filter
string | null

Filter by order status

tracking_status
string | null

Filter to orders having at least one tracking number with this status

has_tracking
boolean | null

If true, only orders with at least one tracking number; if false, only orders with none

return_status
string | null

Filter by return-request status. open → orders with at least one open return. closed → orders with at least one approved or denied return. Omit for no filter.

created_after
string<date-time> | null

Only orders created at/after this instant (inclusive)

created_before
string<date-time> | null

Only orders created before this instant (exclusive)

metadata_key
string | null

Top-level metadata key to match, e.g. po_number. Must be sent together with metadata_value. Nested paths are not supported.

Maximum string length: 200
metadata_value
string | null

Exact value metadata_key must equal. Matching is exact, not partial, and case-sensitive. Must be sent together with metadata_key.

Maximum string length: 500
include
string[]

Optional expansions. tracking_events embeds the full carrier checkpoint timeline (and latest status) on each tracking number; omitted by default to keep list payloads small.

Response

Successful Response

List of orders for a particular user_id

orders
OrderResponse · object[]
required
total
integer
required
limit
integer
required
offset
integer
required