Migrating from older API

Ongoing improvements

We are actively working on improving this documentation. The contents of this page may be incomplete and are subject to change.

This chapter is targeted to customers that are using one or more of the following API endpoints:

API V2:
- /api/v2/bookings
- /api/v2/shipments

Accessing older data

Shipments created by older API endpoints or via the MyWuunder UI cannot be accessed by this new /api/v2/orders API endpoints.
Shipments created via the new API can be access in the MyWuunder UI.
The current MyWuunder UI doesn't have support for Orders yet.

Shipments require an order

Created shipments are always linked to an order. An order can have zero or more shipments. This means that, every shipment has an order. Even if you just want to ship out one package.

Removed number_of_items

The field number_of_items is not supported anymore in this API. If you need multiple shipments in an order with the same properties, you have to supply multiple shipments in the payload of the API.

Renamed fields

Be aware that some fields that you encountered in the booking and shipments API's, have been renamed:

Previous name	New name
`business`	`business_name`
`country`	`country_code`
`customer_reference`	`reference`
`delivery_address`	`receiver_address`
`is_return`	`return`
`locality`	`city`
`pickup_address`	`sender_address`

With the change of orders and shipments, there is now support for multi colli. Since an order can contain one or more shipments, all shipments can be booked in one go. Our system will try to figure out which shipments can be bundled together and can be offered in one multi-colli collection call at the carrier. This saves you, the carrier and us valuable time and money.

Stricter validation

To prevent booking failures at carriers, we are validating incoming address data more strict than the shipments API. This saves valuable time when problems arise.

Orders and shipments now require complete data. Inserting incomplete data for shipments is not supported.
Only data for shipments that is considered bookable is accepted.
There are stricter validations on shipments that pass customs.
There are stricter checks for unicode characters:
- We don't allow unicode control characters (such as left-to-right modifiers).
- We only allow normal spaces. Non-breaking spaces, figure spaces, thin spaces etc. are not allowed.
- We only allow newlines in text fields (such as a description or a meta field).

Consult the API documentation sections if you are running into problems. Every field requirement is specified in our OpenAPI specs and can be found in the API schemas list.

Addresses

As noted, the validations of order and shipment creation is a lot stricter than in previous API versions. Especially on the address part, there are a couple of changes:

An address requires a business_name or at least a first_name and last_name. When business_name is provided, both first_name and last_name are optional. If no business_name is provided, you need to supply a first_name and last_name.
Based on supplying a business_name or not, an address becomes a business or consumer address. Rates and services can vary based on this characteristic.
An address requires a street_name.
An address does not require a house_number.
An address requires a zip_code. There is no strict zip code checking validation in place.
An address requires a valid country_code. Country codes that are not known by the system will result in a failure.
An address requires a valid city.

Shipping internationally

eori_number and vat are required on addresses when shipping internationally. Check the international_shipping section for more information.
state_code is now required on all addresses and validated for US and CA destinations.
ean_number and hs_code are required on order lines when shipping internationally.

Orders and shipments

Orders don't require shipments when creating an order. But: if an order doesn't have any shipments, it cannot be booked. It will stay a draft as long as there are no valid shipments added to that order.

If you want to book shipments within an order, you book the entire order with all it's connected shipments.
You can add multiple shipments to orders as long as they are in status draft or draft_ready_to_book.
When an order is ready to be shipped out, you will see that the status of the order changes to draft_ready_to_book.

Creation and booking are now separate steps

Creating orders and shipments and booking are now two seperate steps. If you want to book a shipment:

Create the order and shipments.
Optional: request the rates that are applicable for the order and shipments.
Book the just created order with all it's shipments.

Locked shipments

Shipments that are being booked, will be locked by the system. If an order is locked, you cannot make any changes to the order or it's linked shipments. ou cannot modify orders and shipments which are not in status draft or draft_ready_to_book anymore.

API timeouts

All new API requests have a max time to respond. If somehow, this takes longer than expected, we return the status of the order and shipments at that point in time, in the background we keep processing your order and shipments.

Webhooks

Webhooks can still be used but are scoped to shipments and not to orders. You can only receive a webhook calls for individual shipments.