Get all order items

GET /v1/order-items

List all order items across all orders in the store

Requires: order.view

Query Parameters

orderId optional

string

Filter on orderId. A bare value is an exact match (orderId=value); use orderId.<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.

skuId optional

string

Filter on skuId. A bare value is an exact match (skuId=value); use skuId.<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.

quantity optional

string

Filter on quantity. A bare value is an exact match (quantity=value); use quantity.<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.

inputs optional

string

Filter on inputs. A bare value is an exact match (inputs=value); use inputs.<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.

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.

externalOrderId optional

string

Filter on externalOrderId. A bare value is an exact match (externalOrderId=value); use externalOrderId.<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.

externalProductId optional

string

Filter on externalProductId. A bare value is an exact match (externalProductId=value); use externalProductId.<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.

externalSku optional

string

Filter on externalSku. A bare value is an exact match (externalSku=value); use externalSku.<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.

originalSku optional

string

Original SKU identifier sent when creating the order item (sku or externalSku), null if skuId was provided directly

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.

ignored optional

string

Filter on ignored. A bare value is an exact match (ignored=value); use ignored.<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.

processedStatus optional

string

Filter on processedStatus. A bare value is an exact match (processedStatus=value); use processedStatus.<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.

skuConfig optional

string

Filter on skuConfig. A bare value is an exact match (skuConfig=value); use skuConfig.<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.

resolutionNote optional

string

Describes why SKU or variant resolution failed, null when resolved successfully

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.

Response Schema

OrderItem[] | SearchResponse

Variant 1OrderItem[]

createdAtrequired

string

format: date-time

customMetadataoptional

Record<string, any>

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

externalIdoptionalnullable

string

externalOrderIdoptionalnullable

string

externalProductIdoptionalnullable

string

externalSkuoptionalnullable

string

idrequired

string

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

ignoredoptionalnullable

boolean

inputsoptionalnullable

Record<string, any>

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

orderIdrequired

string

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

originalSkuoptionalnullable

string

Original SKU identifier sent when creating the order item (sku or externalSku), null if skuId was provided directly

processedAtoptionalnullable

string

format: date-time

processedStatusoptionalnullable

"unprocessed" | "processed"

unprocessedprocessed

quantityrequired

number

min: 1

resolutionNoteoptionalnullable

object

Structured note describing why SKU or variant resolution failed. Stored as a dedicated column on order_items for easy querying.

messagerequired

string

occurredAtrequired

number

Timestamp of when this failure occurred

retriablerequired

boolean

Whether this failure can be retried (e.g., API errors are retriable, missing SKUs are not)

typerequired

"variant_enrichment_failed" | "sku_not_found" | "ambiguous_match"

variant_enrichment_failedsku_not_foundambiguous_match

skuConfigoptionalnullable

object

SKU configuration stored with order items Contains only the configuration overrides, not the SKU reference

freeTextOptionIdsoptional

string[]

Options whose selected value is a buyer's free-text answer rather than one of the option's defined values. A personalization question can reuse a variant option (same name), and its arbitrary answers must not be flagged as invalid values during reconciliation.

linkedPartConfigsoptional

Record<string, object>

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

personalizationAnswerKeysoptional

string[]

selectedOptions keys the integration wrote from buyer personalization answers (as opposed to regular variation selections). Only these may be treated as free text when they land on a variant option; an unmatched regular variation value must still fail validation.

selectedOptionsoptional

Record<string, string>

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

skuIdrequirednullable

string

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

sourceoptionalnullable

enum

etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix

statusoptionalnullable

string

storeIdrequired

string

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

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

[
  {
    "orderId": "string",
    "skuId": "string",
    "source": "etsy",
    "quantity": 1,
    "inputs": {},
    "status": "string",
    "externalId": "string",
    "externalOrderId": "string",
    "externalProductId": "string",
    "externalSku": "string",
    "originalSku": "string",
    "processedAt": "2025-01-15T12:00:00.000Z",
    "ignored": true,
    "processedStatus": "unprocessed",
    "skuConfig": {
      "linkedPartConfigs": {},
      "selectedOptions": {},
      "freeTextOptionIds": [
        "string"
      ],
      "personalizationAnswerKeys": [
        "string"
      ]
    },
    "resolutionNote": {
      "type": "variant_enrichment_failed",
      "message": "string",
      "retriable": true,
      "occurredAt": 1
    },
    "customMetadata": {},
    "id": "string",
    "storeId": "string",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
]