Developer documentation

Return labels

Use the WMS Return Labels API to create, retrieve, update, request (generate), and cancel return shipping labels for your customers. All endpoints require authentication and an X-Customer-Code header.

Use the WMS Return Labels API to create, retrieve, update, request (generate), and cancel return shipping labels. All operations are scoped by the X-Customer-Code header.

**Quick links**

Go directly to: Retrieve a return label • Request (generate) • Create

How do I get a shipping_method id?

If you create a Return Label using a shipping method, you need the shipping method ID (UUID) for the carrier/service you want to use.

You can retrieve shipping methods via the Shipping Methods API:

List all shipping methods: GET /wms/shippingmethods/
Retrieve a specific shipping method: GET /wms/shippingmethods/:id/

Tip: Use query parameters such as code, shipper, or shipping_software to find the correct method for returns. See the examples on the Shipping methods page.

Go to the Shipping methods documentation→

Response models

These response models describe the objects returned by this resource.

The return label model

Top-level return label properties returned by the API.

Field	Description
`id` uuidOptional	Read-only.
`external_reference` stringOptional	Derived from the shipment when created using shipment_id; otherwise, can be set via external_reference on create.
`url` string\|nullOptional	Signed URL to the label PDF. Null until requested/generated.
`created_at` datetime (ISO 8601)Optional	Read-only.
`tracking_information` array of TrackingInformationOptional	-

TrackingInformation

Nested tracking objects inside `tracking_information`.

Field	Description
`label_code` string\|nullOptional	-
`tracking_code` string\|nullOptional	-
`tracking_url` string\|nullOptional	-

SenderAddress (response)

Address object returned by the API in `sender_address`.

Field	Description
`addressed_to` stringOptional	-
`contact_person` string\|nullOptional	-
`street` stringOptional	-
`street2` string\|nullOptional	-
`street_number` stringOptional	-

SenderAddress (request: Create/Patch)

Address shape accepted when creating or updating a return label.

Field	Description
`addressed_to` stringOptional	-
`contact_person` string\|nullOptional	-
`street` stringOptional	-
`street2` string\|nullOptional	-
`street_number` stringOptional	-

List all return labels

GET/wms/return-labels/

Retrieve a collection of return labels. By default you get base information; expand the response using the Expand header.

Try it

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

GET

Request attributes

Field	Description
`from` dateOptional	Accepts a date in the format YYYY-MM-DD.
`to` dateOptional	Accepts a date in the 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`.
`sort` stringOptional	Sorting field for the return label collection.

Request examplecURL

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

Response exampleJSON

[
  {
    "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
    "external_reference": "mw_64f0df1a11a4",
    "url": "https://files.example/signed/595253ae-3d35-4fac-a85a-6b01c46478d3/RL00000000001.pdf?...",
    "created_at": "2025-08-26T10:34:00+00:00",
    "tracking_information": [
      {
        "label_code": "RL00000000001",
        "tracking_code": "3SABC...",
        "tracking_url": "https://track.example/..."
      }
    ],
    "sender_address": {
      "addressed_to": "Henny Krijnen",
      "contact_person": null,
      "street": "De Gagelrijzen",
      "street2": null,
      "street_number": "127",
      "street_number_addition": null,
      "zipcode": "4711PD",
      "city": "St.Willebrord",
      "country": "NL",
      "state": null,
      "phone_number": "+31653263698",
      "mobile_number": null,
      "fax_number": null,
      "email_address": null
    }
  }
]

Retrieve a return label

GET/wms/return-labels/:id/

Retrieve details for a specific return label. Optionally include the linked shipment with the shipment expand group when the return label is linked to a shipment.

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/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1 \
  -H 'Expand: shipment'

Response exampleJSON

{
  "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
  "external_reference": "mw_64f0df1a11a4",
  "url": "https://files.example/signed/595253ae-3d35-4fac-a85a-6b01c46478d3/RL00000000001.pdf?...",
  "created_at": "2025-08-26T10:34:00+00:00",
  "tracking_information": [
    {
      "label_code": "RL00000000001",
      "tracking_code": "3SABC...",
      "tracking_url": "https://track.example/..."
    }
  ],
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "contact_person": null,
    "street": "De Gagelrijzen",
    "street2": null,
    "street_number": "127",
    "street_number_addition": null,
    "zipcode": "4711PD",
    "city": "St.Willebrord",
    "country": "NL",
    "state": null,
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null
  }
}

Create a return label

POST/wms/return-labels/

Create a new return label. You can create it in three ways:

- Using only
shipment_id
(derive shipping details from the shipment or your defaults)
- Using

Try it

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

POST

Request examplecURL

curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/return-labels/' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "shipment_id": "e710389a-5505-49d4-9b99-8314f3543427"
  }'

Response exampleJSON

{
  "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
  "external_reference": "mw_64f0df1a11a4",
  "url": null,
  "created_at": "2025-08-26T10:34:00+00:00",
  "tracking_information": [],
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "contact_person": null,
    "street": "De Gagelrijzen",
    "street2": null,
    "street_number": "127",
    "street_number_addition": null,
    "zipcode": "4711PD",
    "city": "St.Willebrord",
    "country": "NL",
    "state": null,
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null
  }
}

Update a return label

PATCH/wms/return-labels/:id/

Partially update a return label. Provide only the fields you want to change.

After performing the request action, a return label can no longer be updated. Attempts will result in HTTP 412 Precondition Failed.

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/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1/ \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "sender_address": {
      "city": "Breda",
      "country": "NL"
    }
  }'

Response exampleJSON

{
  "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
  "external_reference": "mw_64f0df1a11a4",
  "url": null,
  "created_at": "2025-08-26T10:34:00+00:00",
  "tracking_information": [],
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "contact_person": null,
    "street": "De Gagelrijzen",
    "street2": null,
    "street_number": "127",
    "street_number_addition": null,
    "zipcode": "4711PD",
    "city": "Breda",
    "country": "NL",
    "state": null,
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null
  }
}

Request a return label

POST/wms/return-labels/:id/request

Generate the return label file and tracking details for the given id. No request body.

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/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1/request

Response exampleJSON

{
  "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
  "external_reference": "mw_64f0df1a11a4.R",
  "url": "https://files.example/signed/595253ae-3d35-4fac-a85a-6b01c46478d3/RL00000000001.pdf?...",
  "created_at": "2025-08-26T10:34:00+00:00",
  "tracking_information": [
    {
      "label_code": "RL00000000001",
      "tracking_code": "3SABC...",
      "tracking_url": "https://track.example/..."
    }
  ],
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "contact_person": null,
    "street": "De Gagelrijzen",
    "street2": null,
    "street_number": "127",
    "street_number_addition": null,
    "zipcode": "4711PD",
    "city": "St.Willebrord",
    "country": "NL",
    "state": null,
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null
  }
}

Cancel a return label

POST/wms/return-labels/:id/cancel

Cancel a return label that has not yet been requested (generated). If the label has already been requested, the operation fails with HTTP 412 Precondition Failed. No request body. Returns the updated label state.

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/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1/cancel

Response exampleJSON

{
  "id": "c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1",
  "external_reference": "mw_64f0df1a11a4",
  "url": null,
  "created_at": "2025-08-26T10:34:00+00:00",
  "tracking_information": [],
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "contact_person": null,
    "street": "De Gagelrijzen",
    "street2": null,
    "street_number": "127",
    "street_number_addition": null,
    "zipcode": "4711PD",
    "city": "St.Willebrord",
    "country": "NL",
    "state": null,
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null
  }
}

Field	Description
`label_code` string\|nullOptional	-
`tracking_code` string\|nullOptional	-
`tracking_url` string\|nullOptional	-