Shipments

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.

The shipment model

Properties

  • Name
    id
    Type
    string
    Readonly
    readonly
    Description
  • Name
    customer
    Type
    uuid
    Description
  • Name
    reference
    Type
    string
    Description
  • Name
    po_number
    Type
    string
    Description
  • Name
    order_external_reference
    Type
    array
    Description

    It's possible to fetch multiple shipments by providing multiple order external references.

  • Name
    shipment_external_reference
    Type
    string
    Description
  • Name
    created_at
    Type
    datetime
    Readonly
    readonly
    Description
  • Name
    modified_at
    Type
    datetime
    Readonly
    readonly
    Description
GET/wms/shipments/

List all shipments

Retrieves a collection of shipments. By default, the response contains short shipment information, but you can customize the response by specifying additional fields using the Expand header.

Optional attributes

Attribute NameTypeDescription
order_external_referencestring
Search for a specific order external reference.
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 Headers

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

Available Groups

The following groups can be used with the Expand header to include additional fields in the response:

Group NameDescription
shipmentsBase shipment information (default).
shipment_linesInclude all shipment line items.
shipment_colliInclude shipment colli (package) details.
shipment_labelsInclude shipment labels (e.g., tracking codes, URLs).
shipping_methodInclude shipment's shipping method information.
shipping_addressInclude the shipping address of the shipment.
serial_numbersInclude serial numbers for shipment line items (if applicable).
variantInclude variant details for shipment items (e.g., description, EAN, SKU).
administration_codeInclude additional administration codes.

Request

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

Response

[
{
    "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
},
{
    "id": "66606c93-edc7-45b6-a400-f5fee5729e9f",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "created_at": "2022-07-18T09:55:39+00:00",
    "order_external_reference": "TEST_HENNY_003",
    "shipment_external_reference": "EWHS-TEST_HENNY_003",
    "reference": "SHP00000000064",
    "po_number": null
}
]
GET/wms/shipments/:id/

Retrieve a shipment

Retrieves details for a specific shipment. By default, short shipment details are returned. You can expand the response by using the available groups in the Expand Header.

Request Headers

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

Available Groups

The following groups can be included to expand the response for detailed shipment information:

Group NameDescription
shipmentBase shipment information (default).
shipment_linesInclude all shipment line items.
shipment_colliInclude shipment colli (package) details.
shipment_labelsInclude shipment labels (e.g., tracking codes, URLs).
shipment_documentInclude associated shipment documents (e.g., PDFs).
shipping_addressInclude the shipping address of the shipment.
shipping_methodInclude shipment's shipping method information.
serial_numbersInclude serial numbers for shipment line items (if applicable).
variantInclude variant details for shipment items (e.g., description, EAN, SKU).
administration_codeInclude additional administration codes.
documentsInclude shipment documents and related metadata.
return_labelInclude return label details (if available).

Request

GET
/wms/shipments/:id/
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

{
    "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,
    "shipping_method": {
        "id": "7e808ac8-4167-11e9-92f0-0242ac140006",
        "shipper": "eWarehousing",
        "shipper_code": "ewarehousing",
        "code": "EWH_PICK_UP",
        "description": "eWarehousing afhaal order",
        "shipping_software": "ewh",
        "administration_code": "123"
    },
    "shipment_labels": [
        {
            "label_code": "ewarehousing-afhaal-order",
            "tracking_code": "ewh-pick-up",
            "tracking_url": "#"
        }
    ],
    "shipment_lines": [
        {
            "shipped_quantity": 1,
            "shipped_ean": "978020137962",
            "shipped_article_code": "VBP_A",
            "shipped_sku": "VBP_A",
            "serial_numbers": [],
            "variant": {
                "id": "f2894c16-399e-4ca1-9151-489775a6519c",
                "article_code": "VBP_A",
                "name": "Voorbeeld product - A",
                "description": "Voorbeeld product - A",
                "ean": "978020137962",
                "sku": "VBP_A",
                "hs_tariff_code": null,
                "height": 2,
                "depth": 3,
                "width": 1,
                "weight": 0,
                "expirable": false,
                "country_of_origin": null,
                "using_serial_numbers": false,
                "value": 15.95
            }
        }
    ],
    "shipping_address": {
        "addressed_to": "Henny Krijnen",
        "contact_person": null,
        "street": "Nijverheidsweg",
        "street2": null,
        "street_number": "27",
        "street_number_addition": null,
        "zipcode": "3274 KJ",
        "city": "Heinenoord",
        "country": "NL",
        "state": "Zuid holland",
        "phone_number": null,
        "mobile_number": "+31653282548",
        "fax_number": null,
        "email_address": null
    }
}

Return Labels

A return label is a label associated with a shipment, allowing for seamless return logistics. Return labels provide tracking information, such as tracking codes and URLs, and are typically provided as downloadable PDFs. The system provides endpoints to both retrieve and create return labels, making it easy to integrate return logistics into other workflows or systems.

When integrating with the return label API, it is important to handle error responses gracefully. Below are some likely scenarios:

  1. No Return Label Found (404): If no labels exist for a shipment, this is not an uncommon issue. The client may need to use the POST endpoint to create a new return label.

  2. Unsupported Label Service (417): Certain shipping methods or providers may not support return label generation. Be sure to verify shipping method compatibility before calling the API.

  3. 403 Forbidden: Access Denied: Ensure you have the correct permissions

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

Retrieve a return label for a Shipment

This endpoint retrieves a return label for a specific shipment. If the shipment has a previously generated return label, the system will return its details. This includes tracking information, the associated external reference, and a URL linking to the downloadable label PDF.

Request

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

Response

{
    "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",
    "url": "https://storage.googleapis.com/dev-eu-ewhs-wms/return-labels/EWHS/SHP00000000563-return-label.pdf?GoogleAccessId=ewhs-wms-dev-bucket%40wms-dev-kmkrkz.iam.gserviceaccount.com&Expires=1727969160&Signature=YSMeyFTXIEJXER1uqyedxi3ZU2vWoyKJ4z6pVhULburw51hb7wfmkYk%2F9aqsecEk80wJ6SYUeVnSTq18hPKdbA24JqxrzF2VLhvIIM1%2ByPA4c8S7ofhmKThFRpovXX5UcnUKI1luOwJwSXsALBR95INrU7j%2B8WkRIpIf5v%2BlVS1VE7CeQTbjEVlLGk%2BYJwVQICe4pVnir02AozPjYYcRrjPrMzqsBr8PCWeXxS6OJ9DMtJpAOP7fCbdMady7QPp%2FSptaJNMLFLj4WddAAn0PDkT7HoiH0VYD69CivPKHYP3pdXf2xO%2Fq6NugACXjOAL%2FMmfoWeH1VoWiIuDshKX74g%3D%3D",
    "created_at": "2024-10-03T13:43:47+00:00"
}
POST/wms/shipments/:id/return-label/

Create a return label for a Shipment

Creates a return label for a given shipment. If a return label already exists, it will be returned. Otherwise, the system will attempt to generate a new return label by interacting with the appropriate label generation service.

Request

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

Response

{
    "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",
    "url": "https://storage.googleapis.com/dev-eu-ewhs-wms/return-labels/EWHS/SHP00000000563-return-label.pdf?GoogleAccessId=ewhs-wms-dev-bucket%40wms-dev-kmkrkz.iam.gserviceaccount.com&Expires=1727969160&Signature=example_signature",
    "created_at": "2024-10-03T13:43:47+00:00"
}