Developer documentation

Shipments

Use the Shipments API to list shipments and retrieve details. Return label actions on this controller are deprecated; use the Return Labels API instead.

A Shipment is an order that has been shipped. The API allows users to retrieve both collections of shipments and specific shipment details with customizable responses by using the **Expand Header**.

**Expanding responses**

New to the Expand header? See how it works, available groups, and request examples: Expanding responses.

**Related resources**

• Create and manage orders: Orders

• Retrieve and manage documents: Documents

Return labels

Return labels on shipment endpoints are deprecated and kept for backward compatibility only. Prefer the dedicated Return Labels API.

**Deprecation**

Use the dedicated Return Labels API instead:

• Retrieve: GET /wms/return-labels/:id/

• Create: POST /wms/return-labels/

• Docs: /resources/return-labels

Response models

These response models describe the objects returned by this resource.

Shipment model

Core shipment fields returned by the API.

Field	Description
`id` stringRequired	Unique shipment id.
`customer` uuidRequired	Customer id that owns the shipment.
`reference` stringRequired	Human-readable shipment reference.
`po_number` string\|nullOptional	Purchase order number when provided.
`order_external_reference` arrayOptional	One or multiple order external references.

List all shipments

GET/wms/shipments/

Retrieves a collection of shipments.

By default, this returns short shipment data.
Use the Expand header to include extra groups.

Try it

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

GET

Request headers

Field	Description
`Expand` arrayOptional	Comma-separated list of groups to include in the response.

Request attributes

Field	Description
`from` dateOptional	Accepts date format YYYY-MM-DD.
`to` dateOptional	Accepts date format YYYY-MM-DD.
`limit` integerOptional	Maximum amount of results (default 50).
`page` integerOptional	Page number (works with limit).
`direction` stringOptional	Sort direction. Options asc or desc.
`sort` stringOptional	Sort field. Options reference or createdAt.

Available groups

Field	Description
`shipments`	Base shipment information (default).
`shipment_lines`	Include all shipment line items.
`shipment_colli`	Include shipment package details.
`shipment_labels`	Include shipment labels and tracking references.
`shipping_method`	Include shipping method information.
`shipping_address`	Include shipping address details.
`serial_numbers`	Include serial numbers for shipment lines.
`variant`	Include variant details for shipment lines.
`administration_code`	Include administration code fields.

Request examplecURL

curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/shipments/

Response example (200 OK)JSON

[
  {
    "id": "9bfcf441-b32a-4093-b5d7-6c64cef384a7",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "created_at": "2022-03-08T11:46:44+00:00",
    "order_external_reference": "perf_639068750747",
    "shipment_external_reference": "EWHS-perf_639068750747",
    "reference": "SHP00000000001",
    "po_number": null
  }
]

Retrieve a shipment

GET/wms/shipments/:id/

Retrieves one shipment by id.

By default, short shipment details are returned.
Add groups in Expand to include related resources.

Try it

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

GET

Path parameters

Request headers

Field	Description
`Expand` arrayOptional	Comma-separated list of groups to include.

Request attributes

Field	Description
`id` uuidRequired	Shipment id in the request path.

Available groups

Field	Description
`shipment`	Base shipment information (default).
`shipment_lines`	Include all shipment line items.
`shipment_colli`	Include shipment package details.
`shipment_labels`	Include shipment labels and tracking references.
`shipment_document`	Include associated shipment documents.
`shipping_address`	Include shipping address details.
`shipping_method`	Include shipping method details.
`serial_numbers`	Include serial numbers for shipment lines.
`variant`	Include variant details for shipment lines.
`administration_code`	Include administration code fields.
`documents`	Include document metadata.
`return_label`	Include return label details when available.

Request examplecURL

curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/shipments/e710389a-5505-49d4-9b99-8314f3543427 \
-H 'Expand: shipment_lines,shipment_labels,shipping_address,shipping_method,serial_numbers,variant,administration_code'

Response example (200 OK)JSON

{
  "id": "c27f2a12-fcc5-4bf7-9b40-537c96f1bbd5",
  "customer": "53b5a543-129a-403c-9a6e-3d9c525ffa5b",
  "created_at": "2022-02-11T14:12:59+00:00",
  "order_external_reference": "MW_ORD_001",
  "shipment_external_reference": null,
  "reference": "SHP00000000001",
  "po_number": null
}

[deprecated] Retrieve return label for a shipment

GET/wms/shipments/:id/return-label

Retrieves the return label for a shipment.

Deprecated: use the Return Labels API instead.
Replacement: GET /wms/return-labels/:id/
See Retrieve a return label.

Try it

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

GET

Path parameters

Request attributes

Field	Description
`id` uuidRequired	Shipment id in the request path.

Request examplecURL

curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/shipments/1ef24af0-e54d-6a4e-9a76-9fed48b18b39/return-label

Response example (200 OK)JSON

{
  "id": "8ced0144-d45e-4990-a833-50f95687fe98",
  "tracking_information": [
    {
      "label_code": "LENGTH_001_DHLEX.R",
      "tracking_code": "JVGL0576851000003704",
      "tracking_url": "https://my.dhlparcel.nl/home/tracktrace/JVGL0576851000003704/3274+KJ?lang=nl_NL"
    }
  ],
  "external_reference": "LENGTH_001_DHLEX.R",
  "created_at": "2024-10-03T13:43:47+00:00"
}

[deprecated] Create return label for a shipment

POST/wms/shipments/:id/return-label/

Creates a return label for a shipment.

Deprecated: use the Return Labels API instead.
Replacement: POST /wms/return-labels/
See Create a return label.

Try it

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

POST

Path parameters

Request attributes

Field	Description
`id` uuidRequired	Shipment id in the request path.

Request examplecURL

curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/shipments/1ef24af0-e54d-6a4e-9a76-9fed48b18b39/return-label

Response example (200 OK)JSON

{
  "id": "8ced0144-d45e-4990-a833-50f95687fe98",
  "tracking_information": [
    {
      "label_code": "LENGTH_001_DHLEX.R",
      "tracking_code": "JVGL0576851000003704",
      "tracking_url": "https://my.dhlparcel.nl/home/tracktrace/JVGL0576851000003704/3274+KJ?lang=nl_NL"
    }
  ],
  "external_reference": "LENGTH_001_DHLEX.R",
  "created_at": "2024-10-03T13:43:47+00:00"
}