Skip to navigation
API ReferenceOrders

Bulk Update Instructions

View as Markdown

Sets the packing instructions and/or special SKU instructions on multiple shipments in a single request.

Each instruction field is optional, and omitting a field is different from sending an empty one:

  • Omit the field, or send null, to leave that instruction unchanged.
  • Send an empty string to clear that instruction.

At least one of the two must be provided with a non-null value — a request that omits both, or sends null for both, is rejected with 400 INVALID_PARAMETER. {"packing_instruction": null} counts as providing nothing.

Each value is limited to 500 characters, measured after leading and trailing whitespace is removed. Whitespace padding around a 500-character instruction is therefore accepted.

shipment_ids is de-duplicated before the 250-shipment maximum is applied, and the response contains one result per unique id, in request order.

Instructions apply to B2B, SPS B2B, drop ship, kitting and inventory transfer shipments (including Amazon FBA). Direct-to-consumer shipments do not carry packing or SKU instructions.

Instructions can only be changed while a shipment is still editable. A shipment whose order type does not support instructions, that has been cancelled, cleanswept, shipped or completed, or that has already been assigned a tracking number, is reported as a per-shipment BUSINESS_RULE_VIOLATION rather than failing the whole request. A shipment that does not exist, or that belongs to another merchant, is reported as NOT_FOUND.

Submitting a value a shipment already has is a successful no-op: nothing is written and no audit entry is recorded.

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Request

This endpoint expects an object.
shipment_idslist of longsRequired

Shipment IDs to update the instructions for. Duplicates are ignored, and the 250 maximum applies to the de-duplicated list.

packing_instructionstring or nullOptional

Packing instructions for the shipments. Omit this field to leave the existing packing instructions unchanged; send an empty string to clear them. At least one of packing_instruction or sku_instruction must be provided with a non-null value. Leading and trailing whitespace is removed, and the 500-character limit applies to what remains.

sku_instructionstring or nullOptional

Special SKU instructions for the shipments. Omit this field to leave the existing SKU instructions unchanged; send an empty string to clear them. At least one of packing_instruction or sku_instruction must be provided with a non-null value. Leading and trailing whitespace is removed, and the 500-character limit applies to what remains.

Response

OK
summaryobject
Summary of the bulk operation results
resultslist of objects or nullOptional

Per-shipment results of the bulk operation

Errors

400
Bad Request Error