Multiple shipments

For Checkout Express orders with multiple shipments there are some extra considerations to take into account.

Please read the single shipment shipping option guide before continuing the guide for handling multiple shipments.

Notable changes from the single shipment flow:

• The express.shipping_options must include a shipment_id that is used to group the shipping options per shipment.
• The express.shipping_options must include shipment_items that describes what items belong to a shipment.
• The order.shipping_option is a single top-level shipping option that has multiple shipments.

What it looks like

Express shipping options

For shipping options in express.shipping_options and shipping options returned by the optional express.shipping_address_callback_url endpoint.

When the order contains multiple shipments each shipping option has to contain a shipment_id that is used for grouping the options for that shipment. The shipping options must also contain list of shipment_items that specify the items (and optionally quantities) that are included in the shipment. The shipment_items list is used to determine which items are included in the shipment and is displayed in the checkout. All shipping options that share the same shipment_id should have the same shipment_items list.

Each multi shipment shipping option needs a minimum set of required declared properties:

{
    "id": "group-id-1",
    "line_id": "unique-shipping-id-1",
    "amount": 10000,
    "operator": "shipping-provider-name",
    "title": "Home delivery",
    "shipment_id": "shipment-1",
    "shipment_items": [
        {
            "line_id": "line-1",
            "quantity": 1
        },
        {
            "line_id": "line-2",
            "quantity": 2
        }
    ]
}

The shipping option in the order object

The shipping option found in the order.shipping_option is a single top level shipping option that contains multiple shipments. The shipment array must contain a single shipping option per shipment_id found in express.shipping_options. There must be two or more shipping options in the shipments array, if you only have a single shipment use the single shipment flow instead.

Example top-level shipping option for an order with multiple shipments:

 {
    "id": "multi_shipment",
    "title": "Multiple shipments",
    "amount": 40000,
    "line_id": "multi_shipment",
    "operator": "",
    "shipments": [
        {
            "id": "group-id-1",
            "line_id": "unique-shipping-id-1",
            "amount": 10000,
            "operator": "Bring",
            "title": "Home delivery",
            "shipment_id": "shipment-1",
            "shipment_items": [
                {
                    "line_id": "line-1",
                    "quantity": 1
                },
                {
                    "line_id": "line-2",
                    "quantity": 2
                }
            ]
        },
        {
            "id": "group-id-2",
            "line_id": "unique-shipping-id-2",
            "amount": 30000,
            "operator": "DHL",
            "title": "Express delivery",
            "shipment_id": "shipment-2",
            "shipment_items": [
                {
                    "line_id": "line-3",
                    "quantity": 1
                }
            ]
        }
    ]
}

After payment has been completed

The resulting transaction will contain the top-level multi shipment shipping option, but we will append a single item per shipment to the order.items in the resulting transaction so that the shipments can be captured and refunded separately.