Batch update order items

Path Parameters

orderId required

string

The order's unique identifier

Request Body

Array of item updates with item IDs and changes

RequestBody

Array of objects, each with:

changesrequired

object

Make all properties in T optional

customMetadataoptional

Record<string, any>

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

externalIdoptionalnullable

string

externalOrderIdoptionalnullable

string

externalProductIdoptionalnullable

string

externalSkuoptionalnullable

string

ignoredoptionalnullable

boolean

inputsoptionalnullable

Record<string, any>

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

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

quantityoptional

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

sourceoptionalnullable

enum

etsyshopifymanualebaytiktok-shopwoocommerceshipstationwix

statusoptionalnullable

string

itemIdrequired

string

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

Example Request

application/json

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

Response Schema

OrderItem[]

Array of OrderItem, each with:

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

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"
  }
]