We'll start the shipment section with the different shipment option combinations available in MyParcel. It is highly recommended that you read this first as this section helps you understand what all the shipment options are and which combinations are possible. We will not list every possible combination since there are too many to list. We will look at the different package types and then look at the different options available to them. Then we bring all of it together with some examples.
6.A Shipment option combinations
6.A.1 Package types
There are four different packages types available and determine the name of shipment. The value is sent with the ShipmentOptions .package_type field.
1. Package
This is the standard package type used for NL, EU and Global shipments. It supports a variety of additional options such as insurance, xl format etc. We will look at these options in more detail later. This package is most commonly used when creating shipments.
2. Mailbox package
This package type is available on platform 1 (myparcel)
and platform 2 (flespakket)
for PostNL NL shipments that fit into a mailbox. It does not support additional options. On platform 3 (belgie)
this package type is available for bpost BE shipments that fit into a mailbox. It does not support additional options. This package type is also available on platform 1 (myparcel)
for international shipments that fit into a mailbox. Shipment option tracked is available. You need a PostNL contract for international mailbox packages if you want to use this product for your shipments. If you don't have such a contract, you can't create international mailbox package shipments.
If you still make the request with additional options, bear in mind that you may pay more than is necessary!
3. Letter
This package type is available on platform 1 (myparcel)
for NL, EU and Global shipments. The label for this shipment is unpaid meaning that you will need to pay the postal office/courier to send this letter/package. Therefore, it does not support additional options.
4. Digital stamp
This package type is only available on platform 1 (myparcel)
for NL shipments and does not support any additional options. Its price is calculated using the package weight .
Note: This shipment will appear on your invoice on shipment-status 2 (pending - registered)
as opposed to all other package types, which won't appear on your invoice until shipment shipment-status 3 (enroute - handed to carrier)
.
5. Pallet
This package type is only available on platform 1 (myparcel)
for NL and BE shipments.
6. Package small
This package type is only available on platform 1 (myparcel)
for NL and international shipments. For NL shipments, the same options apply as for the normal package. Of course except for option large_format. For international shipments, two shipments options are available: tracked and insured.
6.A.2 Delivery types
There are five different delivery types and these specify how the package is delivered. The value is sent with the ShipmentOptions.delivery_type field. Currently, delivery types are only available for NL and BE shipments with package-type 1 (package)
. Delivery types 1-5 for NL and 1,4 for BE. The address of the package determines the delivery types available. You need to use the DeliveryOptions interface to fetch the delivery types for a specific address. It is also possible to specify a date on which the package has to be delivered with the ShipmentOptions.delivery_date field. With delivery types 1 & 3 ShipmentOptions.delivery_date is required.
1. Morning
This option is only available for certain NL addresses. It allows a Customer/Consumer to have their package delivered early in the morning on the delivery date specified except on Saturday and Sunday.
2. Standard
This is the standard delivery type.
3. Evening
This option is only available on platform 1 (myparcel)
and platform 2 (flespakket)
for certain NL addresses. It allows a Customer/Consumer to have their package delivered in the evening on the specified delivery date.
4. Pickup
The package is delivered at the chosen drop-off point specified by the Consumer/Customer.
5. Pickup express
The same as pickup but the package is available for pickup before 8:30AM on the delivery date specified at the drop-off location. Only available on MyParcel.nl and Flespakket.
6.A.3 Options
These are the different package options such as insurance, recipient only, signature on receipt, XL format etc. These options are specified in the ShipmentOptions object. These options are only available for package-type 1 (package)
.
only_recipient
Deliver the package only at address of the intended recipient. This option is required for Morning and Evening delivery types.
signature
Recipient must sign for the package. This option is required for Pickup and Pickup express delivery types.
return
Return the package to the sender when the recipient is not home.
This option must be specified for PostNL shipments if the dimensions of the package are between 100 x 70 x 58 and 175 x 78 x 58 cm or heavier than 23 kg. If the scanned dimensions from the carrier indicate that this package is large format, and it has not been specified then it will be added to the shipment in the billing process. This option is also available for EU shipments.
insurance
This option allows a shipment to be insured up to certain amount. For package-type 1 (package)
shipments, the requirement for the insurance is:
- NL shipments can be insured for different amounts with different costs:
- Insured up to 100,- euros
- Insured up to 250,- euros
- Insured from 500,- euros up to 5000 euro's
- EU and global shipments can be insured for different amounts:
- Insured up to 50,- euros
- Insured up to 500,- euros
The following shipment options are mandatory when insuring a PostNL NL shipment: only_recipient and signature.
package-type 6 (package_small)
shipments can be insured up to 50,- euros.
The following shipment options are mandatory when insuring an package-type 6 (package_small)
shipment: tracked
age_check
Only available on platform 1 (myparcel)
and platform 2 (flespakket)
. The Customer/Consumer must sign for the package and only receive it when he is at least 18 years.
saturday_delivery
Available on platform 1 (myparcel)
and carrier DPD for b2b shipments. No additional fee is paid for delivery on saturdays. Available on platform 3 (belgie)
and carrier bpost. An additional fee is paid for delivery on saturdays.
tracked
Only available on platform 1 (myparcel)
and package-type 2 (mailbox)
or package-type 6 (package_small)
. This option can be used to make a package-type 2 (mailbox)
or package-type 6 (package_small)
tracked. Option tracked needs to be used with the international mailbox packages and the international small packages. There is one exception: a small package shipment to Belgium. If you have a PostNL contract that allows you to use international small packages under agreed conditions with PostNL, you can use the tracked option. If you don't have such a contract, the small package shipment to Belgium has the same options as a package-type 1 (package)
shipment to Belgium and the tracked option is not available.
6.A.4 Examples
PickupWe want to send a package to a consumer in Utrecht. He will pick the package up at the nearest pickup location. The shipment looks like this.
{
"data": {
"shipments": [
{
"options": {
"package_type": 1,
"only_recipient": 0,
"signature": 1,
"delivery_type": 4
}
}
]
}
}
Let's go through this example. This package will be picked up by the customer, so it needs to package-type 1 (package)
with delivery-type 4 (pickup)
. All pickup packages need to have signature set. A pickup location needs to be specified as well.
EveningWe want to send a package to a consumer in Utrecht that has to be delivered on Tuesday evening. The shipment looks like this.
{
"data": {
"shipments": [
{
"options": {
"package_type": 1,
"delivery_type": 3,
"only_recipient": 1
}
}
]
}
}
Let's go through this example. This package will be delivered to the consumer in the evening, so it needs package-type 1 (package)
with delivery-type 3 (evening)
. All evening and morning packages need to have only_recipient set.
NL insuredWe want to send a Rolex to a customer in Maastricht. This shipment needs to be insured up to € 5000,–. The shipment looks like this.
{
"data": {
"shipments": [
{
"options": {
"package_type": 1,
"insurance": {
"amount": 500000,
"currency": "EUR"
},
"signature": 1,
"only_recipient": 1
}
}
]
}
}
Only package-type 1 (package)
can be insured so [package type] is set to 1. Insurance amount needs to be specified in cents and needs to be one of these amounts (10000, 25000, 50000, 500000, <= 500000). The package needs to be insured up to 5000 euros, so we set insurance.amount
to 500000 cents. All NL insured packages need to have signature and only_recipient set, so we set them as well.
EU and Global insuredWe want to send an expensive Japanese vase to a Belgian friend of ours in Brussels. This package is large format because it's dimensions are within 100 x 70 x 50 and 175 x 78 x 58 cm range. Since this is an EU shipment is must be insured up to 500 euros.
{
"data": {
"shipments": [
{
"options": {
"package_type": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 1
}
}
]
}
}
This package is an EU package so the name must be set to 1. EU and Global shipments do not have the only_recipient and signature options so these cannot be set for this shipment.
6.B Add Shipment
6.B.1 Overview
Add shipments allows you to create standard and related return shipments. The data format can be JSON or CSV. Only standard national and EU shipments can be created with CSV. There are two ways of sending CSV: raw CSV or CSV file as part of multipart/form-data. You can specify the column mapping for CSV by including it as the first line in the CSV file or as a separate field named ' column_mapping' in the multipart/form-data.
For JSON requests a ShipmentIds object is returned. The ids in the ShipmentIds object will be in the same order they were sent.
For CSV requests HTTP 204 No Content
with empty response body is returned. If a request fails then an HTTP 4xx
is returned.
6.B.2 Reference
URI | https://api.myparcel.nl/shipments |
Methods | POST |
Required request headers | Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
Content-type: application/vnd.shipment+json;charset=utf-8;version=1.1 (For Shipments JSON request) |
Content-type: application/vnd.shipment_recipients+json;charset=utf-8;version=1.1 (For Shipments with recipients column JSON request) |
Content-type: application/vnd.return_shipment+json;charset=utf-8;version=1.1 (For ReturnShipments JSON request) |
Content-type: application/vnd.unrelated_return_shipment+json;charset=utf-8;version=1.1 (For UnrelatedReturnShipments JSON request) |
Optional request headers | Accept: application/vnd.shipment_label+json;charset=utf-8 (You will receive a URL that points to a PDF. This PDF is not immediately available, you can use the webhook shipment_label_created to listen to it.) |
URI parameters | None. |
Query parameters | format = paper_size (When using accept header: application/vnd.shipment_label+json;charset=utf-8) |
positions = label_position (When using accept header: application/vnd.shipment_label+json;charset=utf-8) |
Request body | array of Shipment objects. (For Shipments JSON request) |
array of ReturnShipment objects. (For ReturnShipments JSON request) |
array of UnrelatedReturnShipment objects. (For UnrelatedReturnShipments JSON request) |
Response | HTTP 200 OK Content-Type: application/vnd.shipment_ids+json;charset=utf-8 (For standard and related return shipment.) |
Response body | ShipmentIds |
Error response | HTTP 4xx |
Error response body | Error |
6.B.3 Request Headers
Content-Type: application/vnd.shipment+json;version=1.1
Specify this Content-Type when you want to create standard shipments.
Content-Type: application/vnd.return_shipment+json;version=1.1
Specify this Content-Type when you want to create related return shipments.
Parent shipment cannot be a concept (shipment-status 1 (pending - concept)
) .
When a label is generated, the status of the shipment is converted to registered ( shipment_status 2).
Content-Type: application/vnd.unrelated_return_shipment+json;version=1.1
Specify this Content-Type when you want to create unrelated return shipments.
6.B.4 Examples
In these examples we are going to create shipments.
PostNL: Create domestic shipments
The following example creates a PostNL shipment to a Dutch recipient address. Domestic PostNL shipments are also supported on sendmyparcel.be, using a Belgian address instead.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"return": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0,
"label_description": "My custom description",
"age_check": 1
},
"carrier": 1
},
{
"reference_identifier": "FOO-223-BAR-43",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Amsterdam",
"street": "Dorpstraat",
"number": "123",
"postal_code": "1020BC",
"person": "Mrs. Parcel",
"phone": "02012343546",
"email": "info@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 0,
"signature": 0,
"return": 0
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42"
},
{
"id": 68794,
"reference_identifier": "FOO-223-BAR-43"
}
]
}
}
PostNL: Create domestic multi collo shipments
Multi collo shipments are only available on
platform 1 (myparcel)
and
platform 2 (flespakket)
.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"return": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0,
"label_description": "My custom description",
"age_check": 1
},
"secondary_shipments": [{}, {}],
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
PostNL: Create International shipment
Creating shipments to an international destination is possible depending on the chosen carrier:
- PostNL and Bpost shipments are available worldwide.
- DPD shipments are available in the EU.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"recipient": {
"cc": "JP",
"region": "埼玉県",
"city": "さいたま市",
"street": "埼玉県さいたま市浦和区 常盤9-21-21",
"person": "Tanaka san",
"company": "さいたま国際キリスト教会",
"email": "saitamakyokai@gmail.com",
"phone": "0081-48-825-6637"
},
"options": {
"package_type": 1
},
"customs_declaration": {
"contents": 1,
"invoice": "1231235345345",
"weight": 30,
"items": [
{
"description": "Sample Product",
"amount": 10,
"weight": 20,
"item_value": {
"amount": 7000,
"currency": "EUR"
},
"classification": "0181",
"country": "NL"
},
{
"description": "Sample Product 2",
"amount": 5,
"weight": 10,
"item_value": {
"amount": 1000,
"currency": "EUR"
},
"classification": "0181",
"country": "BE"
}
]
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 3485394579,
"reference_identifier": null
}
]
}
}
PostNL: Create digital stamp shipments
Digital stamp shipments are available on
platform 1 (myparcel)
and to Dutch destinations only.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 4,
"label_description": "This is a digital stamp shipment!"
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 39234953,
"reference_identifier": null
}
]
}
}
PostNL: Create mailbox shipments
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 2,
"label_description": "This is a digital stamp shipment!"
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187520123,
"reference_identifier": null
}
]
}
}
PostNL: Create letter shipments
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 3,
"label_description": "This is a letter shipment!"
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187520123,
"reference_identifier": null
}
]
}
}
PostNL: Create domestic shipments for small package
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 6,
"label_description": "This is a shipment for small package!"
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187521125,
"reference_identifier": null
}
]
}
}
PostNL: Create European shipments for small package
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "FR",
"region": "Île-de-France",
"city": "Paris",
"street": "Rue de Rivoli",
"number": "1",
"postal_code": "75001",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 6,
"label_description": "This is a shipment for small package EU!",
"tracked": 1
},
"physical_properties": {
"weight": 30
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187591222,
"reference_identifier": null
}
]
}
}
PostNL: Create shipment with NL pickup location
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"delivery_type": 4,
"delivery_date": "2015-07-12 00:00:00",
"only_recipient": 0,
"signature": 1,
"return": 0
},
"pickup": {
"postal_code": "2132BH",
"street": "Burgemeester van Stamplein",
"city": "Hoofddorp",
"number": "270",
"location_name": "Albert Heijn"
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": null
}
]
}
}
PostNL: Create multi collo shipment with NL pickup location
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"return": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0,
"label_description": "My custom description",
"age_check": 1
},
"pickup": {
"postal_code": "2132BH",
"street": "Burgemeester van Stamplein",
"city": "Hoofddorp",
"number": "270",
"location_name": "Albert Heijn"
},
"secondary_shipments": [{}, {}],
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
PostNL: Create shipment with BE pickup location
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"recipient": {
"cc": "BE",
"postal_code": "2000",
"city": "Antwerpen",
"region": "België",
"street": "Adriaan Brouwerstraat 12",
"street_additional_info": "",
"person": "Mr. Parcel"
},
"pickup": {
"city": "ANTWERPEN",
"street": "HOOGSTRAAT",
"postal_code": "2000",
"number": "75",
"location_code": "BE0Q07",
"retail_network_id": "LD-01",
"location_name": "K&J TRADING"
},
"options": {
"package_type": 1,
"delivery_type": 4,
"delivery_date": "2017-08-09 16:00:00",
"only_recipient": 0,
"signature": 1,
"return": 0,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0,
"cooled_delivery": 0
},
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": null
}
]
}
}
PostNL: Create related return shipment
The following example creates a PostNL return shipment. On
platform 3 (belgie)
return shipments are only available with
carrier 2 (bpost)
.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.return_shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"return_shipments": [
{
"parent": 5,
"carrier": 1,
"email": "testing@myparcel.nl",
"name": "Mr. Parcel",
"options": {
"package_type": 1,
"only_recipient": 0,
"signature": 1,
"return": 0,
"insurance": {
"amount": 10000,
"currency": "EUR"
}
}
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": null
}
]
}
}
PostNL: Create unrelated return shipment
The following example creates a PostNL return shipment. On
platform 3 (belgie)
return shipments are only available with
carrier 2 (bpost)
.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.unrelated_return_shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"return_shipments": [
{
"options": {
"package_type": 1,
"only_recipient": 0,
"signature": 0,
"return": 0,
"insurance": {
"amount": 0,
"currency": "EUR"
},
"large_format": 0,
"label_description": "My custom description"
},
"carrier": 1,
"email": "testing@myparcel.nl",
"name": "Test"
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": null
}
]
}
}
DPD: Create domestic shipments
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "Shipment with DPD carrier"
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187592269,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
DPD: Create domestic mailbox shipments
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 2,
"label_description": "Shipment with DPD carrier"
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187592398,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
DPD: Create European shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "DE",
"region": "Friedrichshain-Kreuzberg",
"city": "Berlin",
"street": "Torstraße",
"number": "1",
"postal_code": "10119",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "European shipment with DPD carrier"
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187593050,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
DPD: Create domestic B2B shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl",
"company": "MyParcel"
},
"physical_properties": {
"weight": 1000,
"height": 10,
"width": 10,
"length": 12
},
"options": {
"package_type": 1,
"label_description": "reference",
"delivery_type": 2
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187593050,
"reference_identifier": "FOO-DPZ-BAR-46"
}
]
}
}
DPD: Create European B2B shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "FR",
"region": "Île-de-France",
"city": "Paris",
"street": "Rue de Rivoli",
"number": "1",
"postal_code": "75001",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl",
"company": "MyParcel"
},
"physical_properties": {
"weight": 1000,
"height": 10,
"width": 10,
"length": 12
},
"options": {
"package_type": 1,
"label_description": "reference",
"delivery_type": 2
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187593050,
"reference_identifier": "FOO-DPZ-BAR-46"
}
]
}
}
DPD: Create European shipment with DE pickup location
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "DE",
"region": "Berlin",
"postal_code": "10117",
"city": "Berlin",
"street": "Unter den Linden",
"number": "1",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"physical_properties": {
"weight": 1000,
"height": 10,
"width": 10,
"length": 12
},
"options": {
"package_type": 1,
"label_description": "European shipment with DPD carrier and pickup",
"delivery_type": 4
},
"pickup": {
"postal_code": "13057",
"location_name": "Foto Runge",
"city": "Berlin",
"street": "Warnitzer Straße",
"number": "16",
"cc": "DE",
"location_code": "68695056525155"
},
"carrier": 4
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 192789044,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
DHL for you: Create domestic shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"label_description": "Shipment with DHL for you",
"same_day_delivery": 1,
"hide_sender": 1
},
"carrier": 9
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187600832,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
DHL Parcel Connect: Create European shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "DE",
"region": "Friedrichshain-Kreuzberg",
"city": "Berlin",
"street": "Torstraße",
"number": "1",
"postal_code": "10119",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"signature": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"label_description": "This is a DHL Parcel Connect shipment for EU!"
},
"physical_properties": {
"weight": 30
},
"carrier": 10
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187602698,
"reference_identifier": "FOO-DPZ-BAR-46"
}
]
}
}
DHL Europlus: Create domestic (B2B) shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-DPZ-BAR-46",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl",
"company": "MyParcel"
},
"options": {
"package_type": 1,
"signature": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"label_description": "This is a shipment for DHL Europlus (B2B)",
"saturday_delivery": 1,
"hide_sender": 1
},
"physical_properties": {
"weight": 30
},
"carrier": 11
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187604041,
"reference_identifier": "FOO-DPZ-BAR-46"
}
]
}
}
UPS: Create European shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "DE",
"region": "Friedrichshain-Kreuzberg",
"city": "Berlin",
"street": "Torstraße",
"number": "1",
"postal_code": "10119",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "European shipment with ups carrier"
},
"physical_properties": {
"weight": 50
},
"carrier": 8
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187609913,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
UPS: Create International shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "US",
"postal_code": "12458",
"city": "Napanoch",
"street": "Avenue B 1 5 th",
"street_additional_info": "",
"number": "",
"state": "NY",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1
},
"customs_declaration": {
"contents": 1,
"invoice": "1231235345345",
"weight": 30,
"items": [
{
"description": "Sample Product",
"amount": 10,
"weight": 20,
"item_value": {
"amount": 7000,
"currency": "EUR"
},
"classification": "0181",
"country": "NL"
},
{
"description": "Sample Product 2",
"amount": 5,
"weight": 10,
"item_value": {
"amount": 1000,
"currency": "EUR"
},
"classification": "0181",
"country": "BE"
}
]
},
"physical_properties": {
"weight": 1000,
"height": 10,
"width": 10,
"length": 10
},
"carrier": 8
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 187641875,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
Create domestic bpost shipments
Bpost shipments are only supported on
platform 3 (belgie)
.
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"recipient": {
"cc": "BE",
"postal_code": "2000",
"city": "Antwerpen",
"street": "Wormerplein",
"number": "16",
"box_number": "",
"person": "test"
},
"options": {
"package_type": 1,
"signature": 0,
"saturday_delivery": 1,
"insurance": {
"amount": 0,
"currency": "EUR"
}
},
"carrier": 2,
"reference_identifier": "bpost shipment"
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 49566653,
"reference_identifier": "bpost shipment"
}
]
}
}
Create domestic DPD shipments on België
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;version=1.1;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"recipient": {
"cc": "BE",
"postal_code": "2000",
"city": "Antwerpen",
"street": "Wormerplein",
"number": "16",
"box_number": "",
"person": "test"
},
"options": {
"package_type": 1
},
"carrier": 4,
"reference_identifier": "Order 123456"
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 49566517,
"reference_identifier": "Order 123456"
}
]
}
}
Create bpost shipment with BE pickup location
Only available on
platform 3 (belgie)
.
Request
POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"carrier": 2,
"recipient": {
"cc": "BE",
"city": "Antwerpen",
"street": "Adriaan Brouwerstraat",
"number": "16",
"person": "Test",
"postal_code": "2000"
},
"options": {
"package_type": 1,
"delivery_type": 4
},
"pickup": {
"city": "ANTWERPEN",
"location_code": "618925",
"location_name": "KLAPKRANT",
"number": "15",
"postal_code": "2000",
"street": "KLAPDORP"
},
"reference_identifier": "order-012356"
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 49571535,
"reference_identifier": "order-012356"
}
]
}
}
Create DPD shipment with BE pickup location
Only available on
platform 3 (belgie)
.
Request
POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"carrier": 4,
"recipient": {
"cc": "BE",
"city": "Antwerpen",
"street": "Adriaan Brouwerstraat",
"number": "16",
"person": "Test",
"postal_code": "2000"
},
"options": {
"package_type": 1,
"delivery_type": 4
},
"pickup": {
"postal_code": "2000",
"location_name": "PRESS WINKEL",
"city": "Antwerpen",
"street": "HOOGSTRAAT",
"number": "75",
"cc": "BE",
"location_code": "BE11468"
},
"reference_identifier": "DPD pickup"
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 49571535,
"reference_identifier": "DPD pickup"
}
]
}
}
6.C Delete Shipment
Deleting shipments is not done often. This can only be done for shipments for which a label has not yet been created (shipment-status 1 (pending - concept)
). Especially since shipments not handed over to the distributor will not be billed by MyParcel. Therefore, when unused shipments are not deleted this has no financial consequences.
6.C.1 Overview
Use this link to remove shipments. You can specify multiple shipment ids by semicolon separating them on the URL. Only shipments with shipment-status 1 (pending - concept)
can be deleted. This method returns HTTP 204 No Content
if successful. If the shipment doesn't exist a HTTP 422 Unprocessable Entity
is returned.
6.C.2 Reference
URI | https://api.myparcel.nl/shipments/id[;id] |
Methods | DELETE |
Required request headers | Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
Content-type: application/json;charset=utf-8 |
URI parameters | id = [Shipment].id |
Query parameters | None. |
Request body | None. |
Response | HTTP 204 No Content |
Response body | None. |
Error response | HTTP 4xx . |
Error response body | Error |
6.C.3 Parameters
id
Data type: integer
The id of the shipment to delete. You can specify multiple shipments by semicolon separating them.
6.C.4 Examples
Remove a shipment with id 1234.
Request
DELETE https://api.myparcel.nl/shipments/1234 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Response
HTTP 204 No Content
6.D Generate unrelated return shipment URL
6.D.1 Overview
This endpoint is often used by external parties to facilitate return shipments on a dedicated part of their website, mainly when offering reverse logistics e.g. repair services. It will allow the consumer to send packages to the merchant directly from the merchant's website. If this option is not enable then HTTP 404 Not Found
Not Found is returned.
6.D.2 Reference
URI | https://api.myparcel.nl/return_shipments |
Methods | POST |
Required request headers | Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
URI parameters | None. |
Query parameters | None. |
Request body | None. |
Response | HTTP 200 OK Content-Type: application/json |
Response body | DownloadUrl object. |
Error response | HTTP 4xx |
HTTP 5xx |
Error response body | None. |
6.D.3 Examples
Generate unrelated return shipment
Request
POST https://api.myparcel.nl/return_shipments
User-Agent: CustomApiCall/2
HTTP/1.1 Authorization: basic
eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Response
HTTP 200 OK
Content-Type: application/json
{
"data": {
"download_url": {
"link": "https://myparcel.me/returns/902223ede2f50288ecfbbd21a8c8fd7e"
}
}
}
6.E Get Shipment
6.E.1 Overview
With this endpoint you can get shipments. You can use the 'q' query parameter to search for shipments. Depending on the Accept request header either JSON or CSV is returned. Multiple shipment ids can be specified on the URI by using semicolon. There are limitation when getting data back as CSV. When using CSV you will only get the most recent status of shipment.
Upon success either a JSON array of Shipment objects or a CSV file is returned.
6.E.2 Reference
URI | https://api.myparcel.nl/shipments/[id[;id]] |
Methods | GET |
Required request headers | Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
URI parameters | id = [Shipment].id |
Query parameters | q = string |
reference_identifier = [reference_identifier] |
dropoff_today = boolean |
status = shipment_status |
from = timestamp |
to = timestamp |
page = integer |
size = integer |
sort = string |
order = sort_order |
Optional request headers | Accept: application/json;charset=utf-8 (For JSON) |
Request body | None. |
Response | HTTP 200 OK |
Content-Type: application/json;charset=utf-8 (For JSON) |
Response body | array of Shipment objects (For JSON) |
Error response | HTTP 4xx |
Error response body | Error |
6.E.3 Parameters
id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semicolon separating them on the URI.
reference_identifier
Data type: string
This is an optional arbitrary identifier to identify the shipment.
dropoff_today
Data type: boolean
Use this parameter to filter for shipments that need to dropped at a PostNL location today.
q
Data type: string
Use this parameter to search through all the fields of a shipment object including the embedded objects
status
Data type: shipment_status
Use this parameter to specify the shipment status to filter on. You can specify multiple status by semicolon separating them on the URI.
from
Data type: date
Use this parameter to filter on the shipment creation date. This filter will set the lower bound of the date search range.
to
Data type: date
Use this parameter to filter on the shipment creation date. This filter will set the upper bound of the date search range.
page
Data type: integer
Page number. Maximum value is 1000 and minimum is 1. Defaults to 1.
size
Data type: integer
Items per page. Maximum value is 200 and minimum is 30. Defaults to 30.
sort
Data type: string
Shipment object field to sort on. See Shipment object
order
Data type: sort_order
Sort order for sort filter. Defaults to ASC.
6.E.4 Examples
Search for shipments
Search shipments for fields containing 'Niels' with status 'pending'. The first shipment has 'Jan' in the person field.
Request
GET https://api.myparcel.nl/shipments?q=Niels&status=1
User-Agent: CustomApiCall/2
HTTP/1.1 Authorization: basic
eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Response
HTTP 200 OK
{
"data": {
"search_results": {
"shipments": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"return": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0
},
"sender": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Amsterdam",
"street": "Dorpstraat",
"number": "123",
"postal_code": "1020BC",
"person": "Mrs. Parcel",
"phone": "02012343546",
"email": "info@myparcel.nl"
},
"carrier_id": 1,
"status": 1,
"price": {
"amount": 535,
"currency": "EUR"
},
"barcode": "3SMYPA77773333",
"secondary_shipments": null,
"multi_collo_main_shipment_id": null,
"created": "2017-01-31 08:00:00",
"modified": "2017-01-31 09:00:00"
}
],
"page": 1,
"size": 30,
"results": 50
}
}
}
6.F Get Shipment label
6.F.1 Overview
Get shipment label. You can specify label format and starting position of labels on the first page with the format and position query parameters. The ** position** query only works when you specify the A4 format and is only applied on the first page with labels.Accounts with Post-payment payment methods can fetch multiple labels in one call. For accounts with Pre-payment payment method an <Http code=402 /> Payment Required
with a PaymentInstructions object is returned if the label has not been paid for yet.
When a label for a multi collo shipment is requested, labels for all shipments part of the multi collo shipment will be generated. Each shipment within a multi collo shipment MUST be labeled with a specific label containing a unique barcode.
Upon error HTTP 4xx
with a response body containing an Error is returned.
If you want to retrieve more than 25 labels in one response, you can use Accept: application/vnd.shipment_label_link+json;charset=utf8
. You will receive a URL to a label, but the label is not immediately available and will return an HTTP 404 Not Found
until it is ready. Depending on the number of labels, this process will take between 3 seconds and 3 minutes. You can regularly check whether the label is available or you can use the label_created webhooks.
When you want to retrieve ZPL labels you need to use a different Accept header. 'Accept: application/vnd.shipment_label+zpl' or 'Accept: application/vnd.zpl' You will now receive the ZPL label. Currently, our system supports only PostNL and Bpost labels in ZPL format for the following shipment types:
- Domestic shipments for both normal packages and mailbox packages.
- EU shipments
If you request a rest of world label, the system will return a label in PDF format. Additionally, it's important to note that you can request just one label at a time.
For Bpost shipments, you can request a label in ZPL format only if you have not requested a PDF label before. After you requested a ZPL label, you can also request a PDF label.
6.F.2 Reference
URI | https://api.myparcel.nl/shipment_labels/id[;id] |
Methods | GET |
Required request headers | Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
Accept: application/pdf (For the PDF binary. This is the default.) For processing less than 25 labels. |
Accept: application/json;charset=utf8 (For ShipmentLabelDownloadLink) For processing less than 25 labels. |
Accept: application/vnd.shipment_label_link+json;charset=utf8 (For ShipmentLabelDownloadLink) For processing multiple labels. Recommended if you request more than 25 labels. |
URI parameters | id = Shipment.id |
Query parameters | format = paper_size |
positions = label_position |
Request body | None. |
Response | HTTP 200 OK Content-Disposition: attachment; filename="PDF_FILE" Content-Type: application/pdf |
HTTP 200 OK Content-Type: application/json(When using "Accept: application/json;charset=utf8" or "Accept: application/vnd.shipment_label_link+json;charset=utf8") |
Response body | Shipment label PDF |
ShipmentLabelDownloadLink |
PaymentInstructions |
Error response | HTTP 402 Payment Required |
Error response body | Content-Type: application/json (When payment is required) |
6.F.3 Parameters
id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semicolon separating them on the URI.
format
Data type: paper_size
The paper size of the PDF. Currently, A4 and A6 are supported. When A4 is chosen you can specify the label position. When requesting the label for a shipment that contains a custom form, you can only request a A4 format.
positions
Data type: label_position
The position of the label on an A4 sheet. You can specify multiple positions by semicolon separating them on the URI. Positioning is only applied on the first page with labels. All subsequent pages will use the default positioning 1,2,3,4.
6.F.4 Examples
Get Shipment label
Request
GET https://api.myparcel.nl/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Response
HTTP 200 OK
Content-Disposition: attachment;filename="123123123.pdf"
Content-Type: application/pdf
(...PDF content)
Get shipment label download link
Request
GET https://api.myparcel.nl/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Accept: application/json;charset=utf-8
Response
HTTP 200 OK
{
"data": {
"pdfs": {
"url": "https://api.myparcel.nl/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
}
}
}
Get shipment label download link to handle multiple labels
Request
GET https://api.myparcel.nl/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Accept: application/vnd.shipment_label_link+json;charset=utf8
Response
HTTP 200 OK
{
"data": {
"pdfs": {
"url": "/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
}
}
}
Get shipment label with different format and position
Get label for shipment with id 2. The label will be printed on an A4 sheet and the label position will be at the bottom-right.
Request
GET https://api.myparcel.nl/shipment_labels/2?format=A4&positions=3;4 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Response
HTTP 200 OK
Content-Disposition: attachment; filename="456456456456.pdf" Content-Type:
application/pdf (...PDF content)
6.G Track Shipment
6.G.1 Overview
Get detailed Track & Trace information for a shipment. Upon success HTTP 200 OK
is returned with an array of TrackTrace objects.
6.G.2 Limitations
For retrieving Track & Trace data, we recommend passing multiple shipment IDs at once to avoid hitting the rate limit .
6.G.3 Reference
URI | https://api.myparcel.nl/tracktraces/id[;id] |
Methods | GET |
Required | request headers Authorization: basic BASE64(API_KEY) |
User-Agent: CustomApiCall/2 |
URI parameters | id= [Shipment].id |
Query parameters | page= integer |
size= integer |
sort= string |
order= sort_order |
extra_info= [extra_info] |
Request body | None. |
Response | HTTP 200 OK |
Content-Type: application/json;charset=utf-8 |
Response body | array of TrackTrace objects. |
Error response | HTTP 4xx |
Error response body | Error |
6.G.4 Parameters
id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semicolon separating them on the URI.
page
Data type: integer
Page number. Maximum value is 1000 and minimum is 1. Defaults to 1.
size
Data type: integer
Items per page. Maximum value is 200 and minimum is 30. Defaults to 30.
sort
Data type: string
TrackTrace object field to sort on. See TrackTrace
order
Data type: sort_order
Sort order for sort filter. Defaults to ASC.
extra_info
Data type: string
Only the delivery_moment option is available. Delivery moment is not included by default for performance reasons. Example:
extra_info=delivery_moment
6.G.5 Examples
Details Request
GET https://api.myparcel.nl/tracktraces/1212321?extra_info=delivery_moment
HTTP/1.1
User-Agent: CustomApiCall/2
Accept-Language: en_GB
Authorization: bearer BASE64_ENCODED_API_KEY
Response
HTTP 200 OK
{
"data": {
"tracktraces": [
{
"shipment_id": 43393092,
"code": "I01",
"description": "Zending bezorgd",
"time": "2019-02-16 15:09:53",
"link_consumer_portal": "https://postnl.nl/tracktrace/?B=3SMYPA126329191&P=2182KD&D=NL&T=C&L=NL",
"link_tracktrace": "https://postnl.nl/tracktrace/?B=3SMYPA126329191&P=2182KD&D=NL&T=C&L=NL",
"recipient": {
"cc": "NL",
"postal_code": "2231je",
"city": "Potloden dorp",
"street": "Gumlaan",
"number": "101",
"number_suffix": "",
"person": "Hard Kauwer"
},
"sender": {
"cc": "NL",
"postal_code": "4337WA",
"city": "Middelburg",
"street": "Jacobus Spijkerdreef",
"number": "10",
"person": "Tamara Faker",
"company": "Potlodenshop",
"email": "tamluca@potlodenshop.nl",
"phone": "0673826485"
},
"options": {
"package_type": 1,
"only_recipient": 0,
"signature": 0,
"return": 0,
"insurance": {
"amount": 0,
"currency": "EUR"
},
"large_format": 0,
"cooled_delivery": 0,
"age_check": 0
},
"pickup": null,
"delayed": false,
"location": {
"name": "Depot Den Bosch",
"cc": "NL",
"city": "S-Hertogenbosch",
"postal_code": "5222AL",
"street": "Ketelaarskampweg",
"number": "7",
"number_suffix": null,
"longitude": 5.27349901,
"latitude": 51.70326781
},
"status": {
"current": 7,
"main": "delivered",
"final": true
},
"history": [
{
"code": "A01",
"status": 2,
"main": "registered",
"description": "De zending is aangemeld bij PostNL en wordt volgbaar",
"time": "2019-02-15 00:00:00",
"delayed": false,
"location": {
"name": "Depot Den Bosch",
"cc": "NL",
"city": "S-Hertogenbosch",
"postal_code": "5222AL",
"street": "Ketelaarskampweg",
"number": "7",
"number_suffix": null,
"longitude": 5.27349901,
"latitude": 51.70326781
}
},
{
"code": "B01",
"status": 3,
"main": "handed_to_carrier",
"description": "Zending is ontvangen door PostNL",
"time": "2019-02-15 17:09:55",
"delayed": false,
"location": null
},
{
"code": "J01",
"status": 4,
"main": "sorting",
"description": "Zending gesorteerd in sorteercentrum",
"time": "2019-02-16 08:13:29",
"delayed": false,
"location": null
},
{
"code": "J05",
"status": 5,
"main": "distribution",
"description": "Bezorger is onderweg",
"time": "2019-02-16 08:35:51",
"delayed": false,
"location": null
}
],
"delivery_moment_type": "estimated",
"delivery_moment": {
"start": {
"date": "2019-02-19 17:15:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2019-02-19 19:45:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
}
]
}
}
6.H Multi collo shipments
6.H.1 Overview
This section describes the working of multi collo shipments. The multi collo shipment is a special name of shipment which requires a specific way of handling. A multi collo shipment is a shipment which contains multiple packages for the same address and the same delivery date. It contains of one 'main' shipment and at least one 'secondary' shipment. Working with multi collo shipments does not require using specific endpoints but existing endpoints have specific behaviour in combination with multi collo shipments.
6.H.2 Create
This section extends the base functionality.
Creating a multi collo shipment basically means using one extra property secondary_shipments
. This property can be used to pass an array of json objects. Each object represents an extra shipment to be part of the multi collo shipment. All required properties of the main shipment are inherited by the secondary shipments so there is no need to pass data with a secondary shipment, but it is allowed to pass specific data. This might be useful for example to pass a specific reference identifier per secondary shipment. Shipment options MUST be provided only with the main shipment. Secondary shipments only can be used in combination with package-type 1 (package)
and can only be used for shipments to NL en BE.
{
"secondary_shipments": [
{
"reference_identifier": "SECONDARY-SHIPMENT"
}
]
}
6.H.3 Update
URI | https://api.myparcel.nl/shipments |
Methods | PUT |
Required request headers | Authorization: basic BASE64(API_KEY) |
Content-Type: application/vnd.shipment+json;version=1.1 |
Updating a secondary shipment can be done in several ways using different endpoints.
Add secondary shipment
Adding an existing shipment to an existing multi collo shipment can be done in two ways.
- Post complete shipment with an extra shipment passed in the
secondary_shipments
property.
{
"secondary_shipments": [
{
"id": 12345
},
{
"id": 34567
}
]
}
- Update a single existing shipment with a reference to a multi collo shipment via the
multi_collo_main_shipment_id
.
{
"multi_collo_main_shipment_id": 34567
}
Adding a non-existent shipment to an existing multi collo shipment can be done via the secondary_shipments
property of the main shipment.
{
"secondary_shipments": [
{
"id": 12345
}
]
}
Note that the existing secondary shipments should always be passed as well because they will be deleted otherwise.
Remove secondary shipment
Removing a secondary shipment from a multi collo shipment can be done in 3 different ways.
Delete secondary shipment. Make use of the delete endpoint when passing the id of the secondary shipment. This will cause the secondary shipment to be deleted and removed from the multi collo shipment.
Omit the secondary shipment in an update request on the multi collo main shipment. This will cause the secondary shipment to be deleted and be removed from the multi collo shipment.
Unlink a secondary shipment from the multi collo shipment. This is done by a PUT request for a specific secondary shipment with an empty reference to the multi collo main shipment. This will cause the shipment to be removed from the multi collo shipment and still be available as normal shipment. The data passed in the PUT request for secondary shipment 1234 to remove it from its multi collo shipment should contain besides all other required data:
{
"id": 1234,
"multi_collo_main_shipment_id": null
}
6.H.4 Delete
This section extends the base functionality. Deleting a multi collo main shipment will result in a complete removal of the main and secondary shipments of the multi collo shipment.
Deleting a secondary shipment will result in deleting the shipment and removal of the secondary shipment from the multi collo shipment.
6.H.5 Examples
Create national multi collo shipment
Request
POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"only_recipient": 1,
"signature": 1,
"return": 1,
"insurance": {
"amount": 50000,
"currency": "EUR"
},
"large_format": 0,
"label_description": "My custom description",
"age_check": 1
},
"secondary_shipments": [
{
"reference_identifier": "REF-SECONDARY-SHIPMENT"
}
],
"carrier": 1
}
]
}
}
Response
HTTP 200 OK
{
"data": {
"ids": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42"
}
]
}
}
Add new shipment to existing multi collo shipment
This example adds a new shipment to multi collo shipment 12345
Request
PUT https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "My custom description"
},
"secondary_shipments": [
{
"id": 12346,
"reference_identifier": "SECONDARY-SHIPMENT"
},
{}
],
"carrier": 1
}
]
}
}
Response
Add existing shipment to existing multi collo shipment
This example adds existing shipment 12346 to multi collo shipment 12345
Request
PUT https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"id": 12346,
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "My custom description"
},
"carrier": 1,
"multi_collo_main_shipment_id": 12345
}
]
}
}
Response
Delete and remove shipment from multi collo shipment
This example deletes and removes existing shipment 12346 from multi collo shipment 12345 by omitting the shipment in the secondary shipment property
Request
PUT https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
{
"data": {
"shipments": [
{
"id": 12345,
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "My custom description"
},
"secondary_shipments": [
{
"id": 12347,
"reference_identifier": "SECONDARY-SHIPMENT"
}
],
"carrier": 1
}
]
}
}
Response
Remove shipment from multi collo shipment without deletion
This example removes existing shipment 12346 from multi collo shipment 12345 by removing the relation to the multi collo main shipment.
Request
PUT https://api.myparcel.nl/shipments HTTP/1.1
Content-Type: application/vnd.shipment+json;charset=utf-8;version=1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
`
```json
{
"data": {
"shipments": [
{
"id": 12346,
"reference_identifier": "FOO-222-BAR-42",
"recipient": {
"cc": "NL",
"region": "Zuid-Holland",
"city": "Hoofddorp",
"street": "Antareslaan",
"number": "31",
"postal_code": "2132JE",
"person": "Mr. Parcel",
"phone": "0233030315",
"email": "testing@myparcel.nl"
},
"options": {
"package_type": 1,
"label_description": "My custom description"
},
"carrier": 1,
"multi_collo_main_shipment_id": null
}
]
}
}
Response
Delete and remove shipment from a multi collo shipment via DELETE request
This example deletes and removes existing shipment 12346 from multi collo shipment by deleting the secondary shipment.
Request
DELETE https://api.myparcel.nl/shipments/12346 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Response