Developer documentation

Orders

Use the Orders API to create, retrieve, update, and cancel orders. This page covers models (lines, shipping, documents, metadata) and endpoints to manage the order lifecycle, including statuses and international compliance fields (IOSS, EORI).

Response models

These models describe the objects returned by the API in successful responses. Expanded fields are only included when requested through the `expand` header.

The order model

The primary response object returned for order endpoints. It contains the order state, commerce fields, compliance data, and optionally expanded related objects such as shipping address, order lines, documents, and metadata.

FieldDescription
id
stringOptional
Read-only.
created_at
datetimeOptional
Read-only.
requested_delivery_date
datetimeOptional
Requested delivery date returned by the API.
customer
stringOptional
Read-only. Customer identifier returned by the API.
external_reference
stringOptional
External order reference from your upstream system.

The order line model

A single line within an order response. Each line resolves the requested article into a variant object and can optionally include serial numbers and line-level metadata when expanded.

FieldDescription
variant
variantOptional
Resolved variant object returned for the requested article code.
quantity
integerOptional
Ordered quantity.
description
stringOptional
Order line description.
serial_numbers
array of stringsOptional
Expanded serial numbers linked to the order line. Returned when `serial_numbers` is included in the `expand` header.
meta_data
objectOptional
Expanded key-value metadata attached to the order line. Returned when `order_line_meta_data` is included in the `expand` header.

The shipping address model

The expanded shipping destination returned on an order. This object contains the normalized recipient and address details stored for fulfillment.

FieldDescription
addressed_to
stringOptional
Recipient or company name.
contact_person
stringOptional
Contact person returned in the response object.
street
stringOptional
Street name.
street2
stringOptional
Additional street information.
street_number
stringOptional
House number.

The document model

A document attached to an order response, such as a packing slip, customs document, or shipping label. This model describes the metadata returned by the API for each linked document.

FieldDescription
id
stringOptional
Read-only document identifier.
title
stringOptional
Document title.
mime_type
stringOptional
Read-only.
quantity
integerOptional
Amount of times it will be printed
is_shipping_label
booleanOptional
Whether this document is marked as a shipping label.

The meta data model

Metadata is available on both order and order line responses. Add `meta_data` to the `expand` header to receive it in the response. New to the Expand header? See how it works, available groups, and request examples: [Expanding responses](/expanding-responses). Keys must be lowercase and should use `_` or `-` as separators.

FieldDescription
{key: value}
objectOptional
An object of key-value pairs.

List all orders

GET/wms/orders/

Retrieves a collection of orders.

Try it

Send a live request against the development middleware using your current API test session.

GET

Request attributes

FieldDescription
reference
stringOptional
Search for a specific reference.
external_reference
stringOptional
Search for a specific external reference.
external_id
stringOptional
Search for a specific external id.
status
stringOptional
Search for a specific status.
is_business_to_business
booleanOptional
Filter by business-to-business orders.
requested_delivery_date_gte
stringOptional
Accepts date format YYYY-MM-DD.
limit
integerOptional
Limit the number of results. Default is 50.
page
integerOptional
The page number to retrieve.
direction
stringOptional
Sort direction. Options: `asc` or `desc`. Default is `desc`.
sort
stringOptional
Sort field. Options: `createdAt`, `status`, `modifiedAt`, or `requestedDeliveryDate`. Default is `createdAt`.
Request examplecURL
curl 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/?external_reference=WEB-10001&status=created&limit=10'
Response exampleJSON
[
  {
    "id": "f9c392ac-6335-4828-85e2-fae7f82ff636",
    "created_at": "2021-11-12T14:05:43+00:00",
    "requested_delivery_date": "2018-11-19T00:00:00+00:00",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "external_reference": "WEB-10001",
    "external_id": "order-10001",
    "po_number": "841612",
    "reference": "ORD00000000001",
    "status": "created",
    "shipping_method": "9eb93dd6-6929-4b91-8419-8a619a72905b",
    "currency": "EUR"
  }
]

Retrieve an order

GET/wms/orders/:id/

Retrieve a single order.

Try it

Send a live request against the development middleware using your current API test session.

GET

Path parameters

Request examplecURL
curl 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/e710389a-5505-49d4-9b99-8314f3543427/' -H 'expand: shipping_address,order_lines,documents,meta_data,order_line_meta_data,serial_numbers'
Response exampleJSON
{
  "id": "c9165f93-8301-4aaa-9f64-27f191c0c778",
  "created_at": "2022-02-11T09:32:12+00:00",
  "requested_delivery_date": "2022-02-14T00:00:00+00:00",
  "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
  "external_reference": "WEB-10001",
  "external_id": "order-10001",
  "po_number": "841612",
  "reference": "ORD00000003029",
  "status": "created",
  "shipping_method": "9eb93dd6-6929-4b91-8419-8a619a72905b",
  "language": "en",
  "note": "Leave the parcel at the front desk.",
  "customer_note": "Gift order",
  "order_amount": 4599,
  "assured_amount": 4599,
  "inco_terms": "DAP",
  "currency": "EUR",
  "shipping_address": {
    "addressed_to": "eWarehousing Solutions",
    "contact_person": "Warehouse Team",
    "street": "Nijverheidsweg",
    "street_number": "27",
    "zipcode": "3331MB",
    "city": "Zwijndrecht",
    "country": "NL",
    "email_address": "outbound@example.com"
  },
  "order_lines": [
    {
      "variant": {
        "id": "87557e7a-4f4d-44eb-bbf1-c9d83df90099",
        "article_code": "default_variant_b_id",
        "name": "default_variant_b_id"
      },
      "quantity": 7,
      "description": "Blue T-shirt size M",
      "serial_numbers": [
        "SN-0001",
        "SN-0002"
      ],
      "meta_data": {
        "gift_wrap": "true"
      }
    }
  ],
  "documents": [
    {
      "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
      "title": "packing-slip.pdf",
      "mime_type": "application/pdf",
      "quantity": 1,
      "is_shipping_label": false,
      "order_price": 0
    }
  ],
  "meta_data": {
    "sales_channel": "webshop",
    "priority": "normal"
  }
}

Create an order

POST/wms/orders/

This endpoint allows you to add a new order.

Request vs response: you send article_code in order line requests, but the API returns resolved variant objects in the response.

Try it

Send a live request against the development middleware using your current API test session.

POST

Request attributes

FieldDescriptionExample value
external_reference
stringRequired
External order reference.
external_id
stringOptional
Unique order identifier from your source system.
po_number
stringOptional
Purchase order number.
order_lines
array of order linesRequired
One or more order line payloads.See nested fields below
Expand order_lines→
order_lines[].article_codestringRequired

Universal identifier that matches against variant article_code, EAN, or SKU to identify the variant.

order_lines[].quantityintegerRequired

Ordered quantity.

order_lines[].descriptionstringRequired

Human-readable order line description.

order_lines[].pricenumberOptional

Unit price for the order line.

order_lines[].meta_dataobjectOptional

Additional key-value metadata for the order line.

shipping_method
uuidOptional
Shipping method identifier.
shipping_address
ShippingAddressRequired
Shipping address object.See nested fields below
Expand shipping_address→
shipping_address.streetstringRequired

Street name.

shipping_address.street_numberstringOptional

House number.

shipping_address.street_number_additionstringOptional

House number addition.

shipping_address.street2stringOptional

Additional street information.

shipping_address.citystringRequired

City name.

shipping_address.statestringOptional

State or province.

shipping_address.countrystringRequired

ISO country code.

shipping_address.zipcodestringRequired

Postal or ZIP code. Not mandatory for some countries such as `HK` or `AE`.

shipping_address.phone_numberstringOptional

Phone number.

shipping_address.mobile_numberstringOptional

Mobile phone number.

shipping_address.fax_numberstringOptional

Fax number.

shipping_address.invalidbooleanOptional

Manually mark the address as invalid.

shipping_address.addressed_tostringRequired

Recipient or company name.

shipping_contactperson
stringRequired
Contact person for the shipment.
shipping_email
stringOptional
Shipping email address.
requested_delivery_date
dateRequired
Requested delivery date.
documents
array of documentsOptional
Attached documents.Not editable here
ioss_number
stringOptional
IOSS number of the sender.
eori_number
stringOptional
EORI number of the sender.
vat_number
stringOptional
VAT number of the sender.
inbound_vat_number
stringOptional
GB VAT number needed for shipments from Europe to GB.
inbound_eori_number
stringOptional
GB EORI number needed for shipments from Europe to GB.
meta_data
objectOptional
Additional order-level key-value metadata.
language
stringOptional
Language code.
note
stringOptional
Internal note.
customer_note
stringOptional
Customer-facing note.
order_amount
integerOptional
Value of order in cents.
assured_amount
integerOptional
Assured amount in cents.
inco_terms
stringOptional
Options: `DAP` or `DDP`.
currency
stringOptional
Currency code.
Request examplecURL
curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/' -H 'Content-Type: application/json' --data-raw '{
  "external_reference": "WEB-10001",
  "external_id": "order-10001",
  "po_number": "PO-841612",
  "shipping_contactperson": "Warehouse Team",
  "shipping_email": "outbound@example.com",
  "requested_delivery_date": "2026-04-18",
  "note": "Leave the parcel at the front desk.",
  "customer_note": "Gift order",
  "language": "en",
  "currency": "EUR",
  "order_amount": 4599,
  "assured_amount": 4599,
  "meta_data": {
    "sales_channel": "webshop",
    "priority": "normal"
  },
  "shipping_address": {
    "addressed_to": "eWarehousing Solutions",
    "street": "Nijverheidsweg",
    "street_number": "27",
    "zipcode": "3331MB",
    "city": "Zwijndrecht",
    "country": "NL"
  },
  "order_lines": [
    {
      "article_code": "default_variant_b_id",
      "quantity": 2,
      "description": "Blue T-shirt size M",
      "price": 2299,
      "meta_data": {
        "gift_wrap": "true"
      }
    }
  ]
}'
Response exampleJSON
{
  "id": "8faf6cd6-28e7-4e44-a258-4e927d8e680c",
  "created_at": "2026-04-17T14:36:42+00:00",
  "requested_delivery_date": "2026-04-18T00:00:00+00:00",
  "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
  "external_reference": "WEB-10001",
  "external_id": "order-10001",
  "po_number": "PO-841612",
  "reference": "ORD00000005939",
  "status": "created",
  "shipping_method": "9eb93dd6-6929-4b91-8419-8a619a72905b",
  "language": "en",
  "note": "Leave the parcel at the front desk.",
  "customer_note": "Gift order",
  "order_amount": 4599,
  "assured_amount": 4599,
  "currency": "EUR"
}

Update an order

PATCH/wms/orders/:id/

This endpoint allows you to perform an update on an order.

Updating the order_lines will delete the previous order lines.

Try it

Send a live request against the development middleware using your current API test session.

PATCH

Path parameters

Request attributes

FieldDescriptionExample value
po_number
stringOptional
Purchase order number.
order_lines
array of order linesOptional
When updating order lines, use the same format as creating orders.See nested fields below
Expand order_lines→
order_lines[].article_codestringOptional

Universal identifier that matches against variant article_code, EAN, or SKU to identify the variant.

order_lines[].quantityintegerOptional

Ordered quantity.

order_lines[].descriptionstringOptional

Order line description.

order_lines[].pricenumberOptional

Unit price for the order line.

order_lines[].meta_dataobjectOptional

Additional key-value metadata for the line.

shipping_method
uuidOptional
Shipping method identifier.
shipping_address
ShippingAddressOptional
Shipping address object.See nested fields below
Expand shipping_address→
shipping_address.streetstringOptional

Street name.

shipping_address.street_numberstringOptional

House number.

shipping_address.street_number_additionstringOptional

House number addition.

shipping_address.street2stringOptional

Additional street information.

shipping_address.citystringOptional

City name.

shipping_address.statestringOptional

State or province.

shipping_address.countrystringOptional

ISO country code.

shipping_address.zipcodestringOptional

Postal or ZIP code.

shipping_address.phone_numberstringOptional

Phone number.

shipping_address.mobile_numberstringOptional

Mobile phone number.

shipping_address.fax_numberstringOptional

Fax number.

shipping_address.invalidbooleanOptional

Manually mark the address as invalid.

shipping_address.addressed_tostringOptional

Recipient or company name.

shipping_contactperson
stringOptional
Contact person for the shipment.
shipping_email
stringOptional
Shipping email address.
requested_delivery_date
dateOptional
Requested delivery date.
documents
array of documentsOptional
Attached documents.Not editable here
ioss_number
stringOptional
IOSS number of the sender.
eori_number
stringOptional
EORI number of the sender.
vat_number
stringOptional
VAT number of the sender.
inbound_vat_number
stringOptional
GB VAT number needed for shipments from Europe to GB.
inbound_eori_number
stringOptional
GB EORI number needed for shipments from Europe to GB.
meta_data
objectOptional
Additional metadata key-value pairs.
language
stringOptional
Language code.
note
stringOptional
Internal note.
customer_note
stringOptional
Customer-facing note.
order_amount
integerOptional
Value of order in cents.
assured_amount
integerOptional
Assured amount in cents.
inco_terms
stringOptional
Options: `DAP` or `DDP`.
currency
stringOptional
Currency code.
Request examplecURL
curl -X PATCH https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/774bf6ee-90cf-11e9-b36d-0242ac120005/ -H 'Content-Type: application/json' --data-raw '{
  "note": "Leave the parcel at the neighbors if needed.",
  "shipping_email": "outbound@example.com",
  "meta_data": {
    "priority": "high"
  },
  "order_lines": [
    {
      "article_code": "default_variant_b_id",
      "description": "Blue T-shirt size M",
      "quantity": 3,
      "price": 2299
    }
  ]
}'
Response exampleJSON
{
  "id": "4fdb3055-4b1d-4352-96d5-2a89f9f50680",
  "external_reference": "WEB-10001",
  "external_id": "order-10001",
  "po_number": "PO-841612",
  "status": "created",
  "note": "Leave the parcel at the neighbors if needed.",
  "shipping_method": "9eb93dd6-6929-4b91-8419-8a619a72905b"
}

Cancel an order

PATCH/wms/orders/:id/cancel/

This endpoint allows you to cancel an order.

The order can only be canceled while the order's status is one of:
- created
- planned
- invalid_address

Try it

Send a live request against the development middleware using your current API test session.

PATCH

Path parameters

Request examplecURL
curl -X PATCH https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/774bf6ee-90cf-11e9-b36d-0242ac120005/cancel/

List all order documents

GET/wms/orders/:id/documents/

List all order documents.

Use the generic Documents resource to retrieve documents by ID.

Try it

Send a live request against the development middleware using your current API test session.

GET

Path parameters

Request examplecURL
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/184c47d4-d3ee-4412-b156-ce5a4518d641/documents/
Response exampleJSON
[
  {
    "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
    "title": "customs_file_en.pdf",
    "mime_type": "application/pdf",
    "quantity": 1
  }
]

Retrieve an order document

GET/wms/orders/:id/documents/:documentId/

**[deprecated] Use the [/wms/documents/:id](/resources/documents#retrieve-a-document) endpoint instead**

Retrieve an order document.

Try it

Send a live request against the development middleware using your current API test session.

GET

Path parameters

Request examplecURL
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/184c47d4-d3ee-4412-b156-ce5a4518d641/documents/af7c1fe6-d669-414e-b066-e9733f0de7a8/
Response exampleJSON
{
  "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
  "title": "customs_file.pdf",
  "mime_type": "application/pdf",
  "quantity": 1
}

Add a document to an order

POST/wms/orders/:id/documents/

This endpoint allows you to add a document to an existing order.

Try it

Send a live request against the development middleware using your current API test session.

POST

Path parameters

Request examplecURL
curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/3f2a00b4-ce1d-473b-bacb-e6e12303244b/documents/' -H 'Content-Type: application/json' --data-raw '{
  "file": "base64 encoded string",
  "title": "my_label",
  "quantity": 1,
  "order_price": 115,
  "shipping_label": false
}'
Response exampleJSON
{
  "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
  "title": "customs_file.pdf",
  "mime_type": "application/pdf",
  "quantity": 1
}