This endpoint allows you to submit an "external shipping label" to Liverpool.
There are a few very important things to consider before using it.
For Liverpool, there are several conditions that must be met before calling this endpoint. With this single request, we ensure that all conditions are satisfied — but it’s important you understand that the following actions will take place during this call:
1.- In the Liverpool order, the fulfillment.center.code must be set to 'DEFAULT'.This ensures that the order is handled by Liverpool’s acceptance-required flow. Since the first action in this request is to accept the order, the code must be 'DEFAULT'.
2.- If you include package information via fulfillment.package.dimensions, be aware that you will be overwriting Liverpool’s default package values. These defaults are:
"length": "10", "width": "10", "height": "10", "weight": "1" (in cm and kg).
If your package requires different dimensions, you can provide them using fulfillment.package.dimensions. The maximum values are:
100 cm for width and height, 120 cm for length, and 35 kg for weight.
3.- Do not include the fulfillment.items array unless you want to fulfill only specific items in the order.
If you include item IDs in that array, only those items will be accepted — all others will be rejected by default.
So, if your goal is to fulfill all items in the order, simply leave out the items array and all item IDs will be accepted automatically.
4.- Item dimensions and weight will always use Liverpool's default values, which are:
"length": "10", "width": "10", "height": "10", "weight": "1"
5.- The shipping address information is pulled directly from the original Liverpool order.
6- The reference for the fulfillment is provided by the client and must be included in the payload under fulfillment.package.reference.
This value should be a numeric string that uniquely identifies the package within the order. If it's not provided, the system will default to "1".
The final reference used for Liverpool will still be constructed internally as a concatenation of:
orderId + reference + storeId
Where reference is always zero-padded to 6 digits (e.g., "1" becomes "000001").
This reference acts as a unique identifier and is critical because, once it is associated with a fulfillment, Liverpool does not provide any endpoint to retrieve it.
It’s extremely important to store the final reference value, as it cannot be retrieved later through any API. You will need this exact value to update the shipment status later via fulfillment events.
7.- The shipping label PDF must be included as a Base64-encoded string in fulfillment.tracking.url. This field is required.
Taking all this into account, you should be able to use the create fulfillment endpoint without issues.
Remember: except for items and package, all other fields are required.
8.- Currently, the only valid values for fulfillment.tracking.company in the Liverpool integration are: "dhl", "fedex", and "estafeta".
Any other value will be rejected.