8.A Get delivery options
To easily show delivery options and pickup locations to customers, you can use [our standalone Delivery Options module].
8.A.1 Overview
Defaults Get the delivery options for a given location and carrier. If none of the optional parameters are specified then the following default will be used: If a request is made for the delivery options between Friday after the default cutoff_time (15:30) and Monday before the default cutoff_time (15:30) then Tuesday will be shown as the next possible delivery date.
Objects Upon success two arrays are returned; one for DeliveryOptions and one for PickupOptions objects is returned. This object contains delivery date, time and pricing. Upon error an Error object is returned.
8.A.2 Reference
| URI | https://api.myparcel.nl/delivery_options | |
| https://api.myparcel.nl/pickup_locations | |
| Methods | GET | |
| URI parameters | – | |
| Query parameters | cc | country_code |
| postal_code | string |
| number | string |
| city | string |
| street | string |
| platform | platform |
| carrier | carrier |
| delivery_time | time |
| delivery_date | date |
| cutoff_time | time |
| dropoff_days | weekday_digit |
| monday_delivery | boolean |
| dropoff_delay | integer |
| deliverydays_window | integer |
| exclude_delivery_type | delivery_type |
| exclude_parcel_lockers | boolean |
| latitude | coordinates |
| longitude | coordinates |
| Request body | None. | |
| Response | HTTP/1.1 200 OK | |
| Content-Type: | application/json;version=2.0 charset=utf-8 | |
| Response body | array of DeliveryOptions or array of PickupOptions objects | |
| Error response | HTTP/1.1 5xx < MESSAGE > | |
| Error response body | None. | |
| Error response | HTTP/1.1 503 < MESSAGE > | |
| Error response body 503 | Error | |
| Error response body Example | {"data": {"delivery": [],"pickup": [],"message": "No results"},"errors": [{"code": 9,"message": "Example","human": "Example"}]} | |
8.A.3 Parameters
cc
Data type: country_code
Required: yes
The country code for which to fetch the delivery options. This endpoint can only be used in the Netherlands or Belgium ( cc=NL or cc=BE ).
postal_code
Data type: string
Required: yes.
The postal code for which to fetch the delivery options.
number
Data type: string
Required: yes
The street number for which to fetch the delivery options.
city
Data type: string
Required: no
Only available for carriers bpost and DPD. This can be used to narrow the search results for locations outside NL.
street
Data type: string
Required: no
This can be used to narrow the search results for locations outside NL.
platform
Data type: platform
Required: no
The platform where you want the data from
delivery_time
Data type: time
Required: no
The time on which a package has to be delivered.
Note: This is only an indication of time the package will be delivered on the selected date.
delivery_date
Data type: date
Required: no
The date on which the package has to be delivered.
cutoff_time
Data type: time
Required: no
This option allows the Merchant to indicate the latest cutoff time before which a consumer order will still be picked, packed and dispatched on the same/first set drop-off day, taking into account the drop-off delay. Default time is 15:30. For example, if cutoff time is 15:30, Monday is a delivery day and there's no delivery delay; all orders placed Monday before 15:30 will be dropped of at PostNL on that same Monday in time for the Monday collection.
dropoff_days
Data type: weekday_digit
Required: no
This options allows the Merchant to set the days she normally goes to PostNL to hand in her parcels. By default Saturday and Sunday are excluded.
monday_delivery
Data type: boolean
Required: no
Monday delivery is only possible when the package is delivered before 15.00 on Saturday at the designated PostNL locations. Click here for more information concerning Monday delivery and the locations.
Note: To activate Monday delivery, value 6 must be given with [dropoff_days], value 1 must be given by [monday_delivery]. And on Saturday the [cutoff_time] must be before 15:00 (14:30 recommended) so that Monday will be shown.
saturday_delivery
Data type: boolean
Required: no
Saturday delivery is only possible when the package is delivered before 15.00 on Friday at the designated bpost locations.
Note: To activate Saturday delivery, value 6 must be given with [dropoff_days], value 1 must be given by saturday_delivery.
dropoff_delay
Data type: integer (0 – 14) Required: no
This options allows the Merchant to set the number of days it takes them to pick, pack and hand in their parcels at PostNL when ordered before the cutoff time. The default value is 0.
deliverydays_window
Data type: integer
Required: no
This options allows the Merchant to set the number of days into the future for which they want to show their consumers delivery options. For example, if set to 3 in their check-out, a consumer ordering on Monday will see possible delivery options for Tuesday, Wednesday and Thursday (provided there is no drop-off delay, it's before the cutoff time, and they go to PostNL on Mondays). Min is 1. and max. is 14.
exclude_delivery_type
Data type: delivery_type
Required: no
This options allows the Merchant to exclude delivery types from the available delivery options. You can specify multiple delivery types by semicolon separating them. The standard delivery name cannot be excluded.
exclude_parcel_lockers
Data type: boolean
Required: no
This option allows to filter out pickup locations that are parcel lockers.
latitude
Data type: coordinates
Required: no
This provides the ability to display the postNL locations through the coordinates. If only latitude or longitude is passed as a parameter, it will be ignored and will simply use zip code for searching locations.
longitude
Data type: coordinates
Required: no
This provides the ability to display the postNL locations through the coordinates. If only latitude or longitude is passed as a parameter, it will be ignored and will simply use zip code for searching locations.
8.A.4 Examples
Get delivery options for 2132JE, 31 for PostNL
Request
GET https://api.myparcel.nl/delivery_options?platform=myparcel&carrier=postnl&cc=nl&number=31&postal_code=2132JE HTTP/1.1
accept: application/json;charset=utf-8;version=2.0
Response
HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
"data": {
"delivery": [
{
"date": "2017-02-01",
"time": [
{
"start": "08:00:00",
"end": "12:00:00",
"price": {
"currency": "EUR",
"amount": 1000
},
"price_comment": "morning",
"comment": "",
"name": 1
},
{
"start": "11:30:00",
"end": "13:30:00",
"price": {
"currency": "EUR",
"amount": 0
},
"price_comment": "standard",
"comment": "",
"name": 2
}
]
},
{
"date": "2017-02-02",
"time": [
{
"start": "08:00:00",
"end": "12:00:00",
"price": {
"currency": "EUR",
"amount": 1000
},
"price_comment": "morning",
"comment": "",
"name": 1
},
{
"start": "11:00:00",
"end": "13:00:00",
"price": {
"currency": "EUR",
"amount": 0
},
"price_comment": "standard",
"comment": "",
"name": 2
}
]
}
],
"pickup": [
{
"date": "2017-02-01",
"time": [
{
"start": "16:00:00",
"name": 4,
"price": {
"amount": 0,
"currency": "EUR"
}
},
{
"start": "08:30:00",
"name": 5,
"price": {
"amount": 125,
"currency": "EUR"
}
}
],
"location": "Staples Office Centre",
"street": "Jacobus Spijkerdreef",
"number": "10",
"postal_code": "2132PZ",
"city": "Hoofddorp",
"start_time": "08:30:00",
"price": 125,
"price_comment": "retailexpress",
"comment": "Dit is een Business Point. Post en pakketten die u op werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.",
"phone_number": "023-5576310",
"opening_hours": {
"monday": ["08:00-18:30"],
"tuesday": ["08:00-18:30"],
"wednesday": ["08:00-18:30"],
"thursday": ["08:00-18:30"],
"friday": ["08:00-18:30"],
"saturday": ["08:00-17:00"],
"sunday": []
},
"distance": "1934",
"latitude": "52.286582",
"longitude": "4.682377",
"location_code": "173187"
},
{
"date": "2017-02-01",
"time": [
{
"start": "16:00:00",
"name": 4,
"price": {
"amount": 0,
"currency": "EUR"
}
}
],
"location": "Primera Sanders",
"street": "Polderplein",
"number": "3",
"postal_code": "2132BA",
"city": "Hoofddorp",
"start_time": "16:00:00",
"price": 0,
"price_comment": "retail",
"comment": "Dit is een Postkantoor. Post en pakketten die u op werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.",
"phone_number": "023-5640556",
"opening_hours": {
"monday": ["11:00-18:00"],
"tuesday": ["09:00-18:00"],
"wednesday": ["09:00-18:00"],
"thursday": ["09:00-18:00"],
"friday": ["09:00-21:00"],
"saturday": ["09:00-17:00"],
"sunday": ["12:00-17:00"]
},
"distance": "1687",
"latitude": "52.192150633052",
"longitude": "4.44249030539514",
"location_code": "176227"
},
{
"date": "2017-02-01",
"time": [
{
"start": "16:00:00",
"name": 4,
"price": {
"amount": 0,
"currency": "EUR"
}
}
]
}
]
}
}
Get pickup locations for 2132JE, 31 for PostNL
Request
GET https://api.myparcel.nl/pickup_locations?carrierName=postnl&platform=myparcel&carrier=postnl&cc=nl&number=31&postal_code=2132JE HTTP/1.1
accept: application/json;charset=utf-8;version=2.0
Response
HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
"data": {
"pickup_locations": [
{
"address": {
"cc": "NL",
"city": "Hoofddorp",
"street": "Polderplein",
"postal_code": "2132BA",
"number": "3"
},
"possibilities": [
{
"delivery_type_id": 4,
"delivery_type_name": "pickup",
"moment": {
"start": {
"date": "2020-02-13 16:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
}
],
"location": {
"location_name": "Primera Sanders",
"retail_network_id": "PNPNL-01",
"distance": "1696",
"latitude": "52.30329367",
"longitude": "4.69476214",
"location_code": "176227",
"phone_number": null,
"opening_hours": {
"monday": [
{
"start": {
"date": "2020-02-17 11:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-17 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"tuesday": [
{
"start": {
"date": "2020-02-18 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-18 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"wednesday": [
{
"start": {
"date": "2020-02-19 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-19 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"thursday": [
{
"start": {
"date": "2020-02-13 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-13 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"friday": [
{
"start": {
"date": "2020-02-14 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-14 21:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"saturday": [
{
"start": {
"date": "2020-02-15 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-15 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"sunday": [
{
"start": {
"date": "2020-02-16 12:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-16 17:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
]
}
}
}
]
}
}
Get delivery options with a lot of options
- Destination: 2132JE 31
- PostNL
- cutoff time 16:00
- dropoff days Mon - Sat
- dropoff delay: 0
- delivery days window: 2
- no morning
Request
GET https://api.myparcel.nl/delivery_options?platform=myparcel&carrier=postnl&cc=nl&number=31&postal_code=2132JE&cutoff_time=16:00:00&dropoff_days=1;2;3;4;5;6&monday_delivery=1&dropoff_delay=0&deliverydays_window=2&exclude_delivery_type=1 HTTP/1.1
Accept: application/json;charset=utf-8;version=2.0
Response
HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
"data": {
"deliveries": [
{
"date": {
"date": "2020-02-13 00:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"possibilities": [
{
"name": "standard",
"shipment_options": [
{
"name": "age_check",
"schema": {
"name": "boolean",
"enum": [true, false]
}
},
{
"name": "large_format",
"schema": {
"name": "boolean",
"enum": [true, false]
}
},
{
"name": "only_recipient",
"schema": {
"name": "boolean",
"enum": [true, false]
}
},
{
"name": "signature",
"schema": {
"name": "boolean",
"enum": [true, false]
}
},
{
"name": "return",
"schema": {
"name": "boolean",
"enum": [true, false]
}
}
],
"collect_date": null,
"delivery_time_frames": [
{
"name": "start",
"date_time": {
"date": "2020-02-13 09:30:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
},
{
"name": "end",
"date_time": {
"date": "2020-02-13 12:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
]
}
]
}
]
}
}
Get pickup locations
Request
GET https://api.myparcel.nl/pickup_locations?platform=myparcel&carrier=postnl&cc=nl&number=31&postal_code=2132JE&cutoff_time=16:00:00&dropoff_days=1;2;3;4;5;6&monday_delivery=1&dropoff_delay=0&deliverydays_window=2&exclude_delivery_type=1 HTTP/1.1
Accept: application/json;charset=utf-8;version=2.0
Response
HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
"data": {
"pickup_locations": [
{
"address": {
"cc": "NL",
"city": "Hoofddorp",
"street": "Polderplein",
"postal_code": "2132BA",
"number": "3"
},
"possibilities": [
{
"delivery_type_id": 4,
"delivery_type_name": "pickup",
"moment": {
"start": {
"date": "2020-02-13 16:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
}
],
"location": {
"location_name": "Primera Sanders",
"retail_network_id": "PNPNL-01",
"distance": "1696",
"latitude": "52.30329367",
"longitude": "4.69476214",
"location_code": "176227",
"phone_number": null,
"opening_hours": {
"monday": [
{
"start": {
"date": "2020-02-17 11:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-17 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"tuesday": [
{
"start": {
"date": "2020-02-18 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-18 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"wednesday": [
{
"start": {
"date": "2020-02-19 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-19 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"thursday": [
{
"start": {
"date": "2020-02-13 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-13 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"friday": [
{
"start": {
"date": "2020-02-14 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-14 21:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"saturday": [
{
"start": {
"date": "2020-02-15 09:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-15 18:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
],
"sunday": [
{
"start": {
"date": "2020-02-16 12:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
},
"end": {
"date": "2020-02-16 17:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Amsterdam"
}
}
]
}
}
}
]
}
}
Get delivery options for Belgium
Request
GET https://api.myparcel.nl/delivery_options?platform=belgie&carrier=bpost&cc=be&number=49&postal_code=1000 HTTP/1.1
Accept: application/json;charset=utf-8;version=2.0
Response
HTTP 200 OK{
"data": {
"delivery": [
{
"date": "2020-07-27",
"time": [
{
"start": "08:00:00",
"end": "17:00:00",
"price": {
"currency": "EUR",
"amount": 0
},
"price_comment": "standard",
"comment": "",
"name": 2
}
]
},
{
"date": "2020-07-28",
"time": [
{
"start": "08:00:00",
"end": "17:00:00",
"price": {
"currency": "EUR",
"amount": 0
},
"price_comment": "standard",
"comment": "",
"name": 2
}
]
},
{
"date": "2020-07-29",
"time": [
{
"start": "08:00:00",
"end": "17:00:00",
"price": {
"currency": "EUR",
"amount": 0
},
"price_comment": "standard",
"comment": "",
"name": 2
}
]
}
]
}
}