Splitting Orders into multiple Shipments

Our default process assumes every Order is a single Shipment. However, in specific cases you might have to ship the Order in multiple packages, for example because the physical items are in different locations. In this case you can split the Order into multiple Shipments.

Note

The complete Shipments feature is being rolled out to pilot partners, and will be made generally available in the future. For now, please contact your integration manager if you are interested in splitting an Order into multiple Shipments.

Warning

A single order should only be fufilled with the process here OR the Order Line level process. Mixing these processes to fulfill a single Order is not supported.

Initial shipment

Each Order will have an initial Shipment assigned. This Shipment contains all Order Lines of the Order and might look something like this:

{
    "shipment_id": "580b6fd0-c976-499d-9f5e-30b1413558b5",
    "shipment_number": "1",
    "order_lines": [
        {
            "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
        },
        {
            "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
        },
        {
            "order_line_id": "bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c"
        },
        {
            "order_line_id": "8ec1dc26-ae49-486e-a9ea-922ea76b023b"
        }
    ],
    "status": "initial",
    "created_at": "2025-01-10T12:29:20.946108Z",
    "modified_at": "2025-01-10T12:29:20.946108Z"
}

See the Shipments Reference and Orders API OpenAPI Reference on how to retrieve the Shipment objects.

Creating a separate Shipment

You can create new Shipments in addition to the initial one by using this endpoint:

POST merchants/{merchant_ID}/orders/{order_ID}/shipments

You need to provide a JSON payload containing the Order Lines you want to add to the Shipment as well as a weight:

{
    "order_lines": [
        {
            "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
        },
        {
            "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
        }
    ],
    "weight": {
        "value": 500,
        "unit": "g"
    }
}

This is a minimal example and other attributes can be provided, see the Orders API OpenAPI Reference on how to create new Shipments.

While it's required to add a weight to a new shipment, the initial Shipment does not have a weight. We recommend adding a weight to every Shipment (as we do in the example below) before marking it as shipped to make sure it complies with the carrier integration you might have though Zalando. In case the weight of the Shipment is unknown the weight can be estimated or you can fallback to a default weight.

After creation of the Shipment the Order Lines passed will be moved from the initial Shipment to a new Shipment. This means the Order will now have two Shipments like below:

[
    {
        "shipment_id": "580b6fd0-c976-499d-9f5e-30b1413558b5",
        "shipment_number": "1",
        "order_lines": [
            {
                "order_line_id": "bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c"
            },
            {
                "order_line_id": "8ec1dc26-ae49-486e-a9ea-922ea76b023b"
            }
        ],
        "status": "initial",
        "created_at": "2025-01-10T12:29:20.946108Z",
        "modified_at": "2025-01-10T12:29:20.946108Z"
    },
    {
        "shipment_id": "94b159ab-1349-4955-87fe-0132ba267e45",
        "shipment_number": "2",
        "order_lines": [
            {
                "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
            },
            {
                "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
            }
        ],
        "weight": {
            "value": 500,
            "unit": "g"
        },
        "status": "initial",
        "created_at": "2025-01-10T13:29:20.946108Z",
        "modified_at": "2025-01-10T13:29:20.946108Z"
    }
]

Note

Once a second Shipment is created it's no longer possible to update the tracking information on an Order. You now have to provide tracking information for each individual Shipment instead.

Updating a Shipment

Apart from the status of the Shipment all fields can be provided during creation but it can also be applied afterwards by updating the Shipment. Let's look at how you can ship the initial Shipment by updating it with all required and recommended information and updating its status. We can do so by calling this endpoint:

PATCH merchants/{merchant_ID}/orders/{order_ID}/shipments/580b6fd0-c976-499d-9f5e-30b1413558b5

With a body like this:

{
    "order_lines": [
        {
            "order_line_id": "bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c",
            "merchant_specified_identifier": {
                "type": "UPOS-15",
                "value": "ABC"
            }
        },
        {
            "order_line_id": "8ec1dc26-ae49-486e-a9ea-922ea76b023b",
            "merchant_specified_identifier": {
                "type": "UPOS-15",
                "value": "DEF"
            }
        }
    ],
    "tracking_number": "tracking-number-1234",
    "return_tracking_number": "return-tracking-number-5678",
    "outbound_logistic_center_id": "587b5672-bddc-4236-936c-45de0df414c6",
    "weight": {
        "value": 100,
        "unit": "g"
    },
    "status": "shipped"
}

Note

You can make separate calls to update the Shipment, however we recommend to make all changes in the same call (as done in this example). If you do decide to make updates with separate calls ensure to wait 5 seconds after the last update before marking the Shipment as shipped to prevent the updates from being processed out-of-sequence, which can cause the values not to be applied correctly with a potential negative impact on your CXM KPIs.

Now the Shipments on the Order will look like this:

[
    {
        "shipment_id": "580b6fd0-c976-499d-9f5e-30b1413558b5",
        "shipment_number": "1",
        "order_lines": [
            {
                "order_line_id": "bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c",
                "merchant_specified_identifier": {
                    "type": "UPOS-15",
                    "value": "ABC"
                }
            },
            {
                "order_line_id": "8ec1dc26-ae49-486e-a9ea-922ea76b023b",
                "merchant_specified_identifier": {
                    "type": "UPOS-15",
                    "value": "DEF"
                }
            }
        ],
        "weight": {
            "value": 100,
            "unit": "g"
        },
        "tracking_number": "tracking-number-1234",
        "return_tracking_number": "return-tracking-number-5678",
        "outbound_logistic_center_id": "587b5672-bddc-4236-936c-45de0df414c6",
        "status": "shipped",
        "created_at": "2025-01-10T12:29:20.946108Z",
        "modified_at": "2025-01-10T14:29:20.946108Z"
    },
    {
        "shipment_id": "94b159ab-1349-4955-87fe-0132ba267e45",
        "shipment_number": "2",
        "order_lines": [
            {
                "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
            },
            {
                "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
            }
        ],
        "weight": {
            "value": 500,
            "unit": "g"
        },
        "status": "initial",
        "created_at": "2025-01-10T13:29:20.946108Z",
        "modified_at": "2025-01-10T13:29:20.946108Z"
    }
]

When looking at the Order Lines you will see that both Order Lines on the Shipment (bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c and 8ec1dc26-ae49-486e-a9ea-922ea76b023b) now have status shipped and a merchant_specified_identifier defined.

Updating the Order Lines within a Shipment

It's not possible to change the assigned Order Lines on an already existing Shipment through the PATCH API. If Order Lines have to be moved to another Shipment create a new Shipment while assigning all the expected Order Lines instead. To demonstrate this let's move all Order Lines from the second Shipment to a new Shipment. Call the Shipment creation endpoint:

POST merchants/{merchant_ID}/orders/{order_ID}/shipments

With this payload:

{
    "order_lines": [
        {
            "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
        },
        {
            "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
        }
    ],
    "weight": {
        "value": 250,
        "unit": "g"
    }
}

Now the shipments on the Order will look like this:

[
    {
        "shipment_id": "580b6fd0-c976-499d-9f5e-30b1413558b5",
        "shipment_number": "1",
        "order_lines": [
            {
                "order_line_id": "bbe5dbe2-ff5e-4459-993d-8f8f9c97e84c"
            },
            {
                "order_line_id": "8ec1dc26-ae49-486e-a9ea-922ea76b023b"
            }
        ],
        "weight": {
            "value": 100,
            "unit": "g"
        },
        "tracking_number": "tracking-number-1234",
        "return_tracking_number": "return-tracking-number-5678",
        "status": "shipped",
        "created_at": "2025-01-10T12:29:20.946108Z",
        "modified_at": "2025-01-10T14:29:20.946108Z"
    },
    {
        "shipment_id": "94b159ab-1349-4955-87fe-0132ba267e45",
        "shipment_number": "2",
        "order_lines": [],
        "weight": {
            "value": 500,
            "unit": "g"
        },
        "status": "canceled",
        "created_at": "2025-01-10T13:29:20.946108Z",
        "modified_at": "2025-01-10T15:29:20.946108Z"
    },
    {
        "shipment_id": "86666a01-e37e-44d8-845e-38346d1954c5",
        "shipment_number": "3",
        "order_lines": [
            {
                "order_line_id": "0ee6f0c4-dab6-4bb0-b99e-c7e83362b7a6"
            },
            {
                "order_line_id": "40a33bc1-3151-4351-bc62-8317a189d230"
            }
        ],
        "weight": {
            "value": 250,
            "unit": "g"
        },
        "status": "initial",
        "created_at": "2025-01-10T15:29:20.946108Z",
        "modified_at": "2025-01-10T15:29:20.946108Z"
    }
]

Warning

You can only create new Shipments with Order Lines that have status initial or reserved. Any Order Lines with different statuses can not be moved anymore and need to be shipped with the Shipment they are currently assigned to.

From here apply any changes to the newly created Shipment with ID 86666a01-e37e-44d8-845e-38346d1954c5 and make sure it gets marked as shipped before sending the physical items to the end customer.

Cancelling a Shipment

It's not possible to cancel a Shipment through the Shipment API. Instead you should use the Order Lines API to mark the Order Lines you are unable to ship as cancelled. Upon cancellation of the Order Line it will automatically be unassigned from the Shipment and if no Order Lines are left on the Shipment it will get status cancelled.

Once an order is marked as cancelled it can not be updated anymore and no parcel should be shipped for that specific shipment.

Contact Support