Wuunder API docs

Create shipments

POST/api/v2/orders/{order_id}/shipments

Adds one or more shipments to an existing order. Shipments can only be added to orders that are in draft

Authorization

Add HTTP header Authorization with the received API key as the bearer token:

Authorization
API Key

Parameters

URL parameters

PropertyTypeDescription
order_id
string

Order ID

Unique identifier for order.

uuid

Request body

Content-Type
application/json
Body
CreateShipmentsRequestrequired
PropertyTypeDescription
shipments
CreateShipment
required
1..30 items
ShipmentProperties
required
currency
string
Currency used for rates and shipments.
required
one of:
EUR
delivery_instructions
string
The delivery instructions given to a carrier. This text should be short. It is only implemented for the following carriers: TNT; Transmission; bpost (only certain products); Mondial Relay;
nullable
length 1...200
description
string
Text field that may contain multiple lines and unicode characters.
required
\A^[\p{L}\p{N}\p{P}\p{Z}\n]+\z
nullable
length 1...2700
external_id
string
External identification number used for shipments that are generated by third-party systems (like bol.com).
\A[[:alnum:]\-_\\/\.]+\z
length 1...255
height
integer
The height in CMs.
required
value 1...
incoterms
string
Incoterms applicable for shipment. Must be DDP (Delivered Duty Paid) or DAP (Delivered At Place).
required
one of:
DDP
DAP
length
integer
The length in CMs.
required
value 1...
meta
object
This is an additional free format structured field that will give you the possibility to manage your booking process. Maps and lists are supported.
ordered_at
string
Date time in ISO 8601 format (YYYY-MM-DD HH:MM:SS) in UTC
date-time
parcelshop_drop_off
boolean
Indicates if the shipment will be dropped of by the sender for pickup at a parcelshop.
required
parcelshop_id
string
ID of the parcelshop where the package is going to be delivered. String must contain carrier_code:code_of_parcelshop.
\A[A-Z_]+:[A-Z0-9_]+\z
length 3...64
reference
string
Custom reference code to identify your shipments or orders
required
\A[[:alnum:]\-_\\/\.]+\z
length 1...255
return
boolean
required
type
string
Indicates the type of shipment.
required
one of:
document
package
pallet
letterbox
value
integer
The total value in cents.
required
value 1...
webhook_url
string
A valid publicly accessible URL (http or https).
length 1...255
weight
integer
The weight or a product or shipment in grams.
required
value 1...
width
integer
The width of a shipment or product in CMs.
required
value 1...
object
required
order_lines
OrderLine
description
string
The description/name of the item
required
\A^[\p{L}\p{N}\p{P}\p{Z}\n]+\z
nullable
length 1...2700
ean
string
EAN Code of product (European Article Number)
\A[0-9]{8,13}\z
hs_code
string
HS Code of product (Harmonized Commodity Description and Coding System)
\A[0-9]{6,10}\z
meta
object
This is an additional free format structured field that will give you the possibility to manage your booking process. Maps and lists are supported.
origin_country_code
string
ISO country code.
required
\A[A-Z]{2}\z
length 2...2
quantity
integer
The number of items for a product in an order line.
required
value 1...
sku
string
SKU Code of product
\A[[:alnum:] \-_]+\z
value
integer
The total value in cents.
required
value 1...
weight
integer
The weight or a product or shipment in grams.
required
value 1...
receiver_address
CreateAddress
Schema used to specify an address for a newly created shipment.
required
AddressProperties
required
address2
string
Address2 address field.
\A[[:alnum:] .,&'\-]+\z
length 1...255
business_name
string
Name of business for address. If this name is supplied, it will indicate that the address type is business. If left empty, it indicates that the address type is a consumer.
\A[[:alnum:] .,&!'\-]+\z
length 1...255
city
string
City of address.
required
\A[[:alnum:] .,&'\-]+\z
length 2...30
country_code
string
ISO country code.
required
\A[A-Z]{2}\z
length 2...2
email_address
string
Email address compatible with RFC 5322.
\A[\w+\-\.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z
length 3...320
eori_number
string
Economic Operators Registration and Identification number that is required by businesses to ship internationally.
length 3...17
family_name
string
Also known as last name. Refers to the name of the contact person to whom the address belongs.
\A[[:alnum:] -]+\z
length 1...30
given_name
string
Also known as first name. Refers to the personal name of the contact person to whom the address belongs.
\A[[:alnum:] -]+\z
length 1...30
house_number
string
House number in an address. May also contain house number extensions.
required
\A[[:alnum:] \-]+\z
length 1...14
id
string
Unique ID for an address. Can be a ID of an existing sender_address or a unique ID of a parcelshop. In all other cases this ID is empty.
length 1...64
phone_number
string
Phone number that may consist of a country code.
\A[[:digit:] \-+()]+\z
length 2...30
state_code
string
State code for an address. The state code should be applicable for the country. So NY (New York) for country_code US (United States) or YT (Yukon) for country_code CA (Canada)
\A[A-Z]{2,3}\z
length 2...3
street_name
string
Street name is an identifying name given to a street or road.
required
\A[[:alnum:] .,&'\-]+\z
length 2...55
vat
string
Value-added tax identification number or VAT identification number (VATIN).
nullable
length 3...14
zip_code
string
The zipcode of an address.
required
\A[[:alnum:] -]+\z
length 1...10
sender_address
CreateAddress
Schema used to specify an address for a newly created shipment.
required
AddressProperties
required
address2
string
Address2 address field.
\A[[:alnum:] .,&'\-]+\z
length 1...255
business_name
string
Name of business for address. If this name is supplied, it will indicate that the address type is business. If left empty, it indicates that the address type is a consumer.
\A[[:alnum:] .,&!'\-]+\z
length 1...255
city
string
City of address.
required
\A[[:alnum:] .,&'\-]+\z
length 2...30
country_code
string
ISO country code.
required
\A[A-Z]{2}\z
length 2...2
email_address
string
Email address compatible with RFC 5322.
\A[\w+\-\.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z
length 3...320
eori_number
string
Economic Operators Registration and Identification number that is required by businesses to ship internationally.
length 3...17
family_name
string
Also known as last name. Refers to the name of the contact person to whom the address belongs.
\A[[:alnum:] -]+\z
length 1...30
given_name
string
Also known as first name. Refers to the personal name of the contact person to whom the address belongs.
\A[[:alnum:] -]+\z
length 1...30
house_number
string
House number in an address. May also contain house number extensions.
required
\A[[:alnum:] \-]+\z
length 1...14
id
string
Unique ID for an address. Can be a ID of an existing sender_address or a unique ID of a parcelshop. In all other cases this ID is empty.
length 1...64
phone_number
string
Phone number that may consist of a country code.
\A[[:digit:] \-+()]+\z
length 2...30
state_code
string
State code for an address. The state code should be applicable for the country. So NY (New York) for country_code US (United States) or YT (Yukon) for country_code CA (Canada)
\A[A-Z]{2,3}\z
length 2...3
street_name
string
Street name is an identifying name given to a street or road.
required
\A[[:alnum:] .,&'\-]+\z
length 2...55
vat
string
Value-added tax identification number or VAT identification number (VATIN).
nullable
length 3...14
zip_code
string
The zipcode of an address.
required
\A[[:alnum:] -]+\z
length 1...10

Request example

JSON
{
  "shipments": [
    {
      "currency": "EUR",
      "delivery_instructions": "Leave at the back door if no one answers.",
      "description": "Test shipment no 1",
      "external_id": "ID-1",
      "height": 5,
      "length": 2,
      "parcelshop_drop_off": false,
      "receiver_address": {
        "city": "Rotterdam",
        "country_code": "NL",
        "email_address": "shipment-receiver@example.com",
        "family_name": "De Jong",
        "given_name": "Jan",
        "house_number": "1",
        "street_name": "Stationsplein",
        "zip_code": "3013AK"
      },
      "reference": "TEST-SHIPMENT-1",
      "return": false,
      "sender_address": {
        "business_name": "Wuunder - Sender",
        "city": "Amsterdam",
        "country_code": "NL",
        "email_address": "shipment-sender@example.com",
        "eori_number": "NL123123123",
        "family_name": "Gehlen",
        "given_name": "Jeroen",
        "house_number": "1",
        "phone_number": "+31612345678",
        "street_name": "Stationsplein",
        "vat": "NL000099998B0",
        "zip_code": "1012AB"
      },
      "type": "package",
      "value": 50,
      "weight": 200,
      "width": 20
    },
    {
      "currency": "EUR",
      "description": "Test shipment no 1",
      "external_id": "ID-2",
      "height": 5,
      "length": 2,
      "parcelshop_drop_off": false,
      "parcelshop_id": "POST_NL:397950",
      "receiver_address": {
        "city": "Rotterdam",
        "country_code": "NL",
        "email_address": "shipment-receiver@example.com",
        "family_name": "De Jong",
        "given_name": "Jan",
        "house_number": "1",
        "street_name": "Stationsplein",
        "zip_code": "3013AK"
      },
      "reference": "TEST-SHIPMENT-2",
      "return": false,
      "sender_address": {
        "business_name": "Wuunder - Sender",
        "city": "Amsterdam",
        "country_code": "NL",
        "email_address": "shipment-sender@example.com",
        "eori_number": "NL123123123",
        "family_name": "Gehlen",
        "given_name": "Jeroen",
        "house_number": "1",
        "phone_number": "+31612345678",
        "street_name": "Stationsplein",
        "vat": "NL000099998B0",
        "zip_code": "1012AB"
      },
      "type": "package",
      "value": 50,
      "weight": 200,
      "width": 20
    }
  ]
}

Response

Response body

Content-Type
application/json
Body
PropertyTypeDescription
order
Order
A collection of shipments. Contains data for orders that are persisted.
required
OrderProperties
required
reference
string
Custom reference code to identify your shipments or orders
required
\A[[:alnum:]\-_\\/\.]+\z
length 1...255
object
required
id
string
Unique identifier for order.
required
uuid
inserted_at
string
Date time in ISO 8601 format (YYYY-MM-DD HH:MM:SS) in UTC
required
date-time
order_code
string
Unique human readable identifier of an order in Wuunder.
\AO\-[0-9]{3}-[A-Z]{3}-[0-9]{3}\z
length 13...13
receiver
OrderReceiver
Specifies the full legal address of a business or person, including street, house number, zip code, city, and country that is used to send the order to.
required
sender
OrderSender
Specifies the full legal address of a business or person, including street, house number, zip code, city, and country that is used to send the order from.
required
shipments
Shipment
status
string
required
status_history
object
Contains all historical events that took place on this shipment or order.
required
updated_at
string
Date time in ISO 8601 format (YYYY-MM-DD HH:MM:SS) in UTC
required
date-time

Response body example

JSON
{
  "order": {
    "reference": "89977-3249",
    "id": "4a2a1a78-6b9a-43af-887e-2adc7d415e7a",
    "inserted_at": "2019-08-24T14:15:22Z",
    "order_code": "stringstrings",
    "receiver": {
      "city": "Rotterdam",
      "country_code": "NL",
      "email_address": "order-receiver@example.com",
      "eori_number": "NL123456789000",
      "family_name": "Koebergen",
      "given_name": "Peter",
      "house_number": "1",
      "phone_number": "+311012345678",
      "state_code": "ZH",
      "street_name": "Stationsplein",
      "type": "business",
      "zip_code": "3013AK"
    },
    "sender": {
      "business_name": "Acme Inc",
      "city": "Amsterdam",
      "country_code": "NL",
      "email_address": "order-sender@example.com",
      "eori_number": "NL123456789000",
      "family_name": "Gehlen",
      "given_name": "Jeroen",
      "house_number": "1",
      "phone_number": "+311012345678",
      "state_code": "NH",
      "street_name": "Dam",
      "type": "business",
      "vat": "NL000099998B0",
      "zip_code": "1122AA"
    },
    "shipments": [
      {
        "currency": "EUR",
        "delivery_instructions": "Leave at the back door if no one answers.",
        "description": "Box of toothbrushes",
        "external_id": "EXT123",
        "height": 2,
        "incoterms": "DDP",
        "length": 20,
        "meta": {
          "customer_id": "AB-001",
          "locations": [
            "Warehouse X",
            "Warehouse Y"
          ]
        },
        "ordered_at": "2019-08-24T14:15:22Z",
        "parcelshop_drop_off": true,
        "parcelshop_id": "POST_NL:1234",
        "reference": "89977-3249",
        "return": true,
        "type": "document",
        "value": 1444,
        "webhook_url": "https://www.example.com/test.jpeg",
        "weight": 200,
        "width": 10,
        "booked_rate": {
          "carrier_code": "POST_NL",
          "carrier_name": "PostNL",
          "carrier_product_code": "POSTNL_BRIEVENBUSPAKKET",
          "carrier_product_description": "Pakket tot 20 gram in brievenbus",
          "price": 255,
          "receiver_type": "consumer",
          "sender_type": "business",
          "tags": [
            "preferred",
            "fastest",
            "cheapest"
          ]
        },
        "booking_failure_reason": "string",
        "delivery_info": {
          "date": "2024-07-04",
          "time_window": "10:00-17:00",
          "type": "address"
        },
        "documents": {
          "commercial_invoice_url": "https://api.wearewuunder.com/public/123/A-111-111/commercial_invoice",
          "label_pdf_url": "https://api.wearewuunder.com/public/123/A-111-111/get_label",
          "label_zpl_url": "https://api.wearewuunder.com/public/123/A-111-111/zpl_label",
          "packinglist_url": "https://api.wearewuunder.com/public/123/A-111-111/packing_list"
        },
        "id": "57168dba-c987-4755-9c3b-6c5d86825e75",
        "inserted_at": "2019-08-24T14:15:22Z",
        "order_lines": [
          {
            "description": "Toothbrush",
            "ean": "0799439112766",
            "hs_code": "620520",
            "meta": {
              "customer_id": "AB-001",
              "locations": [
                "Warehouse X",
                "Warehouse Y"
              ]
            },
            "origin_country_code": "NL",
            "quantity": 2,
            "sku": "ABC-123",
            "value": 1444,
            "weight": 200
          }
        ],
        "parcelshop": {
          "business_name": "Doelen Pakketservice",
          "carrier_code": "POST_NL",
          "city": "Rotterdam",
          "country_code": "NL",
          "email_address": "parcelshop@example.com",
          "eori_number": "NL123456789000",
          "family_name": null,
          "given_name": null,
          "house_number": "50",
          "id": "302",
          "latitude": 51.9216717,
          "longitude": 4.470482,
          "opening_hours": [
            {
              "hours": [
                "09:00-17:30",
                "20:00-21:00"
              ],
              "weekday": "monday"
            },
            {
              "hours": [
                "09:00-17:30",
                "20:00-21:00"
              ],
              "weekday": "tuesday"
            },
            {
              "hours": [],
              "weekday": "wednesday"
            },
            {
              "hours": [
                "09:00-17:30",
                "20:00-21:00"
              ],
              "weekday": "thursday"
            },
            {
              "hours": [
                "09:00-17:30",
                "20:00-21:00"
              ],
              "weekday": "friday"
            },
            {
              "hours": [
                "09:00-17:30"
              ],
              "weekday": "saturday"
            },
            {
              "hours": [
                "09:00-12:30",
                "13:00-14:00"
              ],
              "weekday": "sunday"
            }
          ],
          "phone_number": "+311012345678",
          "state_code": "ZH",
          "street_name": "Schouwburgplein",
          "type": "business",
          "website_url": "www.example.com",
          "wuunder_reference": "POST_NL:302",
          "zip_code": "3012CL"
        },
        "pickup_info": {
          "date": "2024-07-04",
          "time_window": "10:00-17:00",
          "type": "regular_pickup"
        },
        "receiver_address": {
          "address2": "Apt 202",
          "business_name": "Wuunder",
          "city": "Amsterdam",
          "country_code": "NL",
          "email_address": "info@wearewuunder.com",
          "eori_number": "GB123456789000",
          "family_name": "Henk",
          "given_name": "Henk",
          "house_number": "22-A",
          "id": "d1dcceb0-0796-43bb-bcc1-67aedbf0b436",
          "phone_number": "+31612345678",
          "state_code": "NY",
          "street_name": "Berglaan",
          "vat": "NL000099998B57",
          "zip_code": "2211AA",
          "type": "consumer"
        },
        "sender_address": {
          "address2": "Apt 202",
          "business_name": "Wuunder",
          "city": "Amsterdam",
          "country_code": "NL",
          "email_address": "info@wearewuunder.com",
          "eori_number": "GB123456789000",
          "family_name": "Henk",
          "given_name": "Henk",
          "house_number": "22-A",
          "id": "d1dcceb0-0796-43bb-bcc1-67aedbf0b436",
          "phone_number": "+31612345678",
          "state_code": "NY",
          "street_name": "Berglaan",
          "vat": "NL000099998B57",
          "zip_code": "2211AA",
          "type": "consumer"
        },
        "status": "booked",
        "status_history": [
          {
            "state": "draft",
            "timestamp": "2023-06-01T10:00:00Z"
          },
          {
            "state": "pending_printing",
            "timestamp": "2023-06-01T12:00:00Z"
          },
          {
            "state": "ready_for_pickup",
            "timestamp": "2023-06-02T09:15:00Z"
          },
          {
            "state": "in_transit",
            "timestamp": "2023-06-03T14:30:00Z"
          },
          {
            "state": "out_for_delivery",
            "timestamp": "2023-06-04T08:45:00Z"
          },
          {
            "state": "delivered",
            "timestamp": "2023-06-04T15:20:00Z"
          }
        ],
        "track_and_trace_code": "0009398723",
        "track_and_trace_url": "https://api.wearewuunder.com/track-and-trace",
        "updated_at": "2019-08-24T14:15:22Z",
        "wuunder_id": "strings"
      }
    ],
    "status": "string",
    "status_history": [
      {
        "state": "draft",
        "timestamp": "2023-06-01T10:00:00Z"
      },
      {
        "state": "pending_printing",
        "timestamp": "2023-06-01T12:00:00Z"
      },
      {
        "state": "ready_for_pickup",
        "timestamp": "2023-06-02T09:15:00Z"
      },
      {
        "state": "in_transit",
        "timestamp": "2023-06-03T14:30:00Z"
      },
      {
        "state": "out_for_delivery",
        "timestamp": "2023-06-04T08:45:00Z"
      },
      {
        "state": "delivered",
        "timestamp": "2023-06-04T15:20:00Z"
      }
    ],
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Next

Create order POST

Next

Update shipment PATCH