To show delivery options to customers, you can use our javascript code. Use our sandbox for an example and easier integration.

We do not currently have a test environment. You can create an account and print labels. These will only be invoiced if you actually send them. Note: Digital stamps/Digitale postzegel (package_type 4) will be charged immediately.

 Do you want to be kept informed of new functionalities or do you just need help? You can contact us via our Slack channel.

Sometimes we or an external party that we use have a malfunction. View the malfunctions at status.myparcel.nl. These malfunctions are also visible in our Slack channel.

1. Requests

1.A Base URL

BaseURL: https://api.myparcel.nl

1.B User-Agent

To give us insight that you use the API documentation, you should always send an User-Agent in your header. If you do not use a known CMS system, use the following header:
User-Agent: CustomApiCall/2

If you are using a known CMS system then you must use the name of the CMS system followed by a version number (User-Agent: <product> / <product-version>). Here's an example if your CMS system is Wordpress: User-Agent: Wordpress/4.8.1.

1.C HTTP methods

The API is REST(ful) and uses JSON as it's primary data exchange format. Communication with the API goes through HTTPS thereby insuring data confidentiality and integrity. Here is a list of all supported HTTP methods

1.C.1 GET

GET method is used for retrieving data and is idempotent. Data can be returned in JSON, PDF, CSV, XML or other formats.

1.C.2 POST

POST is used to create new objects or send data to MyParcel.

1.C.3 DELETE

DELETE is used to delete an existing object (piece of data). This method always returns HTTP/1.1 204 No Content unless otherwise specified.

1.D Rate limiting

Rate limits apply to many of our endpoints. You cannot receive data after you have exceeded the limit. The rate limiting will be reached when you make more than 100 requests per minute. The limit automatically resets after 1 minute.

Example: If you make 100 requests to the same endpoint within 15 seconds, you will be able to continue 45 seconds later.

2. Responses

As stated earlier data is usually sent back in JSON format. Exceptions to this rule are shipment label, invoice and CSV export. Shipment label and invoice are sent back in PDF format while CSV export is sent back in CSV format. Usually a response will have a response body. Exceptions are DELETE requests which will only contain a status code (204) indicating success. A failed request with a 4xx status code will always send back a response body with the error description. A failed request with a 5xx status code will probably mean you've hit a snag in our API. We try to monitor these kind of errors, but if you keep having trouble... Don't hesitate to reach out!

2.A HTTP statuses

HTTP status codes are used to indicate success or failure of a request. Here's a list of supported status codes. For a more comprehensive list of HTTP status codes visit Wikipedia or W3C.

Example of a 200 Status code in our API (you can try this in your browser, then you know our API is online)

Request:

GET https://api.myparcel.nl/
Request Headers (example):
GET / HTTP/1.1
Host: api.myparcel.nl
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
Accept-Encoding: gzip, deflate, sdch, br

{
  "title":"MyParcel API",
  "status":"OK"
}
Response Headers (example!)
HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 13:37:00 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

2.A.I 2xx

Used for successful requests. Successful requests may contain a response body e.g. object id of new object or none when modifying an existing object.

2.A.I 200 - OK

This status code is used for successful requests that have a response body.

2.A.I 202 - Accepted

This status code is used for requests that have been received successfully and will be processed at a later time. This is mostly used for processing shipments and addresses CSV.

2.A.I 204 - No Content

This status is used primarily for DELETE requests.

2.A.II 3xx

2.A.II 304 - Not Modified

This status is used by the server when the resource is the same as the one the client has.

2.A.III 4xx

Used for failed requests. Failed requests always contain a response body with the error description.

2.A.III 400 - Bad Request

When the request received is malformed.

2.A.III 401 - Unauthorized

No credentials have been sent with the request, or the wrong credentials are sent. Tip: check if the API key is properly attached in the header:

Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

2.A.III 402 - Payment Required

When payment is required. An Invoice object may be sent with this response.

2.A.III 403 - Forbidden

When the given credentials are not authorized to perform a certain action.

2.A.III 404 - Not Found

When a resource cannot be found.

2.A.III 405 - Method not allowed

When you used a method on an endpoint that is either not supported or not allowed for the given credentials.

2.A.III 406 - Not acceptable

When the client requests a given format for a resource that is not supported.

2.A.III 415 - Unsupported media type

When the client specifies a content-type in the request that is not supported.

2.A.III 422 - Unprocessable Entity

When the client sends a request object with invalid data. The error message will specify what's wrong with the request or the data sent to the API.

2.A.III 409 - Conflict

When the client request conflicts with the current state of the resource.

2.A.IV 5xx

Used for server-side errors. This happens when we (i.e. MyParcel.nl / the API) are having problems.

3. Character encoding

All content must be encoded in UTF-8 and include the charset=utf-8.

Example:

Content-Type: application/json;charset=utf-8

4. Data Types

Our API defines its own data types.

4.1 Contents

• array
• boolean
• carrier
• coordinates
• country_code
• currency
• date
• delivery_type
• description
• eori_number
• float
• integer
• isic_code
• label_position
• main
• month_digit
• package_contents
• package_type
• paper_size
• price
• printer_identifier
• shipment_status
• sort_order
• webhook_status
• string
• text
• time
• timestamp
• vat_number
• weekday_digit
• weekday_string

array

boolean

platform

carrier

coordinates

country_code

currency

date

delivery_type

description

eori_number

float

integer

isic_code

label_position

main

month_digit

package_contents

The package contents are only needed in case of shipping outside EU, this is mandatory info for customs form.

package_type

paper_size

price

printer_identifier

shipment_status

sort_order

webhook status

string

text

time

timestamp

vat_number

weekday_digit

weekday_string

5. Authentication

HTTP basic access authentication on top of SSL is used for authentication. Every request must include an Authorization header with base64 encoded API Key. Go to base64encode.org to convert your key to base64.

GET /somelink HTTP/1.1
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Our API uses API keys for access control. When a Merchant wants to connect an external system to our API he/she needs to create an API Key. This API Key will be assigned the Broker role. Currently the Merchant is not able to create or assign another Role to a API Key. When the Merchant wants to invalidate an API Key he/she just disables the API Key. An Intermediate system, such as the MyParcelNL backoffice or SendMyParcel backoffice, has its own API Key but cannot access user resources. For this it needs to request a Session Token so that it can perform actions on behalf of the user. The API Key and Session Token are send in the Authorization header.

5.1 Error codes

Our API defines a list of error codes besides the HTTP status codes. Error codes are divided in ranges to make it easier for developers to quickly diagnose and solve problems. Errors are returned as an Error object.

6. Shipments

We’ll start the shipment section with the different shipment option combinations available in MyParcel (6.a). 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

Contents

6.A.1 Package types

There are four different packages types available and determine the type of shipment. The value is send 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 only available on MyParcel.nl and Flespakket for NL shipment that fit into a mailbox. It does not support additional options.
Note: If you still make the request with additional options, bear in mind that you need to pay more than is necessary!

3. Letter

This package type is available on MyParcel.nl 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 sent this letter/package. Therefore, it does not support additional options.

4. Digital stamp

This package type is only available on MyParcel.nl 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 status 3 (enroute - handed to carrier).

6.A.2 Delivery types

There are five different delivery types and these specify how the package is delivered. The value is send with the ShipmentOptions.delivery_type field. Currently delivery types are only available for NL and BE shipments with package type 1. 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 options 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 options is only available on MyParcel.nl and 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 if the dimensions of the package are between 100 x 70 x 50 and 175 x 78 x 58 cm. 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. Only package type 1 (package) shipments can be insured. NL shipments can be insured for 500,- euros. EU shipments must be insured for 500,- euros. Global shipments must be insured for 200,- euros. The following shipment options are mandatory when insuring an NL shipment: only_recipient and signature.

age_check

Only available on MyParcel.nl and Flespakket. The Customer/Consumer must sign for the package and only receive it when he is at least 18 years.

6.A.4 Examples

Pickup

We 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
        },
        "pickup": {
          ...
        }
        ...
      }
    ]
  }
}

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. Pickup express is almost identical to pickup. Instead of delivery type 4 (Pickup), you need to specify delivery type 5 (Pickup express).

Evening

We 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 insured

We want to send a Rolex to a customer in Maastricht. This shipment needs to be insured up to 5000 euros for obvious reasons. 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 insured

We 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 type must be set to 1. All EU and Global shipments must be insured up to 500 (EU) / 200 (Global) euros so we set the insured amount to 50000 cents. EU and Global shipments do not have the only_recipient, signature and return 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 where sent.

For CSV requests HTTP/1.1 204 No Content with empty response body is returned. If a request fails then an HTTP/1.1 4xx < MESSAGE > is returned.

6.B.2 Reference

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

For these examples we are going to create shipments.

Create domestic PostNL 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": "FOO-222-BAR-42"
      },
      {
        "id": 68794,
        "reference_identifier": "FOO-223-BAR-43"
      }
    ]
  }
}

Create domestic bpost 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [
      {
        "recipient": {
          "cc": "BE",
          "postal_code": "2000",
          "city": "Antwerpen",
          "street": "Wormerplein",
          "number": "16",
          "box_number": "",
          "person": "test"
        },
        "options": {
          "package_type": 1,
          "signature": 0,
          "insurance": {
            "amount": 0,
            "currency": "EUR"
          }
        },
        "carrier": 2,
        "reference_identifier": "bpost shipment"
      }
    ]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 49566653,
        "reference_identifier": "bpost shipment"
      }
    ]
  }
}

Create domestic DPD 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 49566517,
        "reference_identifier": "Order 123456"
      }
    ]
  }
}

Create domestic Instabox 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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": "My custom description",
          "same_day_delivery": 1
        },
        "carrier": 5,
        "drop_off_point": {
          "location_code": "e9149b66-7bee-439b-bab0-7a5d92ddc519",
          "location_name": "Instabox",
          "cc": "NL",
          "city": "Hoofddorp",
          "postal_code": "2132WV",
          "street": "Diamantlaan",
          "number": "77"
        }
      }
    ]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 49566518,
        "reference_identifier": "FOO-222-BAR-42"
      }
    ]
  }
}

Create domestic PostNL multi collo shipments

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": "FOO-222-BAR-42"
      }
    ]
  }
}

Create International shipment

• PostNL and Bpost shipments are available worldwide.
• DPD shipments are available in the EU.
• Instabox is only available in NL.

Request

POST https://api.myparcel.nl/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 3485394579,
        "reference_identifier": null
      }
    ]
  }
}

Create digital stamp 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK
Content-Type:application/json;charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 39234953,
        "reference_identifier": null
      }
    ]
  }
}

Create PostNL 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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier":null
      }
    ]
  }
}

Create bpost shipment with BE pickup location

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 49571535,
        "reference_identifier": "order-012356"
      }
    ]
  }
}

Create DPD shipment with BE pickup location

Request

POST https://api.sendmyparcel.be/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json; charset=utf-8
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 49571535,
        "reference_identifier": "DPD pickup"
      }
    ]
  }
}

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": "FOO-222-BAR-42"
      }
    ]
  }
}

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": null
      }
    ]
  }
}

Create related return shipment

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": null
      }
    ]
  }
}

Create unrelated return shipment

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 12345,
        "reference_identifier": null
      }
    ]
  }
}

6.C Delete Shipment

Note: The ‘Delete shipment’ section is not used often. This can only be done for shipments for which a label has not yet been created (status 1). 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 status 'pending - concept' can be deleted. This method returns HTTP/1.1 204 if successful. If the shipment doesn’t exist a 422 "cannot delete shipment" is returned.

6.C.2 Reference

6.C.3 Parameters

id
Data type: integer
The id of the shipment to delete. You can specify multiple shipments by semi-colon separating them.

6.C.4 Example

Remove a shipment with id 1234.

Request

DELETE https://api.myparcel.nl/shipments/1234 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 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/1.1 404 Not Found is returned.

6.D.2 Reference

6.D.3 Example

Proceed with actual request
Request

POST https://api.myparcel.nl/return_shipments
User-Agent: CustomApiCall/2
HTTP/1.1 Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw== 

Response

HTTP/1.1 200 OK  Content-Type:application/json
{
  "data": {
    "download_url": {
     "link": "https://myparcel.me/returns/902223ede2f50288ecfbbd21a8c8fd7e"
     }
  }
}

PHP Examples README

If you are a PHP Developer we've included a few examples on how to call our API from your (custom) back-end. For cURL / Non-cURL PHP examples: click here.

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 semi-colon. 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

6.E.3 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon 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 trough 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 semi-colon 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 Example

JSON

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/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "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 Postpayment payment methods can fetch multiple labels in one call. For accounts with Prepayment payment method a HTTP/1.1 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/1.1 4xx < MESSAGE > 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 a HTTP status of 404 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.

6.F.2 Reference

6.F.3 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon 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 semi-colon 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 Example

Get Shipment label

Request

GET https://api.myparcel.nl/shipment_labels/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 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: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Accept: application/json;charset=utf-8

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "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: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Accept: application/vnd.shipment_label_link+json; charset=utf8

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "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: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 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 and trace information for a shipment. Upon success HTTP/1.1 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

6.G.4 Parameters

id
Data type: integer
This is the shipment id. You can specify multiple shipment ids by semi-colon 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:

6.G.5 Example

Request

GET https://api.myparcel.nl/tracktraces/1212321?extra_info=delivery_moment HTTP/1.1
User-Agent: CustomApiCall/2
Accept-Language: en_GB
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "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 type 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 functionaltity.

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 and can only be used for shipments to NL en BE.

"secondary_shipments": [
   {
      "reference_identifier": "SECONDARY-SHIPMENT"
   }
]

6.H.3 Update

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.
For adding shipment 34567 to an existing multi collo shipment, the secondary_shipments property should look like this:

"secondary_shipments": [
    {"id": 12345},
    {"id": 34567}
]

2. Update a single existing shipment with a reference to a multi collo shipment via the 'multi_collo_main_shipment_id'.
For adding shipment 34567 to an existing multi collo shipment 12345, the multi_collo_main_shipment_id should look like this:

    "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.
For adding a new shipment to an existing multi collo shipment, the secondary_shipments property should look like this:

"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

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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

HTTP/1.1 204 No Content

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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

HTTP/1.1 204 No Content

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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

HTTP/1.1 204 No Content

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "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

HTTP/1.1 204 No Content

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:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 204 No Content

7. Shipment related Object Definitions

7.A Shipment Object Definition

7.A.1 Overview

You can create shipments with this object. You can specify multiple address ids in the recipients column to create multiple shipments. If you want to create a return shipment you have to use the ReturnShipment object.

barcode
Data type: string
Required: n/a.
Shipment barcode.

id
Data type: integer
Required: n/a.
Shipment id.

parent_id
Data type: integer
Required: no
The parent shipment. This is used for related return shipment.

account_id
Data type: integer
Required: n/a.
The account id to which this shipment belongs.

shop_id
Data type: integer
Required: n/a.
The shop id to which this shipment belongs.

reference_identifier
Data type: string
Required: No.
Arbitrary reference indentifier to identify this shipment.

shipment_type
Data type: integer
Required: n/a.

recipient
Data type: Address
Required: Yes for application/vnd.shipment+json
The recipient address. Use this field when you want to create a shipment for one address.

recipients
Data type: array of Address objects
Required: Yes for application/vnd.shipment_recipients+json Use this field when you want to create multiple shipments for multiple addresses.

sender
Data type: Address
Required: n/a.
The sender of the package. This field is never set.

status
Data type: shipment_status
Required: no
This is the internal shipment status. What we do is filter and translate the shipment status provided by the carrier in order to reduce the number of statusses.

options
Data type: ShipmentOptions
Required: Yes.
The shipment options.

pickup
Data type: PickupLocation
Required: Yes for options.delivery_type 4.
The pickup location for this shipment.

customs_declaration
Data type: CustomsDeclaration
Required: yes for non-EU shipments.
The customs declaration information.

physical_properties
Data type: PhysicalProperties
Required: yes for non-EU and digital stamp shipment types.
Shipment physical properties such as dimension, weight etc. This object may be updated when fetching shipment status update from the carrier.

carrier
Data type: carrier
Required: yes.
The carrier that will deliver the package.

general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object.

price
Data type: price
Required: n/a.
The shipment price.

secondary_shipments Data type: an array of shipment
Required: no
You can specify secondary shipments for the shipment with this object. This property is used to create a multi collo shipment: multiple packages to be delivered to the same address at the same time. Secondary shipment can be passed as empty json objects as all required data will be copied from the main shipment. When data is passed with the secondary shipment this data will be used in favor of the main shipment data.

multi_collo_main_shipment_id Data type: integer
In case of a multi collo shipment this field contains the id of the main shipment.

created
Data type: timestamp
Required: n/a.
Date of creation.

modified
Data type: timestamp
Required: n/a.
Date of modification.

7.A.2 Example

POST example national shipment

{
  "reference_identifier": "FOO-333-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": 10000,
      "currency": "EUR"
    },
    "large_format": 0
  },
  "carrier": 1
}

POST example national shipment b

{
  "reference_identifier": "FOO-333-BAR-42",
  "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": 1,
    "signature": 1,
    "return": 1
  },
  "general_settings": {
    "save_recipient_address": 1,
    "disable_auto_detect_pickup": 1,
    "delivery_notification": 1,
    "delivery_notification_email": ["testing@myparcel.nl"],
    "printer_identifier": "printer_id_12"
  },
  "carrier": 1
}

POST example national multi collo shipment

{
  "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": [
    {},
    {}
  ],
  "carrier": 1
}

POST example international shipment

{
  "reference_identifier": "さいた-ᚱ	ᚾᛟ/42",
  "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
}

POST example pickup location

{
  "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
      }
    ]
  }
}

GET example national shipment A

{
  "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": 1,
  "status": 1,
  "price": {
    "amount": 535,
    "currency": "EUR"
  },
  "barcode": "3SMYPA77773333",
  "created": "2017-01-31 08:00:00",
  "modified": "2017-01-31 09:00:00"
}

GET example national shipment B

{
  "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": 1,
    "signature": 1,
    "return": 1
  },
  "sender": {
    "cc": "NL",
    "region": "Zuid-Holland",
    "city": "Hoofddorp",
    "street": "Antareslaan",
    "number": "31",
    "postal_code": "2132JE",
    "person": "Mr. Parcel",
    "phone": "0233030315",
    "email": "testing@myparcel.nl"
  },
  "carrier": 1,
  "status": 2,
  "price": {
    "amount": 535,
    "currency": "EUR"
  },
  "barcode": "563716278632716817283",
  "created": "2017-01-31 08:00:00",
  "modified": "2017-01-31 09:00:00"
}

GET example national multi collo shipment

{
  "id": 12345,
  "account_id": 1,
  "shop_id": 1,
  "shipment_type": 3,
  "recipient": {
    "cc": "NL",
    "region": "Zuid-Holland",
    "city": "Hoofddorp",
    "street": "Antareslaan",
    "number": "31",
    "postal_code": "2132JE",
    "person": "Mr. Parcel",
    "phone": "0233030315",
    "email": "testing@myparcel.nl"
  },
  "sender": {
    "cc": "NL",
    "postal_code": "2132JE",
    "city": "Hoofddorp",
    "street": "Antareslaan",
    "number": "31",
    "person": "Mrs. Parcel",
    "company": "MyParcel",
    "email": "testing@myparcel.nl",
    "phone": "12345678"
  },
  "status": 1,
  "options": {
    "package_type": 1,
    "label_description": "My custom description"
  },
  "reference_identifier": "FOO-222-BAR-42",
  "transaction_status": "unpaid",
  "barcode": null,
  "price": {
    "amount": 595,
    "currency": "EUR"
  },
  "region": "NL",
  "payment_status": "unpaid",
  "carrier_id": 1,
  "secondary_shipments": [
    {
      "id": 12346,
      "account_id": 1,
      "shop_id": 1,
      "shipment_type": 3,
      "recipient": {
        "cc": "NL",
        "region": "Zuid-Holland",
        "city": "Hoofddorp",
        "street": "Antareslaan",
        "number": "31",
        "postal_code": "2132JE",
        "person": "Mr. Parcel"
      },
      "sender": {
        "cc": "NL",
        "postal_code": "",
        "city": "Hoofddorp",
        "street": "Antareslaan",
        "number": "2132JE",
        "person": "Frisby Test",
        "company": "Test1",
        "email": "test1@test.nl",
        "phone": "12345678"
      },
      "status": 1,
      "options": {
        "package_type": 1,
        "label_description": "My custom description"
      },
      "reference_identifier": null,
      "transaction_status": "unpaid",
      "price": {
        "amount": 595,
        "currency": "EUR"
      },
      "barcode": "",
      "region": "NL",
      "payment_status": "unpaid",
      "carrier_id": 1,
      "multi_collo_main_shipment_id": 12345
    }
  ],
  "multi_collo_main_shipment_id": 12345
}

7.B Address Object Definition

7.B.1 Overview

This is the adress object

cc
Data type: country_code
Required: yes.
The address country code.

region
Data type: string
Required: no.
The region, department, state or province of the address.

postal_code
Data type: string
Required: Yes for NL and EU destinations except for IE.
The address postal code.

city
Data type: string
Required: yes.
The address city.

street
Data type: string
Required: yes.
The address street name. When shipping to an international destination, you may include street number in this field.

street_additional_info
Data type: string
Required: no.
Additional information for the street that should not be included in the street field.

number
Data type: string
Required: Yes for domestic shipments in NL and BE.
Street number.

number_suffix
Data type: string
Required: no
Street number suffix.

person
Data type: string
Required: yes.
The person at this address. Up to 40 characters long.

company
Data type: string
Required: no.
Company name.

email
Data type: string
Required: no
The address email.

phone
Data type: string
Required: no.
The address phone.

7.B.2 Example

Example a

{
  "cc": "NL",
  "region": "Zuid-Holland",
  "city": "Hoofddorp",
  "street": "Antareslaan",
  "number": "31",
  "postal_code": "2132JE",
  "person": "Mr. Parcel",
  "phone": "0233030315",
  "email": "parcel@myparcel.nl"
}

Example b

{
  "cc": "NL",
  "region": "Zuid-Holland",
  "city": "Hoofddorp",
  "street": "Antareslaan",
  "number": "31",
  "postal_code": "2132JE",
  "person": "Mrs. Parcel",
  "phone": "0233030315",
  "email": "parcel@myparcel.nl"
}

Example c

{
  "cc": "FR",
  "region": "Seine",
  "city": "Paris",
  "street": "rue du Grenier-Saint-Lazare 22",
  "person": "Claus Stuter",
  "company": "Renault",
  "email": "claus@paris.nl",
  "postal_code": "75008",
  "phone": "0033142723122"
}

Example d

{
  "cc": "NL",
  "region": "Zuid-Holland",
  "city": "Zoetermeer",
  "street": "Louiarmstrongrode",
  "number": "18",
  "postal_code": "2717NH",
  "person": "Pato otap",
  "phone": "0790880808",
  "email": "pato@otap.nl"
}

Example e

{
  "cc": "NL",
  "region": "Zuid-Holland",
  "city": "Hoofddorp",
  "street": "Antareslaan",
  "number": "31",
  "person": "Jan Peter",
  "company": "MyParcel B.V.",
  "email": "janpeter@bedrijven.nl",
  "phone": "0233030315"
}

Example i

{
  "cc": "JP",
  "region": "埼玉県",
  "city": "さいたま市",
  "street": "埼玉県さいたま市浦和区 常盤9－21－21",
  "person": "Tanaka san",
  "company": "さいたま国際キリスト教会",
  "email": "saitamakyokai@gmail.com",
  "phone": "0081-48-825-6637"
}

Example CSV a

{
  "cc",
  "city",
  "street",
  "number",
  "person",
  "company",
  "email",
  "phone",
  "groups""124",
  "nl",
  "Hoofddorp",
  "Antareslaan",
  "31",
  "Claus Stuter",
  "MyParcel B.V.",
  "claus@stuter.nl",
  "0233030315",
}

Example CSV b

{
  "cc",
  "postalcode",
  "city",
  "street",
  "number",
  "person",
  "company",
  "email",
  "phone""nl",
  "2132JE",
  "Hoofddorp",
  "Antareslaan",
  "31",
  "Mrs. Parcel",
  "MyParcel",
  "parcel@myparcel.nl",
  "0233030315"
}

Example CSV c

{
  "nl",
  "2132JE",
  "Hoofddorp",
  "Antareslaan",
  "31",
  "Arie Test",
  "MyParcel",
  "arie@myparcel.nl",
  "0233030315"
}

7.C ShipmentOptions Object Definition

7.C.1 Overview

This object contains the shipment options and is embedded in Shipment.options and ReturnShipment.options.

package_type
Data type: package_type
Required: yes
The package type. For international shipment only package type 1 (package) is allowed.

delivery_type
Data type: delivery_type
Required: Yes if delivery_date has been specified.
The delivery type for the package.

delivery_date
Data type: timestamp
Required: Yes if delivery type has been specified.
The delivery date time for this shipment.

only_recipient
Data type: boolean
Required: No.
Deliver the package to the recipient only.

signature
Data type: boolean
Required: No.
Package must be signed for.

return
Data type: boolean
Required: No.
Return the package if the recipient is not home.

insurance
Data type: price
Required: No.
Insurance price for the package.

large_format
Data type: boolean
Required: No.
Large format package.

cooled_delivery
Data type: boolean
Required: No.
Cooled_delivery is only valid for cc=NL and with shipment_type 1 or 3.

label_description
Data type: string
Required: No.
This description will appear on the shipment label. Note: This will be overridden for return shipment by the following: Retour – 3SMYPAMYPAXXXXXX

age_check
Data type: boolean
Required: No.
The recipient must sign for the package and must be at least 18 years old.

7.C.2 Example

Example a

{
  "package_type": 1,
  "only_recipient": 1,
  "signature": 1,
  "return": 1,
  "insurance": {
    "amount": 10000,
    "currency": "EUR"
  },
  "large_format": 0,
  "label_description": "My custom description",
  "age_check":1
}

Example b

{
  "package_type": 1,
  "only_recipient": 0,
  "signature": 1,
  "return": 0,
  "insurance": {
    "amount": 10000,
    "currency": "EUR"
  },
  "label_description": "My custom description"
}

Example c

{
  "package_type": 1,
  "only_recipient": 1,
  "signature": 1,
  "return": 1,
  "insurance": {
    "amount": 50000,
    "currency": "EUR"
  },
  "large_format": 0
}

Example d

{
  "package_type": 1,
  "only_recipient": 1,
  "signature": 1,
  "return": 1
}

Example return shipment options

{
  "package_type": 1,
  "only_recipient": 0,
  "signature": 1,
  "return": 0,
  "insurance": {
    "amount": 10000,
    "currency": "EUR"
  }
}

Example international shipment

{
  "package_type": 1
}

Example pickup

{
  "package_type": 1,
  "delivery_type": 4,
  "delivery_date": "2017-01-12 16:30:00",
  "only_recipient": 0,
  "signature": 1,
  "return": 0
}
                

7.D ShipmentGeneralSettings Object Definition

7.D.1 Overview

You can specify shipment general settings with this object. It is embedded in the Shipment.general_settings column.

save_recipient_address
Data type: boolean
Required: No
When this setting is true the recipient address will be saved in the address book. Only for valid for POST request.

delivery_notification
Data type: boolean
Required: No.
When this setting is true the Merchant will receive an email notification when the package has been delivered.

disable_auto_detect_pickup
Data type: boolean
Required: No.
When this setting is true MyParcel do not auto detect pickup addresses.

delivery_notification_email
Data type: array of string
Required: No.
This email addresses that will receive a delivery notification.

printer_identifier
Data type: printer_identifier of string
Required: No.
In this field you can enter your printer identifier. This field is also sent with the webhook shipment_label_created. You are responsible for controlling your own printer based on a printer identifier.

7.D.2 Example

Example

{
  "save_recipient_address": 1,
  "disable_auto_detect_pickup": 1,
  "delivery_notification": 1,
  "delivery_notification_email": ["testing@myparcel.nl"]
  "printer_identifier": "printer_id_12"
}

7.E CustomsDeclaration Object Definition

7.E.1 Overview

This object is embedded in the Shipment object for global shipments and is mandatory for non-EU shipments.

contents
Data type: package_contents
Required: Yes.
The type of contents in the package.

invoice
Data type: string
Required: Yes for commercial goods, commercial samples and return shipment package contents.
The invoice number for the commercial goods or samples of package contents.

weight
Data type: integer
Required: Yes.
The total weight for all items in whole grams.

items
Data type: array of CustomsItem objects
Required: Yes.
An array containing CustomsItem objects with description for each item in the package.

7.E.2 Example

POST example a

{
  "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 NBG Product",
      "amount": 5,
      "weight": 10,
      "item_value": {
        "amount": 1000,
        "currency": "EUR"
      },
      "classification": "0181",
      "country": "BE"
    }
  ]
}
  

POST example a

{
  "contents": 3,
  "invoice": "4567789004",
  "weight": 30,
  "items": [
    {
      "description": "NIV Product Audio CD",
      "amount": 3,
      "weight": 10,
      "item_value": {
        "amount": 10000,
        "currency": "EUR"
      },
      "classification": "0181",
      "country": "US"
    },
    {
      "description": "Sample JP Product",
      "amount": 10,
      "weight": 20,
      "item_value": {
        "amount": 800000,
        "currency": "YEN"
      },
      "classification": "0181",
      "country": "JP"
    }
  ]
}

7.F CustomsItem Object Definition

7.F.1 Overview

This object contains a declaration for an item in the CustomsDeclaration object.

description
Data type: string
Required: Yes.
The description of the item.

amount
Data type: integer
Required: Yes.
The amount of this item in the package. The minimum amount is 1.

weight
Data type: integer
Required: Yes.
The total weight for these items in whole grams. Between 0 and 20000 grams.

item_value
Data type: price
Required: Yes.
Item value

classification
Data type: isic_code
Required: Yes.
The International Standard Industry Classification code for this item.

country
Data type: country_code
Required: Yes.
The country of origin for this item.

7.F.2 Example

POST example a

{
  "description": "Sample NIV Product",
  "amount": 10,
  "weight": 20,
  "item_value": {
    "amount": 7000,
    "currency": "EUR"
  },
  "classification": "0181",
  "country": "NL"
}

POST example b

{
  "description": "Sample NBG Product",
  "amount": 5,
  "weight": 10,
  "item_value": {
    "amount": 1000,
    "currency": "EUR"
  },
  "classification": "0181",
  "country": "BE"
}

POST example c

{
  "description": "NIV Product Audio CD",
  "amount": 3,
  "weight": 10,
  "item_value": {
    "amount": 10000,
    "currency": "EUR"
  },
  "classification": "0181",
  "country": "US"
}

POST example d

{
  "description": "Sample JP Product",
  "amount": 10,
  "weight": 20,
  "item_value": {
    "amount": 800000,
    "currency": "YEN"
  },
  "classification": "0181",
  "country": "JP"
}

7.G ShipmentIds Object Definition

Overview

This object contains an array of ShipmentId objects.

ids
Data type: array of ShipmentId objects.
Required: n/a.
array of ShipmentId objects.

7.H ShipmentId Object Definition

Overview

id
Data type: integer
Required: n/a.
Shipment.id

7.I ReturnShipment Object Definition

7.I.1 Overview

You can create a return shipment with this object.

shop_id
Data type: integer
Required: no.
The shop id to which this shipment belongs.

parent
Data type: integer
Required: Yes.
The parent shipment that was initially sent to the consumer.

carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.

email
Data type: string
Required: no.
The email address to send the return shipment email to.

name
Data type: string
Required: Yes.
The name to include in the email.

options
Data type: ShipmentOptions
Required: no.
The shipment options. If this is not provided then the default shop return shipment options are used.

general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object. For return shipments only the printer_identifier property is accepted.

7.I.2 Example

POST example

{
  "parent": 123456,
  "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"
    }
  },
  "general_settings": {
    "printer_identifier": "printer_id_12"
  }
}

7.J UnrelatedReturnShipment Object Definition

7.J.1 Overview

You can create an unrelated return shipment with this object.

shop_id
Data type: integer
Required: No.
The shop id to which this shipment belongs.

carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.

email
Data type: string
Required: Yes.
The email to send the return shipment email to.

name
Data type: string
Required: Yes.
The name to include in the email.

sender
Data type: Address
Required: No.
The sender where the package comes from.

options
Data type: ShipmentOptions
Required: No.
The shipment options. If this is not provided then the default shop returnshipment options are used.

general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object. For return shipments only the printer_identifier property is accepted.

7.J.2 Example

POST example

{
  "carrier": 1,
  "email": "testing@myparcel.nl",
  "name": "Mr. Parcel",
  "sender": {
    "cc": "NL",
    "city": "Hoofddorp",
    "street": "Antareslaan",
    "number": "31",
    "postal_code": "2132 JE",
    "email": "parcel@myparcel.nl",
    "person": "Mr. Parcel",
    "street_additional_info": "",
    "number_suffix": "",
    "company": "MyParcel B.V.",
    "phone": "0118418888"
  },
  "options": {
    "package_type": 1,
    "only_recipient": 0,
    "signature": 1,
    "return": 0,
    "insurance": {
      "amount": 10000,
      "currency": "EUR"
    }
  },
  "general_settings": {
    "printer_identifier": "printer_id_12"
  }
}

7.K DownloadUrl Object Definition

7.K.1 Overview

This is the download url object.

link
Data type: string
Required: Yes.
The url to generate an unrelated return shipment

7.K.2 Example

POST example

{
  "link": "https://backoffice.myparcel.nl/retour/8005ebb27d55425c5eaf2dff2fa41147"
}

7.L TrackTrace Object Definition

7.L.1 Overview

This is the tracktrace object.

shipment_id
Data type: integer

code
Data type: string

description
Data type: description

time
Data type: time

link_consumer_portal
Data type: string
URL for custom track and trace page. More information about this service is found here. If the consumer portal is turned off, the carrier tracking page is used. You can also pass a language parameter: ?lang=en_GB.

link_tracktrace
Data type: string
Carrier tracking page

recipient
Data type: Address

sender
Data type: Address

options
Data type: ShipmentOptions

pickup
Data type: PickupLocation

delayed
Data type: boolean
Indicates whether the current event code means the shipment has been delayed.

location
Data type: TrackTraceLocation

status
Data type: TrackTraceStatus

history
Data type: TrackTraceHistory

delivery_moment_type
Data type: string
Depending on the status of the shipment `expected` or `estimated`

delivery_moment
Data type: DeliveryMoment

7.L.2 Example

GET example

{
  "data": {
    "tracktraces": [
      {
        "shipment_id": 43393092,
        "code": "I01",
        "description": "Zending bezorgd",
        "time": "2019-02-16 15:09:53",
        "link_consumer_portal": "https://yoursubomain.myparcel.me/track-trace/3SMYPA126329191/2182KD/NL",
        "link_tracktrace": "https://postnl.nl/tracktrace/?B=3SMYPA126329190&P=2182KD&D=NL&T=C&L=NL",
        "recipient": {
          "cc": "NL",
          "postal_code": "2231je",
          "city": "Hillegom",
          "street": "Brouwerlaan",
          "number": "12",
          "number_suffix": "",
          "person": "Elma Koen"
        },
        "sender": {
          "cc": "NL",
          "postal_code": "4337WV",
          "city": "Middelburg",
          "street": "Podium",
          "number": "3",
          "person": "Tamara Bosman",
          "company": "Skin Jewelry",
          "email": "tamluca@zeelandnet.nl",
          "phone": "0118418888"
        },
        "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": [],
        "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"
          }
        }
      }
    ]
  }
}

7.M TrackTraceHistory Object Definition

7.M.1 Overview

This is the tracktrace history object.

code
Data type: string
Required: n/a.

description
Data type: string
Required: n/a.

time
Data type: time
Required: n/a.

delayed
Data type: boolean
Indicates whether the current event code means the shipment has been delayed.

location
Data type: TrackTraceLocation

7.M.2 Example

GET example

{
  "code": "C3",
  "description": "The package is at the sorting center",
  "time": "2015-01-02 05: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
  }
}

7.N PhysicalProperties Object Definition

7.N.1 Overview

This is the physical properties object, which is required for non-EU and digital stamp shipments. Note: Weight is the only available property for digital stamps (package_type 4)

carrier_height
Data type: integer
Required: n/a.

carrier_width
Data type: integer
Required: n/a.

carrier_weight
Data type: integer
Required: n/a.

carrier_length
Data type: integer
Required: n/a.

carrier_volume
Data type: integer
Required: n/a.

height
Data type: integer
Required: n/a.

width
Data type: integer
Required: n/a.

length
Data type: integer
Required: n/a.

volume
Data type: integer
Required: n/a.

weight
Data type: integer
Required: n/a.

7.N.2 Example

POST example

{
  "weight": 30
}

7.O PickupLocation Object Definition

7.O.1 Overview

This is the pickup location object.

city
Data type: string
Required: n/a.

location_name
Data type: string
Required: n/a.

number
Data type: string
Required: n/a.

postal_code
Data type: string
Required: n/a.

street
Data type: string
Required: n/a.

location_code
Data type: string
Required: n/a.

retail_network_id
Data type: string
Required: n/a.

7.O.2 Example

POST example for NL pickup location

{
  "postal_code": "2132BH",
  "street": "Burgemeester van Stamplein",
  "city": "Hoofddorp",
  "number": "270",
  "location_name": "Albert Heijn"
}

POST example for BE pickup location

{
  "city": "ANTWERPEN",
  "street": "HOOGSTRAAT",
  "postal_code": "2000",
  "number": "75",
  "location_code": "BE0Q07",
  "retail_network_id": "LD-01",
  "location_name": "K&J TRADING"
}

7.P PaymentInstructions Object Definition

7.P.1 Overview

This is the payment instruction object.

id
Data type: string
Required: n/a.

hash
Data type: string
Required: n/a.

invoices
Data type: Invoice
Required: n/a.

type
Data type: integer
Required: n/a.

notification_hash
Data type: string
Required: n/a.

original_notification_hash
Data type: string
Required: n/a.

payment_url
Data type: string
Required: n/a.

paid
Data type: boolean
Required: n/a.

price
Data type: price
Required: n/a.

7.P.2 Example

Example

{
  "id": "93c8533d3744eaf4a24a119f068019dcfbf97551",
  "hash": "93c8533d3744eaf4a24a119f068019dcfbf97551",
  "invoices": {
    "id": 1334092,
    "number": "111704089216",
    "status": 102
  },
  "type": 1,
  "notification_hash": "27eecee49d917d9ea2700ef5ccb59d28849a8bf3",
  "original_notification_hash": "27eecee49d917d9ea2700ef5ccb59d28849a8bf3",
  "payment_url": "https://pay.multisafepay.com/pay/?transaction=25cOdyun01THR2ZpozaR5KfNPPrLCzBSFYq&lang=nl_NL",
  "paid": 0,
  "price": {
    "amount": 911,
    "currency": "EUR"
  }
}
 

7.Q Invoice Object Definition

7.Q.1 Overview

This is the invoice object.

id
Data type: integer
Required: n/a.

number
Data type: string
Required: n/a.

status
Data type: integer
Required: n/a.

7.Q.2 Example

Example

{
  "id": 1334092,
  "number": "111704089216",
  "status": 102
}
 

7.R ShipmentLabelDownloadLink Object Definition

7.R.1 Overview

This is the shipment label download link object.

url
Data type: string
Required: n/a.

7.R.2 Example

Example

{
  "url": "https://api.myparcel.nl/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
}

7.S TrackTraceStatus Object Definition

7.S.1 Overview

An object with a current status, main and final.

current
Data type: shipment_status

main
Data type: main

final
Data type: boolean
When `true` no new statuses are expected

7.S.2 Example

Example

"status": {
  "current": 7,
  "main": "delivered",
  "final": true
}

7.T DeliveryMoment Object Definition

7.T.1 Overview

An object with a start and end DateTime.

start
Data type: DateTimeStartEnd

end
Data type: DateTimeStartEnd

7.T.2 Example

Example

"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"
  }
}

7.U DateTimeStartEnd Object Definition

7.U.1 Overview

An object with a date, timezone_type and timezone.

date
Data type: timestamp

timezone_type
Data type: integer

timezone
Data type: string

7.U.2 Example

Example

{
  "date": "2019-02-19 17:15:00.000000",
  "timezone_type": 3,
  "timezone": "Europe/Amsterdam"
}

7.V TrackTraceLocation Object Definition

7.V.1 Overview

An object with a location where the track and trace event took place. This data is only available when it has been provided by the carrier of the shipment.

name
Data type: string
nullable: false

cc
Data type: string
nullable: true

city
Data type: string
nullable: true

postal_code
Data type: string
nullable: true

street
Data type: string
nullable: true

number
Data type: string
nullable: true

number_suffix
Data type: string
nullable: true

longitude
Data type: float
nullable: true

latitude
Data type: float
nullable: true

7.V.2 Example

Example

{
  "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
}

8. Delivery options

8.A Get delivery options

This endpoint has a rate limit. For more information, see rate limiting.

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 (15h30) and Monday before the default cutoff_time (15h30) 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

{
  "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 cut-off time before which a consumer order will still be picked, packed and dispatched on the same/first set dropoff day, taking into account the dropoff-delay. Default time is 15h30. For example, if cutoff time is 15h30, Monday is a delivery day and there's no delivery delay; all orders placed Monday before 15h30 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
Required: no
This options allows the Merchant to set the number of days it takes her to pick, pack and hand in her parcels at PostNL when ordered before the cutoff time. By default this is 0 and max is 14.

deliverydays_window
Data type: integer
Required: no
This options allows the Merchant to set the number of days into the future for which she wants to show her consumers delivery options. For example, if set to 3 in her 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 cut-off time and she goes 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 semi-colon separating them. The standard delivery type 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 Example

Get delivery options for 2132WT, 66 for PostNL
Request

GET https://api.myparcel.nl/delivery_options?platform=myparcel&carrier=postnl&cc=nl&number=66&postal_code=2132WT HTTP/1.1
User-Agent: CustomApiCall/2
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": "",
            "type": 1
          },
          {
            "start": "11:30:00",
            "end": "13:30:00",
            "price": {
              "currency": "EUR",
              "amount": 0
            },
            "price_comment": "standard",
            "comment": "",
            "type": 2
          }
        ]
      },
      {
        "date": "2017-02-02",
        "time": [
          {
            "start": "08:00:00",
            "end": "12:00:00",
            "price": {
              "currency": "EUR",
              "amount": 1000
            },
            "price_comment": "morning",
            "comment": "",
            "type": 1
          },
          {
            "start": "11:00:00",
            "end": "13:00:00",
            "price": {
              "currency": "EUR",
              "amount": 0
            },
            "price_comment": "standard",
            "comment": "",
            "type": 2
          }
        ]
      }
    ],
    "pickup": [
      {
        "date": "2017-02-01",
        "time": [
          {
            "start": "16:00:00",
            "type": 4,
            "price": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          {
            "start": "08:30:00",
            "type": 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",
            "type": 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",
            "type": 4,
            "price": {
              "amount": 0,
              "currency": "EUR"
            }
          }
        ]
      }
    ]
  }
}

Get pickup options for 2132WT, 66 for PostNL
Request

GET https://api.myparcel.nl/pickup_locations?carrierName=postnl&platform=myparcel&carrier=postnl&cc=nl&number=66&postal_code=2132WT HTTP/1.1
User-Agent: CustomApiCall/2
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 2132WT, 66 for PostNL cutoff time 16h00, dropoff days Mon - Sat, dropoff delay is zero, delivery window is 2 days and morning is excluded as delivery type

Request

GET https://api.myparcel.nl/delivery_options?platform=myparcel&carrier=postnl&cc=nl&number=66&postal_code=2132WT&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

User-Agent: CustomApiCall/2
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": [
          {
            "type": "standard",
            "shipment_options": [
              {
                "name": "age_check",
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true,
                    false
                  ]
                }
              },
              {
                "name": "large_format",
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true,
                    false
                  ]
                }
              },
              {
                "name": "only_recipient",
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true,
                    false
                  ]
                }
              },
              {
                "name": "signature",
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true,
                    false
                  ]
                }
              },
              {
                "name": "return",
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true,
                    false
                  ]
                }
              }
            ],
            "collect_date": null,
            "delivery_time_frames": [
              {
                "type": "start",
                "date_time": {
                  "date": "2020-02-13 09:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "type": "end",
                "date_time": {
                  "date": "2020-02-13 12:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Get pickup options for 2132WT, 66 for PostNL cutoff time 16h00, dropoff days Mon - Sat, dropoff delay is zero, delivery window is 2 days and morning is excluded as delivery type

Request

GET https://api.myparcel.nl/pickup_locations?platform=myparcel&carrier=postnl&cc=nl&number=66&postal_code=2132WT&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
User-Agent: CustomApiCall/2
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
User-Agent: CustomApiCall/2
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": "2020-07-27",
        "time": [
          {
            "start": "08:00:00",
            "end": "17:00:00",
            "price": {
              "currency": "EUR",
              "amount": 0
            },
            "price_comment": "standard",
            "comment": "",
            "type": 2
          }
        ]
      },
      {
        "date": "2020-07-28",
        "time": [
          {
            "start": "08:00:00",
            "end": "17:00:00",
            "price": {
              "currency": "EUR",
              "amount": 0
            },
            "price_comment": "standard",
            "comment": "",
            "type": 2
          }
        ]
      },
      {
        "date": "2020-07-29",
        "time": [
          {
            "start": "08:00:00",
            "end": "17:00:00",
            "price": {
              "currency": "EUR",
              "amount": 0
            },
            "price_comment": "standard",
            "comment": "",
            "type": 2
          }
        ]
      }
    ]
  }
}

Get pickup options for Belgium

Request

GET https://api.myparcel.nl/pickup_locations?platform=belgie&carrier=bpost&cc=be&number=49&postal_code=1000  HTTP/1.1
User-Agent: CustomApiCall/2
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": "BE",
          "city": "BRUSSEL",
          "street": "ANSPACHLAAN",
          "postal_code": "1000",
          "number": "1",
          "number_suffix": null
        },
        "possibilities": [
          {
            "delivery_type_id": 4,
            "delivery_type_name": "pickup",
            "moment": {
              "start": {
                "date": "2020-07-27 16:00:00.000000",
                "timezone_type": 3,
                "timezone": "Europe/Amsterdam"
              }
            }
          }
        ],
        "location": {
          "location_name": "BRUSSEL DE BROUCKERE",
          "retail_network_id": "",
          "distance": "242",
          "latitude": "50.8506",
          "longitude": "4.35185",
          "location_code": "20100",
          "phone_number": null,
          "opening_hours": {
            "monday": [
              {
                "start": {
                  "date": "2020-07-27 08:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-27 12:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "start": {
                  "date": "2020-07-27 13:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-27 18:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "tuesday": [
              {
                "start": {
                  "date": "2020-07-28 08:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-28 12:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "start": {
                  "date": "2020-07-28 13:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-28 18:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "wednesday": [
              {
                "start": {
                  "date": "2020-07-29 08:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-29 12:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "start": {
                  "date": "2020-07-29 13:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-29 18:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "thursday": [
              {
                "start": {
                  "date": "2020-07-30 08:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-30 12:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "start": {
                  "date": "2020-07-30 13:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-30 18:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "friday": [
              {
                "start": {
                  "date": "2020-07-31 08:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-31 12:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              },
              {
                "start": {
                  "date": "2020-07-31 13:30:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-31 18:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "saturday": [
              {
                "start": {
                  "date": "2020-07-25 10:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                },
                "end": {
                  "date": "2020-07-25 13:00:00.000000",
                  "timezone_type": 3,
                  "timezone": "Europe/Amsterdam"
                }
              }
            ],
            "sunday": []
          }
        }
      }
    ]
  }
}

9. Delivery options Object Definitions

If you use the endpoint delivery_options you get two objects. DeliveryOptions Object and PickupOptions Object. OpeningHours Object contains the opening hours of pickup locations.

9.A DeliveryOptions Object Definition

DeliveryOptions Object contains possible delivery options. Besides these options would also be able to bring the customer has two other choices: only_recipient and signature. These two options could offer you as long as the address is in the Netherlands. Morning and Evening delivery types always used only_recipient.

9.A.1 Overview

date
Data type: date
Required: n/a.

time
Data type: DeliveryOptionTime
Required: n/a.

9.A.2 Example

Example

{
  "date": "2017-02-01",
  "time": [
    {
      "start": "08:00:00",
      "end": "12:00:00",
      "price": {
        "currency": "EUR",
        "amount": 1000
      },
      "price_comment": "morning",
      "comment": "",
      "type": 1
    },
    {
      "start": "11:30:00",
      "end": "13:30:00",
      "price": {
        "currency": "EUR",
        "amount": 0
      },
      "price_comment": "standard",
      "comment": "",
      "type": 2
    }
  ]
}

9.B PickupOptions Object Definition

PickupOptions Object contains possible PostNL locations.

9.B.1 Overview

date
Data type: date
Required: n/a.

time
Data type: PickupOptionTime
Required: n/a.

location
Data type: string
Required: n/a.

street
Data type: string
Required: n/a.

number
Data type: string
Required: n/a.

postal_code
Data type: string
Required: n/a.

city
Data type: string
Required: n/a.

start_time
Data type: time
Required: n/a.

price
Data type: integer
Required: n/a.

price_comment
Data type: string
Required: n/a.

comment
Data type: string
Required: n/a.

phone_number
Data type: string
Required: n/a.

opening_hours
Data type: string
Required: n/a.

distance
Data type: string
Required: n/a.

latitude
Data type: coordinates
Required: n/a.

longitude
Data type: coordinates
Required: n/a.

location_code
Data type: string
Required: n/a.

9.B.2 Example

Example

{
  "date": "2017-02-01",
  "time": [
    {
      "start": "16:00:00",
      "type": 4,
      "price": {
        "amount": 0,
        "currency": "EUR"
      }
    },
    {
      "start": "08:30:00",
      "type": 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",
  "phone_number": "023-5576310",
  "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.",
  "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"
}

9.C OpeningHours Object Definition

9.C.1 Overview

monday
Data type: array of string
Required: n/a.

tuesday
Data type: array of string
Required: n/a.

wednesday
Data type: array of string
Required: n/a.

thursday
Data type: array of string
Required: n/a.

friday
Data type: array of string
Required: n/a.

saterday
Data type: array of string
Required: n/a.

sunday
Data type: array of string
Required: n/a.

9.C.2 Example

Example

{
  "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": []
}

9.D DeliveryOptionTime Object Definition

9.D.1 Overview

start
Data type: time
Required: n/a.

end
Data type: time
Required: n/a.

price
Data type: price
Required: n/a.

price_comment
Data type: string
Required: n/a.

comment
Data type: string
Required: n/a.

type
Data type: integer
Required: n/a.

9.D.2 Example

Example

{
  "start": "08:00:00",
  "end": "12:00:00",
  "price": {
    "currency": "EUR",
    "amount": 1000
  },
  "price_comment": "morning",
  "comment": "",
  "type": 1
}

9.E PickupOptionTime Object Definition

9.E.1 Overview

start
Data type: time
Required: n/a.

type
Data type: integer
Required: n/a.

price
Data type: price
Required: n/a.

9.E.2 Example

Example

{
  "start": "16:00:00",
  "type": 4,
  "price": {
    "amount": 0,
    "currency": "EUR"
  }
}

10. Webhooks

10.A Add subscription

10.A.1 Overview

Use this endpoint to subscribe to an event in our API. Upon success a HTTP/1.1 200 OK with subscription ids is returned. You must use HTTPS for callback because it's secure and tamper proof. You can only have one webhook of each type at a time for a shop so adding the same webhook overwrites any existing one. We always send the webhook to a URL with lowercase characters. Therefore it is necessary to use lowercase characters in the URL of the webhook call.

We currently have two available hooks: shipment_status_change and shipment_label_created:

• shipment_status_change: Whenever the status of a shipment changes this webhook will send you an update with the new value. We will not send an update with a status 1.
• shipment_label_created: When a label is created asynchronously (for example when creating shipments using accept header application/vnd.shipment_label+json;charset=utf-8) this webhook will send you a message with the url of the label.

10.A.2 Reference

10.A.3 Example

Request

POST https://api.myparcel.nl/webhook_subscriptions HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
Content-Type:application/json; charset=utf-8
{
  "data": {
    "webhook_subscriptions": [
      {
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "ids": [
      {
        "id": 3
      }
    ]
  }
}

10.B Get subscriptions

10.B.1 Overview

Use this endpoint to fetch your active webhook subscriptions. Upon success a HTTP/1.1 200 with an array of Subscription objects is returned.

10.B.2 Reference

10.B.3 Parameters

id
Data type: integer
This is the subscription id. You can specify multiple subscription ids by semi-colon separating them on the URI.

10.B.4 Example

Request

GET https://api.myparcel.nl/webhook_subscriptions/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "webhook_subscriptions": [
      {
        "id": 123,
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

10.C Delete subscription

10.C.1 Overview

Use this endpoint to delete webhook subscriptions. You can specify multiple subscription ids by semi-colon separating them on the URI. Upon delete an HTTP/1.1 204 No Content is returned.

10.C.2 Reference

10.C.3 Parameters

id
Data type: integer.id
The id of the subscription to delete. You can specify multiple subscriptions by semi-colon separating them.

10.C.4 Example

Request

DELETE https://api.myparcel.nl/webhook_subscriptions/1 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 204 No Content

11. Webhook Object Definitions

11.A Subscription Object Definition

11.A.1 Overview

This object contains an event and a callback URL that will receive notifications.

id
Data type: integer
Required: No.
The id of the webhook subscription.

hook
Data type: string
(shipment_label_created or shipment_status_change) Required: Yes.
The event from which you want to receive notifications.

url
Data type: string
Required: Yes.
The callback URL on which to receive notifications. The URL protocol must be https.

account_id
Data type: integer
Required: No.
The ID of the account to which this subscription belongs.

shop_id
Data type: integer
Required: No.
The ID of the shop to which this subscription belongs.

11.A.2 Example

POST Example

{
  "hook": "shipment_status_change",
  "url": "https://seoshop.nl/myparcel/notifications"
}

GET Example

{
  "id": 79798,
  "account_id": 126594,
  "shop_id": 39399,
  "hook": "shipment_status_change",
  "url": "https://seoshop.nl/myparcel/notifications"
}

{
  "data": {
    "webhook_subscriptions": [
      {
        "id": 79798,
        "account_id": 126594,
        "shop_id": 39399,
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

11.B ShipmentStatusChangeEvent Object Definition

11.B.1 Overview

This object contains the shipment status change event. This object is sent to the callback URL specified in the Subscription object whenever a shipment status changes.

shipment_id
Data type: string
This is the shipment id.

account_id
Data type: integer
This is the account id to which the shipment belongs.

shop_id
Data type: integer
This is the shop to which the shipment belongs.

status
Data type: shipment_status
The shipment status.

barcode
Data type: string
This is the shipment barcode.

11.B.2 Reference

We send the following headers to your environment:

11.B.3 Example

{
  "shipment_id": "25482412",
  "account_id": 7003,
  "shop_id": 1897,
  "status": 2,
  "barcode": "3SMYPA749883621"
}

{
  "data": {
    "hooks": [
      {
        "shipment_id": "25482412",
        "account_id": 7003,
        "shop_id": 1897,
        "status": 2,
        "barcode": "3SMYPA749883621"
      }
    ]
  }
}

11.C ShipmentLabelCreated Object Definition

11.C.1 Overview

This object contains the shipment label created event. This object is sent to the callback URL specified in the Subscription object when a label is created asynchronously (for example when creating shipments using accept header application/vnd.shipment_label+json;charset=utf-8).

status
Data type: webhook status

shipment_ids
Data type: array of integer

printer_identifier
Data type: printer_identifier

pdf
Data type: string
This field contains a URL that leads to a PDF.

11.C.2 Reference

We send the following headers to your environment:

11.C.3 Example

{
  "status": "success",
  "shipment_ids": [
    15001826
  ],
  "printer_identifier": "YOUR_PRINTER_ID",
  "pdf": "https://api.myparcel.nl/pdfs/f569bc5a247fcec09d6a8cba16ff7629ca8062f3"

}

{
  "status": "failed",
  "shipment_ids": [
    15001820
  ],
  "printer_identifier": "",
  "pdf": "",
  "reason": "payment required"
}

{
  "data": {
    "hooks": [
      {
        "status": "success",
        "shipment_ids": [
          15001826
        ],
        "printer_identifier": "YOUR_PRINTER_ID",
        "pdf": "https://api.myparcel.nl/pdfs/f569bc5a247fcec09d6a8cba16ff7629ca8062f3"
      }
    ]
  }
}

11.D SubscriptionIds Object Definition

Overview

This object contains an array of SubscriptionId objects.

ids
Data type: array of SubscriptionId objects.
Required: n/a.
array of SubscriptionId objects.

11.E SubscriptionId Object Definition

Overview

id
Data type: integer
Required: n/a.
Subscription.id

12. Drop off points

12.A Get drop off points

12.A.1 Overview

Use this endpoint to receive a list of nearby drop off points, where shipments can be dropped off upon shipping. Results are ordered by distance from the provided postal code or coordinates.
When creating Instabox shipments, it is required to provide a drop off point.

12.A.2 Reference

12.A.3 Parameters

postal_code
Data type: string
Required: yes, unless longitude and latitude are used
The postal code for which to fetch drop off points in the area.

cc
Data type: country_code
Required: no
The country code for which to fetch the drop off points. This endpoint can only be used in the Netherlands (cc=NL).

carrier_id
Data type: carrier
Required: no
PostNL (1), Instabox (5), and UPS (8) are available.

distance
Data type: integer
Required: no
Provide the radius in kilometers for which you want to find drop off points. The default distance differs by carrier.

latitude
Data type: coordinates
Required: no
This provides the ability to find drop off points by coordinates. Should be used together with longitude.

longitude
Data type: coordinates
Required: no
This provides the ability to find drop off points by coordinates. Should be used together with latitude.

12.A.4 Example

Get drop off points for 2132JE for Instabox
Request

GET https://api.myparcel.nl/delivery_options?carrier_id=5&postal_code=2132JE HTTP/1.1
User-Agent: CustomApiCall/2
accept: application/json;charset=utf-8
                

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "drop_off_points": [
      {
        "location_code": "e9149b66-7bee-439b-bab0-7a5d92ddc519",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Hoofddorp",
        "postal_code": "2132WV",
        "street": "Diamantlaan",
        "number": "77",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.68156004,
        "latitude": 52.29063034,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 2076,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "09108a62-10a7-45ec-8b96-ab03b92182af",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Hoofddorp",
        "postal_code": "2131PZ",
        "street": "Paxlaan",
        "number": "10",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.68188469,
        "latitude": 52.30899335,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 2588,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "4757b869-b97f-4b98-a436-133cff0d8007",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "SCHIPHOL-RIJK",
        "postal_code": "1119NB",
        "street": "Koolhovenlaan",
        "number": "1",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.76706,
        "latitude": 52.28593,
        "available_days": [
          1,
          2,
          3,
          4,
          5
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 3895,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "2dc21869-17b2-49d7-b676-394761aa6a57",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Aalsmeer",
        "postal_code": "1431GD",
        "street": "Turfstekerstraat",
        "number": "27",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.775219,
        "latitude": 52.259905,
        "available_days": [
          1,
          2,
          3,
          4,
          5
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 5786,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "9b39e848-1430-4a8b-b92a-0198edd4c841",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Cruquius",
        "postal_code": "2143CH",
        "street": "Spaarneweg",
        "number": "75",
        "number_suffix": "C",
        "phone": null,
        "reference": null,
        "longitude": 4.628213,
        "latitude": 52.333788,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 7160,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "5cf69210-a9d5-4f0b-b232-1ab0cf39e71f",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Aalsmeer",
        "postal_code": "1432CE",
        "street": "Schinkeldijkje",
        "number": "4",
        "number_suffix": "B",
        "phone": null,
        "reference": null,
        "longitude": 4.82139,
        "latitude": 52.29148,
        "available_days": [
          1,
          2,
          3,
          4,
          5
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 7482,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "ea91722d-f4ba-40f0-a87f-c0c72f683125",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amstelhoek",
        "postal_code": "1427 AX",
        "street": "Mennonietenbuurt",
        "number": "29",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.82958,
        "latitude": 52.23026,
        "available_days": [
          1,
          2,
          3,
          4,
          5
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 10743,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "da2ba2c9-03a7-47dd-abcc-b6c98cd72382",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1067PL",
        "street": "Daam van Harenstraat",
        "number": "14",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.80402,
        "latitude": 52.37428,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 10887,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "13420d8b-c290-4a15-bd71-3244d3b035b0",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Haarlem",
        "postal_code": "2031BJ",
        "street": "Hendrik Figeeweg",
        "number": "5",
        "number_suffix": "A",
        "phone": null,
        "reference": null,
        "longitude": 4.652859,
        "latitude": 52.389378,
        "available_days": [
          2,
          3,
          4,
          5
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 11291,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "e3ccc1d5-ec90-4738-84a6-35596abede1b",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amstelveen",
        "postal_code": "1183HK",
        "street": "Kostverlorenhof",
        "number": "150",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.87691,
        "latitude": 52.31295,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 11437,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "354f88db-2bcd-4eb7-bb28-d7e7adc56804",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1076SZ",
        "street": "Marathonweg",
        "number": "21",
        "number_suffix": "-23",
        "phone": null,
        "reference": null,
        "longitude": 4.861751,
        "latitude": 52.34824,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 11841,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "1025f656-fee9-4d5a-ad86-60c91370294c",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1046 AG",
        "street": "Pleimuiden",
        "number": "10",
        "number_suffix": "C",
        "phone": null,
        "reference": null,
        "longitude": 4.78694,
        "latitude": 52.390865,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 11893,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "373c2d08-dcad-4f31-9c01-5e95a284f7ba",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Lisse",
        "postal_code": "2161LE",
        "street": "Vennestraat",
        "number": "52",
        "number_suffix": "g",
        "phone": null,
        "reference": null,
        "longitude": 4.54992,
        "latitude": 52.25069,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 12017,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "d1c9f43b-b796-45d5-9aa5-bbaaedf26b66",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1053GB",
        "street": "Kinkerstraat",
        "number": "270",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.8645501,
        "latitude": 52.3652267,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 13050,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "290e43b0-7666-4c28-a02a-3743c818fc3a",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Lisse",
        "postal_code": "2161 DH",
        "street": "Heereweg",
        "number": "448",
        "number_suffix": "B",
        "phone": null,
        "reference": null,
        "longitude": 4.53643847,
        "latitude": 52.23953247,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 13381,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "9f0b602e-af0c-432a-b6d8-507644b393fe",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1072ER",
        "street": "Ceintuurbaan",
        "number": "11",
        "number_suffix": "HS",
        "phone": null,
        "reference": null,
        "longitude": 4.887313,
        "latitude": 52.352459,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 13585,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "992de390-4dd5-43f5-a331-6ba995111ed7",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1078PZ",
        "street": "Rijnstraat",
        "number": "59",
        "number_suffix": "H",
        "phone": null,
        "reference": null,
        "longitude": 4.90515,
        "latitude": 52.34651,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 14384,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "6efb5bd8-1f97-4a58-b187-68bd0207d027",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1016LR",
        "street": "Rozengracht",
        "number": "25",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.88179,
        "latitude": 52.37367,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 14550,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "db927fda-c3da-4242-bce9-e3c56eb8004e",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1013SZ",
        "street": "Spaarndammerbuurt",
        "number": "490",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.88,
        "latitude": 52.388908,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 15544,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "c25ec25d-2554-4fa6-a9d9-e1d9b45f5ff7",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Nieuwkoop",
        "postal_code": "2421AX",
        "street": "Dorpsstraat",
        "number": "153",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.78182,
        "latitude": 52.15176,
        "available_days": [
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 16564,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "22350eb5-26f4-43bf-b720-76714214840b",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1098RB",
        "street": "Christiaan Huygensplein",
        "number": "12",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.93873,
        "latitude": 52.34937,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 16613,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "db9eb896-be2b-4cc4-8b95-9b0a5a001155",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Amsterdam",
        "postal_code": "1032KK",
        "street": "Klaprozenweg",
        "number": "21",
        "number_suffix": "A",
        "phone": null,
        "reference": null,
        "longitude": 4.9106586,
        "latitude": 52.3964524,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 17662,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "ab130002-28ad-4155-978f-8bcc42fe779e",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Vinkeveen",
        "postal_code": "3645DP",
        "street": "Herenweg",
        "number": "12",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.93652,
        "latitude": 52.21272,
        "available_days": [
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 17806,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "354f34ba-21f2-4e14-ba01-5ea3c878ea00",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Diemen",
        "postal_code": "1112AT",
        "street": "Visseringweg",
        "number": "82",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.97182,
        "latitude": 52.33219,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 18191,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      },
      {
        "location_code": "3546a7a1-0442-42a1-ab5d-7fde04e9024e",
        "location_name": "Instabox",
        "cc": "NL",
        "state": null,
        "city": "Noordwijk",
        "postal_code": "2203GB",
        "street": "Rederijkersplein",
        "number": "6",
        "number_suffix": null,
        "phone": null,
        "reference": null,
        "longitude": 4.45187,
        "latitude": 52.24139,
        "available_days": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "cut_off_time": "10:00",
        "carrier_id": 5,
        "distance": 18622,
        "occupancy": null,
        "occupancy_today": null,
        "default_drop_off_point": null,
        "opening_hours": null
      }
    ]
  }
}

14. Document changes

Click here for the latest version of the API documentation. Last version update is done on .