Get all orders

GET /v1/orders

List your store's orders. Orders require a commercial account; other stores get 403.

With no query parameters, every order is returned as a plain array. Add any of the parameters below to filter, sort and page the results:

Filters: field=value matches exactly (for example status=open). For other comparisons use field.operator=value, where the operator is one of eq, ne, gt, gte, lt, lte, contains, startsWith, endsWith (the text operators ignore case), in or notIn. in and notIn take a comma-separated list (source.in=shopify,etsy). Which operators a field accepts depends on its type. For null checks, ranges with between, or and/or combinations, use POST /v1/orders/search. Filterable fields include orderNumber, status (open or closed), source, customerId, externalId, deadline, processedAt and createdAt.
Sorting: sort=field:asc or sort=field:desc; separate several with commas.
Paging: limit (up to 1000) and offset.
Related data: include=items, include=customer or include=items,customer embeds each order's line items and customer.
Metadata: meta=true wraps the results as { "data": [...], "meta": { ... } } with the total count and whether more pages exist.

To fetch one order with its items and customer, use GET /v1/orders/{orderId}.

Requires: order.view

Query Parameters

orderNumber optional

string

Filter on orderNumber. A bare value is an exact match (orderNumber=value); use orderNumber.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

source optional

string

Filter on source. A bare value is an exact match (source=value); use source.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

status optional

string

Filter on status. A bare value is an exact match (status=value); use status.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

cancelledAt optional

string

Filter on cancelledAt. A bare value is an exact match (cancelledAt=value); use cancelledAt.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

shippedAt optional

string

Filter on shippedAt. A bare value is an exact match (shippedAt=value); use shippedAt.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

customerId optional

string

Filter on customerId. A bare value is an exact match (customerId=value); use customerId.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

integrationId optional

string

Filter on integrationId. A bare value is an exact match (integrationId=value); use integrationId.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

priceBucket optional

string

Filter on priceBucket. A bare value is an exact match (priceBucket=value); use priceBucket.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

price optional

string

Filter on price. A bare value is an exact match (price=value); use price.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

currency optional

string

Filter on currency. A bare value is an exact match (currency=value); use currency.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

externalId optional

string

Filter on externalId. A bare value is an exact match (externalId=value); use externalId.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

externalUrl optional

string

Filter on externalUrl. A bare value is an exact match (externalUrl=value); use externalUrl.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

sourceRef optional

string

Filter on sourceRef. A bare value is an exact match (sourceRef=value); use sourceRef.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

note optional

string

Filter on note. A bare value is an exact match (note=value); use note.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

deadline optional

string

Filter on deadline. A bare value is an exact match (deadline=value); use deadline.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

processedAt optional

string

Filter on processedAt. A bare value is an exact match (processedAt=value); use processedAt.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

syncDisabled optional

string

Filter on syncDisabled. A bare value is an exact match (syncDisabled=value); use syncDisabled.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

customMetadata optional

string

Filter on customMetadata. A bare value is an exact match (customMetadata=value); use customMetadata.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

id optional

string

Filter by record ID. A bare value is an exact match; use id.in=a,b,c for several (up to 100). See Querying Data.

storeId optional

string

Filter by store ID. Results are always limited to the store your API key belongs to, so this is rarely useful. See Querying Data.

createdAt optional

string

Filter by creation time. Pass an ISO 8601 timestamp with a comparison operator, e.g. createdAt.gte=2025-01-01T00:00:00Z. See Querying Data.

updatedAt optional

string

Filter by last-modified time. Pass an ISO 8601 timestamp with a comparison operator, e.g. updatedAt.gt=2025-01-01T00:00:00Z to fetch what changed since a checkpoint. See Querying Data.

sort optional

string

Comma-separated field:direction pairs, applied in order, e.g. createdAt:desc,name:asc. Direction is asc (the default) or desc. At most 5 clauses; JSON and array fields cannot be sorted on. See Querying Data.

limit optional

number

Maximum number of records to return, 1–1000. Defaults to 1000; larger values are capped at 1000. See Querying Data.

offset optional

number

Number of matching records to skip before returning results. Combine with limit to page through a list, and with meta=true to learn the total. See Querying Data.

fields optional

string

Comma-separated list of fields to return, e.g. id,name,updatedAt. Other fields are left out of each record. At most 50 fields. See Querying Data.

include optional

string

Comma-separated related records to embed in each result, e.g. linkedParts,linkedParts.part. At most 4 includes, each at most 2 levels deep; only the relations this endpoint supports are accepted, anything else is a 400. See Querying Data.

meta optional

boolean

Set to true to wrap the response as { data, meta }, where meta carries total, count, offset, limit, hasMore and executionTime. Without it the response is a bare array. See Querying Data.

hints optional

boolean

Set to true to add a hints array of suggested follow-up API calls to the response (aimed at AI agents). A list response is wrapped as { data, meta, hints }. See Querying Data.

Examples

Open orders, newest first, with line items

Request

GET /v1/orders?status=open&sort=createdAt:desc&limit=25&include=items

Response

[
  {
    "id": "o4r8d2e6r0x3c7v1b5n9m2q6",
    "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
    "orderNumber": "1042",
    "status": "open",
    "source": null,
    "customerId": "c3u7s1t5o9m2e6r0q4w8e1r5",
    "price": 34.5,
    "currency": "USD",
    "deadline": "2026-09-30T00:00:00.000Z",
    "processedAt": "2026-09-23T15:20:44.103Z",
    "syncDisabled": false,
    "createdAt": "2026-09-23T15:20:44.180Z",
    "updatedAt": "2026-09-23T15:20:44.180Z",
    "items": [
      {
        "id": "i9t3e7m1q5w2r6t0y4u8i3o5",
        "orderId": "o4r8d2e6r0x3c7v1b5n9m2q6",
        "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
        "quantity": 2,
        "externalSku": "BENCHY-RED",
        "processedStatus": "unprocessed"
      }
    ]
  }
]

Paginate Shopify orders with metadata

Request

GET /v1/orders?source=shopify&sort=processedAt:desc&limit=50&offset=0&meta=true

Response

{
  "data": [
    {
      "id": "o9q3w7e1r5t8y2u6i0o4p7a1",
      "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
      "orderNumber": "#5821",
      "status": "open",
      "source": "shopify",
      "externalId": "6194837261945",
      "price": 58,
      "currency": "USD",
      "processedAt": "2026-09-23T13:48:09.000Z",
      "syncDisabled": false,
      "createdAt": "2026-09-23T13:48:31.772Z",
      "updatedAt": "2026-09-23T13:48:31.772Z"
    }
  ],
  "meta": {
    "total": 137,
    "count": 50,
    "offset": 0,
    "limit": 50,
    "hasMore": true,
    "executionTime": 42
  }
}

Response Schema

Order[] | SearchResponse

Variant 1Order[]

cancelledAtoptionalnullable

string

createdAtrequired

string

format: date-time

currencyoptionalnullable

string

customerIdoptionalnullable

string

pattern: ^[a-z0-9]{24}$

customMetadataoptional

Record<string, any>

Construct a type with a set of properties K of type T

deadlineoptionalnullable

string

externalIdoptionalnullable

string

externalUrloptionalnullable

string

idrequired

string

pattern: ^[a-z0-9]{24}$

integrationIdoptionalnullable

string

pattern: ^[a-z0-9]{24}$

noteoptionalnullable

string

orderNumberrequired

string

priceoptionalnullable

number

priceBucketoptionalnullable

number

processedAtoptionalnullable

string

shippedAtoptionalnullable

string

sourceoptionalnullable

enum

etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix

sourceRefoptionalnullable

string

statusrequired

"open" | "closed"

openclosed

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

syncDisabledrequired

boolean

updatedAtrequired

string

format: date-time

Variant 2SearchResponseStandardized search response with data, metadata, and query information

datarequired

Record<string, any>[]

Array of matching entities

metarequired

object

Pagination and result metadata

countrequired

number

Number of records returned in this response

executionTimerequired

number

Query execution time in milliseconds

hasMorerequired

boolean

Whether there are more records available

limitrequired

number

Maximum number of records requested

offsetrequired

number

Number of records skipped

totalrequired

number

Total number of matching records (before pagination)

Example Response

200 OK — application/json

[
  {
    "orderNumber": "string",
    "source": "etsy",
    "status": "open",
    "cancelledAt": "2025-01-15T12:00:00.000Z",
    "shippedAt": "2025-01-15T12:00:00.000Z",
    "customerId": "string",
    "integrationId": "string",
    "priceBucket": 1,
    "price": 1,
    "currency": "string",
    "externalId": "string",
    "externalUrl": "string",
    "sourceRef": "string",
    "note": "string",
    "deadline": "2025-01-15T12:00:00.000Z",
    "processedAt": "2025-01-15T12:00:00.000Z",
    "syncDisabled": true,
    "customMetadata": {},
    "id": "string",
    "storeId": "string",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
]