REST API - Shipment
The REST API supports creating, updating and deleting Shipments.
After the shipment is created a label can be generated and downloaded.
Generating a label will pre announce the shipment to the specified Carrier.
Endpoint
/parcel/shipment
Headers
A valid JWT token in the request is needed along with the version number to authenticate and authorize the request.
Replace ACCESS_TOKEN with a valid access token.
Authorization: Bearer ACCESS_TOKEN
Api-Version: 3.0
Content-Type: application/json
Create Shipment
Method: POST
Response: 200 OK
Max 100 shipments at once can be created
Shipments
| Field | Type | Required | Comment |
|---|---|---|---|
| Shipments | Shipment | Yes | Array of multiple shipments |
Update Shipment
Endpoint: /parcel/shipment/{shipmentId}
Method: PUT
Response: 200 OK
Just one shipment can be updated at a time
Updating a shipment is only possible if the Status of the shipment is ToPrint.
It will mainly be used to change shipment address data or swap between parcel and mailbox.
A single Shipment must be provided.
Not all fields and properties are required. This depends on the chosen package type.
On the Options Page you can find which properties are applicable.
Sender address is optional. If not specified, the default sender address will be inserted.
Shipment
| Field | Type | Required | Comment |
|---|---|---|---|
| ReferenceId | string(20) | Yes | Identifier from source system |
| Carrier | int | Yes | 2 = PostNL, 30 = bpost |
| LabelText | string(50) | No | Text on label |
| TrackTraceEmail | string(50) | No | Optional email address for Track & Trace notification send by Simplymail |
| DeliveryEmail | string(50) | No | Optional email address for delivery notification send by Simplymail |
| CostCenter | int | No | -- |
| Addresses | Address | Yes | Array of multiple addresses |
| Properties | ShipmentProperty | Yes | Object with properties of shipment |
| Customs | Customs | No | Customs declaration: required for Non-EU shipments |
Address
| Field | Type | Required | Comment |
|---|---|---|---|
| TypeId | int | Yes | Type of address: 1 = Receiver, 2 = Sender (optional), 3 = Pick up point (optional) |
| Company | string(100) | No | Company or Contact required |
| Contact | string(100) | No | Company or Contact required |
| string(50) | No | Email from contact | |
| Phone | string(25) | No | Phone from contact |
| Street | string(100) | No | Required for NL, BE, DE |
| Number | string(10) | No | Optional split from street |
| NumberSuffix | string(10) | No | Optional split from street |
| ExtraAddress | string(100) | No | Additional address line |
| ZipCode | string(10) | Yes | -- |
| City | string(50) | Yes | -- |
| CountryCode | char(2) | Yes | 2 letter ISO Code |
ShipmentProperty
| Field | Type | Required | Comment |
|---|---|---|---|
| Package | int | Yes | 1 = Parcel, 2 = Mailbox, 3 = Box, 4 = Letter, 5 = Digital Stamp |
| Weight | int | Yes | Weight in gram |
| Signature | bool | No | Reiceiver must sign for delivery -> Not applicable on NL Mailbox shipments |
| Insurance | int | No | NL (100, 250, multiple of 500 till 5000) / Other (50, 500) |
| NoNeighbour | bool | No | Parcel will not be delivered to neighbour -> Applicable on NL Parcel shipments only |
| Delivery | int | No | 1 = Guaranteed 09:00, 2 = Guaranteed 10:00, 3 = Guaranteed 12:00, 4 = Guaranteed 17:00, 5 = Evening, 6 = Sameday, 7 = Sunday, 8 = Pickup Point |
| DeliveryDate | DateTime | No | Delivery date for Guaranteed, Evening, Sameday and Sunday shipments [yyyy-MM-dd] |
| Quantity | int | No | Create Multi collo shipments -> Applicable for Parcel NL |
| AddHandling | bool | No | Add shipment handling fee up front -> Applicable for Parcels |
| Feature | string(20) | No | Add required features: [48h, untracked, age-check, vat-free, C4] |
Customs
Customs is only applicable on Non-EU shipments
| Field | Type | Required | Comment |
|---|---|---|---|
| Type | int | Yes | 1 = Gift, 2 = Documents, 3 = Commercial Goods, 4 = Commercial Sample, 5 = Returned Goods |
| Currency | char(3) | Yes | EUR, USD, GBP, CNY |
| InvoiceNumber | string(35) | Yes | Number of invoice: required for Type 3, 4, 5 |
| NonDeliverable | bool | Yes | Return shipment if it can't be delivered the first time |
| Items | CustomsItem | Yes | Array of CustomsItem (max 5) |
CustomsItem
Max 5 items can be used
| Field | Type | Required | Comment |
|---|---|---|---|
| Description | string(50) | Yes | Description of the item |
| Quantity | int | Yes | Number of the items |
| Weight | int | Yes | Total weight of items |
| Value | decimal | Yes | Value of items |
| HsTariffNumber | string(25) | No | Harmonized System Code of item |
| CountryCode | char(2) | Yes | 2 letter ISO Code of origin of item |
Create Request
Below you can find a request of multiple shipments with different properties.
{
"shipments": [
{
"referenceId": "MyRef101",
"carrier": 2,
"labelText": "shipment 1",
"trackTraceEmail": "info@quadient.com",
"addresses": [
{
"typeId": 1,
"company": "Quadient Netherlands",
"contact": "Jan Janssen",
"street": "Avelingen West",
"number": "9",
"numberSuffix": "A",
"extraAdrress": "Verdieping 2",
"email": "info@quadient.com",
"phone": "0183 635 777",
"zipCode": "4202 MS",
"city": "Gorinchem",
"countryCode": "NL"
}
],
"properties": {
"package": 1,
"weight": 3000
}
},
{
"referenceId": "MyRef102",
"carrier": 2,
"trackTraceEmail": "info@example.com",
"deliveryEmail": "info@example.com",
"addresses": [
{
"typeId": 1,
"company": "Quadient Belgium",
"street": "'t Hofveld",
"number": "6",
"numberSuffix": "F",
"extraAdrress": "Bus 1",
"email": "info@quadient.com",
"phone": "+32 (0)2 569 05 35",
"zipCode": "1702",
"city": "Groot-Bijgaarden",
"countryCode": "BE"
}
],
"properties": {
"package": 1,
"weight": 3000
}
},
{
"referenceId": "MyRef103",
"carrier": 2,
"labelText": "shipment 3",
"costCenter": 101,
"addresses": [
{
"typeId": 1,
"contact": "Jan Janssen",
"street": "Avelingen West",
"number": "9",
"zipCode": "4202 MS",
"city": "Gorinchem",
"countryCode": "NL"
}
],
"properties": {
"package": 2,
"weight": 2000
}
}
]
}
Create Response
The response format is a JSON body with http code 200 OK.
If an error occurred an Error response will be generated.
{
"shipments": [
{
"referenceId": "MyRef101",
"id": 1000001
},
{
"referenceId": "MyRef102",
"id": 1000002
},
{
"referenceId": "MyRef103",
"id": 1000003
}
]
}
Update Request
Below you can find an update request of a shipment with receiver and sender address data.
{
"shipment":
{
"labelText": "Test label",
"trackTraceEmail":"info@example.com",
"deliveryEmail":"info@example.com",
"addresses": [
{
"TypeId": 1,
"contact": "Receiver",
"street": "Receiverstreet 1",
"zipCode": "1234 AB",
"city": "Rotterdam",
"countryCode": "NL"
}
],
"properties": {
"package": 1,
"weight": 3000
}
}
}
Update Response
The response is a http code 200 OK without a JSON body.
If an error occurred an Error response will be generated.
Delete Shipment
Method: DELETE
Response: 204 No Content
A Shipment can only be deleted if it's not pre announced to a Carrier.
If a label is already genereated a delete is not possible and a 401 Bad Request is returned.
Shipment
| Field | Type | Comment |
|---|---|---|
| Ids | int | Array of multiple shipment ids |
Delete Request
Below you can find a request of multiple ids to be deleted.
{
"ids": [
1000001,
1000002
]
}
Delete Response
The response is a http code 204 No Content without a JSON body.
If an error occurred an Error response will be generated.