To homepage
HomeAPI Reference6. Shipments

6. Shipments

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.

Run in Postman

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.

large_format

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

Pickup
Evening
NL insured
EU and Global insured

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

URIhttps://api.myparcel.nl/shipments
MethodsPOST
Required request headersAuthorization: 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 parametersNone.

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)

ResponseHTTP 200 OK Content-Type: application/vnd.shipment_ids+json;charset=utf-8 (For standard and related return shipment.)
Response bodyShipmentIds
Error responseHTTP 4xx
Error response bodyError

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.

Platform 1 (myparcel)

PostNL: Create domestic shipments

PostNL: Create domestic multi collo shipments

PostNL: Create International shipment

PostNL: Create digital stamp shipments

PostNL: Create mailbox shipments

PostNL: Create letter shipments

PostNL: Create domestic shipments for small package

PostNL: Create European shipments for small package

PostNL: Create shipment with NL pickup location

PostNL: Create multi collo shipment with NL pickup location

PostNL: Create shipment with BE pickup location

PostNL: Create related return shipment

PostNL: Create unrelated return shipment

DPD: Create domestic shipments

DPD: Create domestic mailbox shipments

DPD: Create European shipment

DPD: Create domestic B2B shipment

DPD: Create European B2B shipment

DPD: Create European shipment with DE pickup location

DHL for you: Create domestic shipment

DHL Parcel Connect: Create European shipment

DHL Europlus: Create domestic (B2B) shipment

UPS: Create European shipment

UPS: Create International shipment

Platform 3 (belgie)

Create domestic bpost shipments

Create domestic DPD shipments on België

Create bpost shipment with BE pickup location

Create DPD shipment with BE pickup location

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

URIhttps://api.myparcel.nl/shipments/id[;id]
MethodsDELETE
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
Content-type: application/json;charset=utf-8
URI parametersid = [Shipment].id
Query parametersNone.
Request bodyNone.
ResponseHTTP 204 No Content
Response bodyNone.
Error responseHTTP 4xx.
Error response bodyError

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.

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

URIhttps://api.myparcel.nl/return_shipments
MethodsPOST
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
URI parametersNone.
Query parametersNone.
Request bodyNone.
ResponseHTTP 200 OK Content-Type: application/json
Response bodyDownloadUrl object.
Error responseHTTP 4xx
HTTP 5xx
Error response bodyNone.

6.D.3 Examples

Generate unrelated return shipment

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

URIhttps://api.myparcel.nl/shipments/[id[;id]]
MethodsGET
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
URI parametersid = [Shipment].id
Query parametersq = 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 headersAccept: application/json;charset=utf-8 (For JSON)
Request bodyNone.
ResponseHTTP 200 OK
Content-Type: application/json;charset=utf-8 (For JSON)
Response bodyarray of Shipment objects (For JSON)
Error responseHTTP 4xx
Error response bodyError

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

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

URIhttps://api.myparcel.nl/shipment_labels/id[;id]
MethodsGET
Required request headersAuthorization: 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 parametersid = Shipment.id
Query parametersformat = paper_size
positions = label_position
Request bodyNone.
ResponseHTTP 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 bodyShipment label PDF
ShipmentLabelDownloadLink
PaymentInstructions
Error responseHTTP 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

Get shipment label download link

Get shipment label download link to handle multiple labels

Get shipment label with different format and position

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

URIhttps://api.myparcel.nl/tracktraces/id[;id]
MethodsGET
Requiredrequest headers Authorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
URI parametersid= [Shipment].id
Query parameterspage= integer
size= integer
sort= string
order= sort_order
extra_info= [extra_info]
Request bodyNone.
ResponseHTTP 200 OK
Content-Type: application/json;charset=utf-8
Response bodyarray of TrackTrace objects.
Error responseHTTP 4xx
Error response bodyError

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

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

URIhttps://api.myparcel.nl/shipments
MethodsPUT
Required request headersAuthorization: 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.

  1. Post complete shipment with an extra shipment passed in the secondary_shipments property.
{
  "secondary_shipments": [
    {
      "id": 12345
    },
    {
      "id": 34567
    }
  ]
}
  1. 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.

  1. 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.

  2. 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.

  3. 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

Add new shipment to existing multi collo shipment

Add existing shipment to existing multi collo shipment

Delete and remove shipment from multi collo shipment

Remove shipment from multi collo shipment without deletion

Delete and remove shipment from a multi collo shipment via DELETE request

Edit this page
Last updated: 
Contributors Peter-MyParcel
To homepage
Conditions & Policyopen in new windowCookie statementopen in new windowPrivacy statementopen in new window