Return labels

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

The return label model

Properties

  • Name
    id
    Type
    uuid
    Readonly
    readonly
    Description
  • Name
    external_reference
    Type
    string
    Description
    Derived from the shipment when created using shipment_id; otherwise, can be set via external_reference on create.
  • Name
    url
    Type
    string|null
    Description
    Signed URL to the label PDF. Null until requested/generated.
  • Name
    created_at
    Type
    datetime (ISO 8601)
    Readonly
    readonly
    Description
  • Name
    tracking_information
    Type
    array of TrackingInformation
    Description
  • Name
    sender_address
    Type
    SenderAddress|null
    Description

TrackingInformation

  • Name
    label_code
    Type
    string|null
    Description
  • Name
    tracking_code
    Type
    string|null
    Description
  • Name
    tracking_url
    Type
    string|null
    Description

SenderAddress (response)

  • Name
    addressed_to
    Type
    string
    Description
  • Name
    contact_person
    Type
    string|null
    Description
  • Name
    street
    Type
    string
    Description
  • Name
    street2
    Type
    string|null
    Description
  • Name
    street_number
    Type
    string
    Description
  • Name
    street_number_addition
    Type
    string|null
    Description
  • Name
    zipcode
    Type
    string
    Description
  • Name
    city
    Type
    string
    Description
  • Name
    country
    Type
    string
    Description
    ISO code or UUID reference
  • Name
    state
    Type
    string|null
    Description
  • Name
    phone_number
    Type
    string|null
    Description
  • Name
    mobile_number
    Type
    string|null
    Description
  • Name
    fax_number
    Type
    string|null
    Description
  • Name
    email_address
    Type
    string|null
    Description

SenderAddress (request: Create/Patch)

  • Name
    addressed_to
    Type
    string
    Description
  • Name
    contact_person
    Type
    string|null
    Description
  • Name
    street
    Type
    string
    Description
  • Name
    street2
    Type
    string|null
    Description
  • Name
    street_number
    Type
    string
    Description
  • Name
    street_number_addition
    Type
    string|null
    Description
  • Name
    zipcode
    Type
    string
    Description
  • Name
    city
    Type
    string
    Description
  • Name
    state
    Type
    string|null
    Description
  • Name
    country
    Type
    string
    Description
    ISO code (e.g., "NL") or UUID
  • Name
    phone_number
    Type
    string|null
    Description
  • Name
    mobile_number
    Type
    string|null
    Description
  • Name
    fax_number
    Type
    string|null
    Description
  • Name
    email_address
    Type
    string|null
    Description

Expanding responses

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

The Expand header only influences the fields returned in the response. It is not required for requests themselves. You may include it on any endpoint if you want to expand the response payload.

Request Headers

Header NameTypeRequiredDescription
ExpandarrayNoComma-separated list of groups to include in the API response.

Available groups

Group NameDescription
shipmentInclude the related shipment details when the return label is linked to a shipment.
GET/wms/return-labels/

List all return labels

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

Optional query parameters

Attribute NameTypeDescription
fromdate
Accepts a date in the format YYYY-MM-DD (2020-01-31).
todate
Accepts a date in the format YYYY-MM-DD (2020-01-31).
limitinteger
Limit the number of results.
Default: 50
pagestring
The page number to retrieve.
directionstring
The default sorting direction.
Options: asc, desc
Default: desc
sortstring
The default sorting direction.
Options: reference, createdAt
Default: reference

Request

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

[
  {
    "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
    }
  }
]
GET/wms/return-labels/:id/

Retrieve a return label

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.

Request

GET
/wms/return-labels/:id/
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1 \
-H 'Expand: shipment'

{
  "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
  }
}
POST/wms/return-labels/

Create a return label

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 shipment_id together with a new shipping_method (override)
  • Using shipping_method and full sender_address (no shipment_id)

The sender_address object accepts ISO country codes (e.g., "NL"). When not using shipment_id, you may include external_reference to set your own reference. When shipment_id is provided, the external_reference is derived from the shipment and you should not include external_reference in the payload.

When you include shipment_id, the return label will be linked to that shipment. If no shipping_method is provided, the system will use the shipment's or your default return settings. The external_reference is derived from the shipment; do not include external_reference in the payload when using shipment_id.

Request — 1) Only shipment_id

POST
/wms/return-labels/
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"
}'

Request — 2) shipment_id + new shipping_method

POST
/wms/return-labels/
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",
  "shipping_method": "0ac0be56-c597-4c29-893a-83219849fe34"
}'

Request — 3) shipping_method + sender_address (no shipment_id)

POST
/wms/return-labels/
curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/return-labels/' \
-H 'Content-Type: application/json' \
--data-raw '{
  "shipping_method": "0ac0be56-c597-4c29-893a-83219849fe34",
  "external_reference": "mw_64f0df1a11a4",
  "sender_address": {
    "addressed_to": "Henny Krijnen",
    "street": "De Gagelrijzen",
    "street_number": "127",
    "street_number_addition": null,
    "street2": null,
    "zipcode": "4711PD",
    "city": "St.Willebrord",
    "state": null,
    "country": "NL",
    "phone_number": "+31653263698",
    "mobile_number": null,
    "fax_number": null,
    "email_address": null,
    "contact_person": null
  }
}'

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

The url remains null until a label is requested and generated.

PATCH/wms/return-labels/:id/

Update a return label

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.

Request

PATCH
/wms/return-labels/:id/
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"
  }
}'

{
  "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
  }
}
POST/wms/return-labels/:id/request

Request a return label

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

Request

POST
/wms/return-labels/:id/request
curl -X POST https://eu-dev.middleware.ewarehousing-solutions.com/wms/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1/request

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

{ "error": "MESSAGE" }
POST/wms/return-labels/:id/cancel

Cancel a return label

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.

Request

POST
/wms/return-labels/:id/cancel
curl -X POST https://eu-dev.middleware.ewarehousing-solutions.com/wms/return-labels/c7c0f8a9-3c2b-4b0b-9f02-2a3c47f0b7c1/cancel

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

{ "error": "MESSAGE" }

{ "error": "MESSAGE" }

{ "error": "MESSAGE" }

Status codes

  • 200 OK: Successfully executed (list, retrieve, update, request, cancel)
  • 201 Created: Successfully created (create)
  • 400 Bad Request: Business rule violations or invalid payload
  • 403 Forbidden: Missing role for the requested action
  • 404 Not Found: Return label not found
  • 412 Precondition Failed: Return label cannot be updated or canceled after it has been requested
  • 417 Expectation Failed: Unexpected errors

To include the related shipment in the response, use the Expand header with the group shipment.