Introduction

This is the documentation for the MyParcel.com API. Our API is build in such a way to easily handle bulk operations. We try to follow the REST architecture as much as possible but deviate from it when we need to achieve high performance.

The Base URL for all requests is: https://api.myparcel.com

You are looking at the most up-to-date version of the Documentation of the MyParcel.com API. We are currently working on some major updates on our API prior to the go-live of MyParcel.com the coming weeks. Paralel to these updates on the API, we will also thoroughly update this documentation page and add possible use cases and examples. Please send an e-mail to support@myparcel.com if you would like to stay updated on changes and our GO- live date.

  1. We greatly appreciate any feedback. We always try to improve our API.
  2. It would be great if you could send us examples of your requests before releasing your version to the end user. This so we can review your request and provide you with feedback and suggestions. Your examples may be sent to support@myparcel.com.

1. Requests

Base URL

BaseURL: https://api.myparcel.com

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.A GET

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

1.B POST

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

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

2. Responses

As stated earlier data is usually send back in JSON format. Exceptions to this rule are shipment label, invoice and CSV export. Shipment label and invoice are send back in PDF format while CSV export is send 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.com/
Request Headers (example!):
GET / HTTP/1.1
Host: api.myparcel.com
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
Accept-Encoding: gzip, deflate, sdch, br

Response:

{
  "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 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 send. 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 is always 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 send 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.com / 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 it's own data types.

4.1 Contents

array

description array of elements. Can contain all other data types.
pattern *
example

boolean

description boolean value
pattern 1 or 0
example 0 (false), 1 (true)

carrier

description Carrier id
pattern \d+
example 2 (PostNL)

carrier_service

description Carrier service id
pattern \d+
example 3 (PostNL - Letterbox)

country_code

description ISO3166-1 alpha2 country code
pattern [A-Z]{2,2}
example NL, BE, CW

currency

description ISO 4217 currency code
pattern EUR
example EUR

date

description Date
pattern [YYYY-MM-DD]
example 2015-01-01

delivery_type

description The delivery type.
pattern [1 – 5]
example
  1. morning
  2. standard
  3. night
  4. pickup
  5. pickup express

integer

description Whole numeric value
pattern [0-9]+
example 10. 20. NOT 2,3

isic_code

description International Standard Industry Classification
pattern [0-9]{1,4}
example 0111 (Growing of cereals (except rice), leguminous crops and oil seeds)

label_position

description The position of the label on the paper.
pattern [1 - 4]
example
  1. (top-left)
  2. (top-right)
  3. (bottom-left)
  4. (bottom-right)

month_digit

description The month in digit preceded by a zero for single digit months
pattern [0-1][1-9]+
example 01 (Jan), 02 (Feb) etc.

package_contents

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

description The content type of a package.
pattern [1 - 5]
example
  1. commercial goods
  2. commercial samples
  3. documents
  4. gifts
  5. return shipment

package_type

description package_type
pattern [1 – 3]
example
  1. package
  2. mailbox package
  3. letter

paper_size

description The size of a paper as specified in ISO216.
pattern A4 or A6
example A4

price

description composite type containing integer and currency. The amount is without decimal separators (in cents).
pattern {"amount": integer, "currency": currency }
example {"amount": 5000, "currency": "EUR"}

shipment_status

description shipment_status
pattern [1-99]
example
  • 1 pending - concept
  • 2 pending - registered
  • 3 enroute - handed to carrier
  • 4 enroute - sorting
  • 5 enroute - distribution
  • 6 enroute - customs
  • 7 delivered - at recipient
  • 8 delivered - ready for pickup
  • 9 delivered - package picked up
  • 10 delivered - return shipment ready for pickup
  • 11 delivered - return shipment package picked up
  • 12 printed - letter
  • 13 credit
  • 30 inactive - concept
  • 31 inactive - registered
  • 32 inactive - enroute - handed to carrier
  • 33 inactive - enroute - sorting
  • 34 inactive - enroute - distribution
  • 35 inactive - enroute - customs
  • 36 inactive - delivered - at recipient
  • 37 inactive - delivered - ready for pickup
  • 38 inactive - delivered - package picked up
  • 99 inactive - unknown
  • 100 credit rejected
  • 101 credit approved

sort_order

description sort order value
pattern ASC or DESC
example ASC (ascending), DESC (descending)

string

description any alphanumeric value up to 255 characters.
pattern *{0,255}
example e.g 1; 2; 3; 4

text

description Any character up to a limit of 2048 characters.
pattern (.*){,2048}
example This is a test text.

time

description Time.
pattern HH:MM:SS
example 08:00:00

timestamp

description Date and time.
pattern YYYY-MM-DD HH:MM:SS
example 2015-01-01 08:00:00

weekday_digit

description Weekday in digit
pattern [0-6]{1,1}
example 0 (Sunday), 1 (Monday), ...

weekday_string

description Weekday in string
pattern sunday OR monday OR tuesday OR wednesday OR thursday OR friday OR saturday
example sunday

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.

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 MyParcel.com UI, 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 recommende 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 three 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 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 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.

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 shipments with package type 1. 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.

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

The package is delivered in the evening on the delivery date specified. Currently this is only available for Tuesday and Thursday, but it is expected to be broadened to other days of the week as well.

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.

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 5000,- 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.

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 only_recipient and 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 (5000, 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 Brussel. 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

URI https://api.myparcel.com/shipments
Methods POST
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
Content-type: application/vnd.shipment+json; charset=utf-8 (For Shipments JSON request)
Content-type: application/vnd.shipment_recipients+json; charset=utf-8 (For Shipments with recipients column JSON request)
Content-type: application/vnd.return_shipment+json; charset=utf-8 (For ReturnShipments JSON request)
Content-type: application/vnd.unrelated_return_shipment+json; charset=utf-8 (For UnrelatedReturnShipments JSON request)
URI parameters None.
Query parameters None.
Request body array of Shipment objects. (For Shipments JSON request)
array of ReturnShipment objects. (For ReturnShipments JSON request)
array of UnrelatedReturnShipment objects. (For UnrelatedReturnShipments JSON request)
Response HTTP/1.1 200 OK Content-Type: application/vnd.shipment_ids+json; charset=utf-8 (For standard and related return shipment.)
Response body ShipmentIds
Error response HTTP/1.1 4xx < MESSAGE >.
Error response body Error

6.B.3 Request Headers

Content-Type: application/vnd.shipment+json
Specify this content-type when you want to create standard shipments.

Content-Type: application/vnd.return_shipment+json
Specify this content-type when you want to create related return shipments.

Content-Type: application/vnd.unrelated_return_shipment+json
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 national shipments

Request

POST https://api.myparcel.com/shipments HTTP/1.1
Content-Type:application/vnd.shipment+json;charset=utf-8
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [{
      "recipient": {
        "cc": "NL",
        "city": "Hoofddorp",
        "street": "Siriusdreef",
        "number": "66",
        "postal_code": "2132WT",
        "person": "Mr. Parcel",
        "phone": "0213030315",
        "email": "testing@myparcel.com"
      },
      "options": {
        "package_type": 1,
        "only_recipient": 1,
        "signature": 1,
        "return": 1,
        "insurance": {
          "amount": 50000,
          "currency": "EUR"
        },
        "large_format": 0
      },
      "carrier": 1
    }, {
      "recipient": {
        "cc": "NL",
        "city": "Amsterdam",
        "street": "Dorpstraat",
        "number": "123",
        "postal_code": "1020BC",
        "person": "Mrs. Parcel",
        "phone": "02012343546",
        "email": "info@myparcel.com"
      },
      "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
    }, {
      "id": 68794
    }]
  }
}

Create International shipment

Request

POST https://api.myparcel.com/shipments HTTP/1.1 Content-Type:application/vnd.shipment+json;
charset=utf-8 Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [{
      "recipient": {
        "cc": "JP",
        "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
    }]
  }
}

Create shipment with pickup location

Request

POST https://api.myparcel.com/shipments HTTP/1.1 Content-Type:application/vnd.shipment+json;
charset=utf-8 Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "shipments": [{
      "recipient": {
        "cc": "NL",
        "city": "Hoofddorp",
        "street": "Siriusdreef",
        "number": "66",
        "postal_code": "2132WT",
        "person": "Mr. Parcel",
        "phone": "0213030315",
        "email": "testing@myparcel.com"
      },
      "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
    }]
  }
}

Create related return shipment

Request

POST https://api.myparcel.com/shipments HTTP/1.1 Content-Type:application/vnd.return_shipment+
json;charset=utf-8 Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
{
  "data": {
    "return_shipments": [{
      "parent": 5,
      "carrier": 1,
      "email": "testing@myparcel.com",
      "name": "Mr. Parcel",
      "options": {
        "package_type": 1,
        "only_recipient": 0,
        "signature": 1,
        "return": 0,
        "insurance": {
          "amount": 50,
          "currency": "EUR"
        }
      }
    }]
  }
}

Response

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

Create unrelated return shipment

Request

POST https://api.myparcel.com/shipmentsHTTP/1.1 Content-Type:
application/vnd.unrelated_return_shipment+json;charset=utf-8
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": "test"
      },
      "carrier": 1,
      "email": "testing@myparcel.com",
      "name": "Test"
    }]
  }
}

Response

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

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 201 if successful. If the shipment doesn’t exist a 422 "cannot delete shipment" is returend.

6.C.2 Reference

URI https://api.myparcel.com/shipments/id[;id]
Methods DELETE
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
Content-type: application/json; charset=utf-8
URI parameters id = Shipment.id.
Query parameters None.
Request body None.
Response HTTP/1.1 201 OK
Response body None.
Error response HTTP/1.1 4xx < MESSAGE >.
Error response body Error

6.C.3 Parameters

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

6.C.4 Example

Remove a shipment with id 1234.

Request

DELETE https://api.myparcel.com/shipments/1234 HTTP/1.1
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 201 No Content

6.D Generate unrelated return shipment

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

URI https://api.myparcel.com/return_shipments
Methods POST
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters None.
Query parameters None.
Request body None.
Response HTTP/1.1 200 OK Content-Type: application/json
Response body DownloadUrl object.
Error response HTTP/1.1 4xx < MESSAGE >
HTTP/1.1 5xx < MESSAGE >
Error response body None.

6.D.3 Example

Proceed with actual request
Request

POST https://api.myparcel.com/return_shipments
HTTP/1.1 Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

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

6.E Get Shipment

6.E.1 Overview

With this endpoint you can get shipments. You can use the 'q' query parameter to search for shipments. Depending on the Accept request header either JSON or CSV is returned. Multiple shipment ids can be specified on the URI by using 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

URI https://api.myparcel.com/shipments/[id[;id]]
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters id= Shipment.id
Query parameters q= string
dropoff_today= boolean
status= shipment_status
from= timestamp
to= timestamp
page= integer
size= integer
sort= string
order= sort_order
Optional request headers Accept: application/json; charset=utf-8 (For JSON)
Request body None.
Response HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8 (For JSON)
Response body array of Shipment objects (For JSON)
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

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.

dropoff_today
Data type: boolean
Use this parameter to filter for shipments that need to dropped at a drop-off location today.

q
Data type: string
Use this parameter to search true 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.com/shipments?q=Niels&status=1
HTTP/1.1 Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "search_results": {
      "shipments": [{
        "recipient": {
          "cc": "NL",
          "city": "Hoofddorp",
          "street": "Siriusdreef",
          "number": "66",
          "postal_code": "2132WT",
          "person": "Mr. Parcel",
          "phone": "0213030315",
          "email": "testing@myparcel.com"
        },
        "options": {
          "package_type": 1,
          "only_recipient": 1,
          "signature": 1,
          "return": 1,
          "insurance": {
            "amount": 50000,
            "currency": "EUR"
          },
          "large_format": 0
        },
        "sender": {
          "cc": "NL",
          "city": "Amsterdam",
          "street": "Dorpstraat",
          "number": "123",
          "postal_code": "1020BC",
          "person": "Mrs. Parcel",
          "phone": "02012343546",
          "email": "info@myparcel.com"
        },
        "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"
      }],
      "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.

Upon error HTTP/1.1 4xx < MESSAGE > with a response body containing an Error is returned.

6.F.2 Reference

URI https://api.myparcel.com/shipment_labels/id[;id]
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
Accept: application/pdf (For the PDF binary. This is the default.)
Accept: application/json; charset=utf8 (For ShipmentLabelDownloadLink)
URI parameters id= Shipment.id
Query parameters format = paper_size
positions = label_position
Request body None.
Response HTTP/1.1 200 OK Content-Disposition: attachment; filename="< PDF_FILE >" Content-Type: application/pdf
HTTP/1.1 200 OK Content-Type: application/json (When using "Accept: application/json; charset=utf8)
HTTP/1.1 402 Payment Required Content-Type: application/json (When payment is required.)
Response body Shipment label PDF
ShipmentLabelDownloadLink (When using "Accept: application/json; charset=utf8)"
PaymentInstructions (When payment is required)
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

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.com/shipment_labels/12 HTTP/1.1
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.com/shipment_labels/12 HTTP/1.1
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.com/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.com/shipment_labels/2?format=A4&positions=3;4 HTTP/1.1 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 Reference

URI https://api.myparcel.com/tracktraces/id[;id]
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters id= Shipment.id.
Query parameters page= integer
size= integer
sort= string
order= sort_order
Request body None.
Response HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Response body array of TrackTrace objects.
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

6.G.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.

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.

6.G.4 Example

Request

GET https://api.myparcel.com/tracktraces/12 HTTP/1.1
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "tracktraces": [{
      "shipment_id": "1234",
      "code": "D3",
      "final": false,
      "description": "The package is in distribution",
      "time": "2015-01-02 05:00:00",
      "history": [{
        "code": "C3",
        "description": "The package is at the sorting center",
        "time": "2015-01-02 05:00:00"
      }, {
        "code": "B2",
        "description": "The package is has been scanned",
        "time": "2015-01-01 06:00:00"
      }]
    }, {
      "shipment_id": "569034234",
      "code": "B4",
      "description": "The package is at the sorting center",
      "time": "2015-01-02 05:00:00",
      "history": [{
        "code": "A2",
        "description": "The package has been scanned",
        "time": "2015-01-01 05:00:00"
      }]
    }]
  }
}

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.

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 and 5.
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 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.

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

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

region
Data type: string
Required: n/a.

7.A.2 Example

POST example national shipment

{
  "recipient": {
    "cc": "NL",
    "city": "Hoofddorp",
    "street": "Siriusdreef",
    "number": "66",
    "postal_code": "2132WT",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@myparcel.com"
  },
  "options": {
    "package_type": 1,
    "only_recipient": 1,
    "signature": 1,
    "return": 1,
    "insurance": {
      "amount": 5000,
      "currency": "EUR"
    },
    "large_format": 0
  },
  "carrier": 1
}

POST example national shipment b

{
  "recipient": {
    "cc": "NL",
    "city": "Amsterdam",
    "street": "Dorpstraat",
    "number": "123",
    "postal_code": "1020BC",
    "person": "Mrs. Parcel",
    "phone": "02012343546",
    "email": "info@myparcel.com"
  },
  "options": {
    "package_type": 1,
    "only_recipient": 1,
    "signature": 1,
    "return": 1
  },
  "carrier": 1
}

POST example international shipment

{
  "recipient": {
    "cc": "JP",
    "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",
        "city": "Hoofddorp",
        "street": "Siriusdreef",
        "number": "66",
        "postal_code": "2132WT",
        "person": "Mr. Parcel",
        "phone": "0213030315",
        "email": "testing@myparcel.com"
      },
      "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

{
  "recipient": {
    "cc": "NL",
    "city": "Hoofddorp",
    "street": "Siriusdreef",
    "number": "66",
    "postal_code": "2132WT",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@myparcel.com"
  },
  "options": {
    "package_type": 1,
    "only_recipient": 1,
    "signature": 1,
    "return": 1,
    "insurance": {
      "amount": 50000,
      "currency": "EUR"
    },
    "large_format": 0
  },
  "sender": {
    "cc": "NL",
    "city": "Amsterdam",
    "street": "Dorpstraat",
    "number": "123",
    "postal_code": "1020BC",
    "person": "Mrs. Parcel",
    "phone": "02012343546",
    "email": "info@myparcel.com"
  },
  "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",
    "city": "Amsterdam",
    "street": "Dorpstraat",
    "number": "123",
    "postal_code": "1020BC",
    "person": "Mrs. Parcel",
    "phone": "02012343546",
    "email": "info@myparcel.com"
  },
  "options": {
    "package_type": 1,
    "only_recipient": 1,
    "signature": 1,
    "return": 1
  },
  "sender": {
    "cc": "NL",
    "city": "Hoofddorp",
    "street": "Siriusdreef",
    "number": "66",
    "postal_code": "2132WT",
    "person": "Mr. Parcel",
    "phone": "0213030315",
    "email": "testing@myparcel.com"
  },
  "carrier": 2,
  "status": 2,
  "price": {
    "amount": 535,
    "currency": "EUR"
  },
  "barcode": "563716278632716817283",
  "created": "2017-01-31 08:00:00",
  "modified": "2017-01-31 09:00:00"
}

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.

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.

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 NL.
Street number.

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

person
Data type: string
Required: yes.
The person at this address.

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",
  "city": "Hoofddorp",
  "street": "Siriusdreef",
  "number": "66",
  "postal_code": "2132WT",
  "person": "Mr. Parcel",
  "phone": "0213030315",
  "email": "parcel@myparcel.com"
}

Example b

{
  "cc": "NL",
  "city": "Hoofddorp",
  "street": "Siriusdreef",
  "number": "66",
  "number_suffix": "68",
  "postal_code": "2132WT",
  "person": "Mrs. Parcel",
  "phone": "0213030315",
  "email": "parcel@myparcel.com"
}

Example c

{
  "cc": "FR",
  "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",
  "city": "Zoetermeer",
  "street": "Louiarmstrongrode",
  "number": "18",
  "postal_code": "2717NH",
  "person": "Pato otap",
  "phone": "0790880808",
  "email": "pato@otap.nl"
}

Example e

{
  "cc": "NL",
  "city": "Hoofddorp",
  "street": "Siriusdreef",
  "number": "66",
  "person": "Jan Peter",
  "company": "MyParcel B.V.",
  "email": "janpeter@bedrijven.nl",
  "phone": "0203030315"
}

Example i

{
  "cc": "JP",
  "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",
  "Siriusdreef",
  "66",
  "Claus Stuter",
  "MyParcel B.V.",
  "claus@stuter.nl",
  "0203030315",
}

Example CSV b

{
  "cc",
  "postalcode",
  "city",
  "street",
  "number",
  "person",
  "company",
  "email",
  "phone""nl",
  "2132WT",
  "Hoofddorp",
  "Siriusdreef",
  "66",
  "Mrs. Parcel",
  "MyParcel",
  "parcel@myparcel.com",
  "0213030315"
}

Example CSV c

{
  "nl",
  "2132WT",
  "Hoofddorp",
  "Siriusdreef",
  "66",
  "Arie Test",
  "MyParcel",
  "arie@myparcel.com",
  "0213030319"
}

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.

delivery_remark
Data type: string
Required: No.
The delivery remark.

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.

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

7.C.2 Example

Example a

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

Example b

{
  "package_type": 1,
  "only_recipient": 0,
  "signature": 1,
  "return": 0,
  "insurance": {
    "amount": 50,
    "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": 50,
    "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.

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

7.D.2 Example

Example

{
  "save_recipient_address": 1,
  "delivery_notification": 1,
  "delivery_notification_email": "testing@myparcel.com"
}

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.

7.I.2 Example

POST example

{
  "parent": 123456,
  "carrier": 1,
  "email": "testing@myparcel.com",
  "name": "Mr. Parcel",
  "options": {
    "package_type": 1,
    "only_recipient": 0,
    "signature": 1,
    "return": 0,
    "insurance": {
      "amount": 5000,
      "currency": "EUR"
    }
  }
}

7.J UnrelatedReturnShipment Object Definition

7.J.1 Overview

You can create a 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.

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

7.J.2 Example

POST example

{
  "carrier": 1,
  "email": "testing@myparcel.com",
  "name": "Mr. Parcel",
  "options": {
    "package_type": 1,
    "only_recipient": 0,
    "signature": 1,
    "return": 0,
    "insurance": {
      "amount": 50,
      "currency": "EUR"
    }
  }
}

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://accounts.myparcel.com/retour/8005ebb27d55425c5eaf2dff2fa41147"
}

7.L TrackTrace Object Definition

7.L.1 Overview

This is the tracktrace object.

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

code
Data type: string
Required: n/a.

final
Data type: boolean
Required: n/a.

description
Data type: string
Required: n/a.

time
Data type: time
Required: n/a.

history
Data type: TrackTraceHistory
Required: n/a.

7.L.2 Example

POST example

{
  "shipment_id": "1234",
  "code": "D3",
  "final": false,
  "description": "The package is in distribution",
  "time": "2015-01-02 05:00:00",
  "history": [{
    "code": "C3",
    "description": "The package is at the sorting center",
    "time": "2015-01-02 05:00:00"
  }, {
    "code": "B2",
    "description": "The package is has been scanned",
    "time": "2015-01-01 06:00:00"
  }]
}

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.

7.M.2 Example

POST example

{
  "code": "C3",
  "description": "The package is at the sorting center",
  "time": "2015-01-02 05:00:00"
}

7.N PhysicalProperties Object Definition

7.N.1 Overview

This is the physical properties object.

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.

7.O.2 Example

POST example

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

7.P PaymentInstructions Object Definition

7.P.1 Overview

This is the payment instruction object.

id
Data type: integer
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.com/pdfs/461efc8b5c7e71dbd0c39a25067bda9455b0ca5a"
}

8. Delivery options

8.A Get delivery options

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

URI https://api.myparcel.com/delivery_options
Methods GET
Required request headers None.
URI parameters None.
Query parameters cc = country_code
postal_code = string
number = string
carrier = carrier
delivery_time = time
delivery_date = date
cutoff_time = time
dropoff_days = weekday_digit
monday_delivery = boolean
dropoff_delay = integer
deliverydays_window = integer
exclude_delivery_type = delivery_type
Request body None.
Response HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Response body array of DeliveryOptions and array of PickupOptions objects
Error response HTTP/1.1 5xx < MESSAGE >
Error response body None.
Error response HTTP/1.1 503 < MESSAGE >
Error response body 503 Error
Error response body Example
{
  "data": {
    "delivery": [],
    "pickup": [],
    "message": "No results"
  },
  "errors": [{
    "code": 9,
    "message": "Example",
    "human": "Example"
  }]
}

8.A.3 Parameters

cc
Data type: country_code
Required: yes
The country code for which to fetch the delivery options.

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.

carrier
Data type: carrier
Required: yes.
The carrier id for which to fetch the delivery options.

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 the carrier 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 a drop-off location 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 drop-off 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.

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 over to the carrier 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 her chosen carrier 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.

8.A.4 Example

Get delivery options for 2132WT, 66 for PostNL
Request

GET https://api.myparcel.com/delivery_options?cc=NL&postal_code=2132WT&number=66&carrier=2 HTTP/1.1

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",
      "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",
      "location_code": "176227"
    }, {
      "date": "2017-02-01",
      "time": [{
        "start": "16:00:00",
        "type": 4,
        "price": {
          "amount": 0,
          "currency": "EUR"
        }
      }]
    }]
  }
}

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.com/delivery_options?cc=NL&postal_code=2132WT&number=66&carrier=2&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

Response

HTTP/1.1 200 OK Content-Type:application/json;charset=utf-8
{
  "data": {
    "delivery": [{
      "date": "2017-05-06",
      "time": [{
        "start": "08:30:00",
        "end": "21:30:00",
        "price": {
          "currency": "EUR",
          "amount": 0
        },
        "price_comment": "standard",
        "comment": "",
        "type": 2
      }]
    }, {
      "date": "2017-05-08",
      "time": [{
        "start": "10:30:00",
        "end": "13:00:00",
        "price": {
          "currency": "EUR",
          "amount": 0
        },
        "price_comment": "standard",
        "comment": "",
        "type": 2
      }]
    }],
    "pickup": [{
      "date": "2017-05-06",
      "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": "1798",
      "location_code": "173187"
    }, {
      "date": "2017-05-06",
      "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": "1696",
      "location_code": "176227"
    }]
  }
}

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 all possible drop-off 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.

cc
Data type: country_code
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.

location_code
Data type: string
Required: n/a.

lat
Data type: float
Required: n/a.

long
Data type: float
Required: n/a.

carrier
Data type: carrier
Required: n/a.

9.B.2 Example

Example a

{
  "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",
  "cc": "NL",
  "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",
  "location_code": "173187",
  "lat": 52.286582,
  "long": 4.682377,
  "carrier": 2
}

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 temper proof. Adding the same webhook overwrites the existing one.

10.A.2 Reference

URI https://api.myparcel.com/webhook_subscriptions
Methods POST
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
Content-type: application/json; charset=utf-8
URI parameters None.
Query parameters None.
Request body array of Subscription objects.
Response HTTP/1.1 200 OK
Response body SubscriptionIds
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

10.A.3 Example

Request

POST https://api.myparcel.com/webhook_subscriptions HTTP/1.1
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 Delete subscription

10.B.1 Overview

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

10.B.2 Reference

URI https://api.myparcel.com/webhook_subscriptions/id[;id]
Methods DELETE
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
Content-type: application/json; charset=utf-8
URI parameters id = Subscription.id.
Query parameters None.
Request body None.
Response HTTP/1.1 204 No Content
Response body None.
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

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.B.4 Example

Request

DELETE https://api.myparcel.com/webhook_subscriptions/1 HTTP/1.1
Authorization:basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 204 No Content

10.C Get subscription

10.C.1 Overview

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

10.C.2 Reference

URI https://api.myparcel.com/webhook_subscriptions/id[;id]
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters id = Subscription.id
Query parameters None.
Request body None.
Response HTTP/1.1 201 OK
Response body array of Subscription objects
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

10.C.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.C.4 Example

Request

GET https://api.myparcel.com/webhook_subscriptions/12 HTTP/1.1
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"
    }]
  }
}

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
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 must be https.

account_id
Data type: integer
Required: No.
The account id to which this subscription belongs.

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

11.A.2 Example

POST Example

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

GET Example

{
  "id": 123,
  "account_id": 1,
  "shop_id": 2,
  "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
This is the shipment id.

account_id
This is the account id to which the shipment belongs.

shop_id
This is the shop to which the shipment belongs.

status
The shipment status.

barcode
This is the shipment barcode.

11.B.2 Example

Example a

{
  "shipment_id": 1,
  "account_id": 1,
  "shop_id": 2,
  "status": 3,
  "barcode": "3SMYPA12302837"
}

11.C 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.D SubscriptionId Object Definition

Overview

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

12. Carriers and Services

12.A Get Carriers

12.A.1 Overview

Get all supported carriers for your account. Upon success HTTP/1.1 200 OK is returned with an array of Carrier objects.

12.A.2 Reference

URI https://api.myparcel.com/carriers
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters None.
Query parameters None.
Request body None.
Response HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Response body array of Carrier objects.
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

12.A.3 Example

Request

GET https://api.myparcel.com/carriers HTTP/1.1
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "carriers": [{
      "id": 1,
      "name": "Myparcel.com",
      "cc": "NL",
      "currency": "EUR"
    }, {
      "id": 2,
      "name": "PostNL",
      "cc": "NL",
      "currency": "EUR"
    }, {
      "id": 3,
      "name": "Bpost",
      "cc": "BE",
      "currency": "EUR"
    }, {
      "id": 4,
      "name": "DPD",
      "cc": "GB",
      "currency": "GBP"
    }, {
      "id": 5,
      "name": "Hermes",
      "cc": "GB",
      "currency": "GBP"
    }],
    "results": 5,
    "page": 1,
    "size": 5
  }
}

12.A.4 Object Definition

This is the Carrier object.

id
Data type: integer
Required: n/a.

name
Data type: string
Required: n/a.

cc
Data type: country_code
Required: n/a.

currency
Data type: string
Required: n/a.

12.B Get Carrier Services

12.B.1 Overview

Get all carrier services. Upon success HTTP/1.1 200 OK is returned with an array of CarrierService objects.

12.B.2 Reference

URI https://api.myparcel.com/carrier_services
Methods GET
Required request headers Authorization: basic BASE64(API_KEY OR SESSION_TOKEN)
URI parameters None.
Query parameters None.
Request body None.
Response HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Response body array of CarrierService objects.
Error response HTTP/1.1 4xx < MESSAGE >
Error response body Error

12.B.3 Example

Request

GET https://api.myparcel.com/carrier_services HTTP/1.1
              Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==

Response

HTTP/1.1 200 OK Content-Type:application/json; charset=utf-8
{
  "data": {
    "carrier_services": [{
      "id": 1,
      "carrier_id": 1,
      "active": 1,
      "type": "unstamped",
      "name": "Unstamped Label",
      "groups": [{
        "id": 0
      }],
      "prices": {
        "NL": {
          "base": [0]
        },
        "BE": {
          "base": [0]
        },
        "GB": {
          "base": [0]
        }
      }
    }, {
      "id": 2,
      "carrier_id": 2,
      "active": 1,
      "type": "parcel",
      "name": "PostNL Parcel",
      "groups": [{
        "id": 0,
        "name": "0-10kg",
        "weight": {
          "min": 0,
          "max": 10
        }
      }, {
        "id": 1,
        "name": "10 - 20",
        "weight": {
          "min": 10,
          "max": 20
        }
      }, {
        "id": 2,
        "name": "20 plus",
        "weight": {
          "min": 20,
          "max": null,
          "step": 0.5
        }
      }],
      "prices": {
        "NL": {
          "base": [585, 650, 850],
          "step": [0, 0, 50],
          "options": [{
            "name": "only_recipient",
            "price": 27
          }, {
            "name": "signature",
            "price": 35
          }, {
            "name": "only_recipient_signature",
            "price": 42
          }, {
            "name": "insured",
            "price": 0
          }, {
            "name": "large_format",
            "price": 42
          }, {
            "name": "return",
            "price": 42
          }],
          "insurances": [{
            "amount": 5000,
            "price": 50
          }, {
            "amount": 10000,
            "price": 100
          }, {
            "amount": 50000,
            "price": 168
          }, {
            "amount": 100000,
            "price": 336
          }, {
            "amount": 150000,
            "price": 504
          }, {
            "amount": 200000,
            "price": 672
          }, {
            "amount": 250000,
            "price": 840
          }]
        },
        "BE": {
          "base": [685, 750, 950],
          "increment": [0, 0, 50],
          "options": [{
            "name": "only_recipient",
            "price": 27
          }, {
            "name": "signature",
            "price": 35
          }, {
            "name": "only_recipient_signature",
            "price": 42
          }, {
            "name": "insured",
            "price": 0
          }, {
            "name": "large_format",
            "price": 42
          }, {
            "name": "return",
            "price": 42
          }],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }]
        },
        "GB": {
          "base": [785, 850, 1050],
          "increments": [0, 0, 50],
          "options": [{
            "name": "only_recipient",
            "price": 27
          }, {
            "name": "signature",
            "price": 35
          }, {
            "name": "only_recipient_signature",
            "price": 42
          }, {
            "name": "insured",
            "price": 0
          }, {
            "name": "large_format",
            "price": 42
          }, {
            "name": "return",
            "price": 42
          }],
          "insurance": [{
            "amount": 200,
            "price": 0
          }]
        }
      }
    }, {
      "id": 3,
      "carrier_id": 2,
      "active": 1,
      "type": "letterbox",
      "name": "PostNL Letterbox",
      "groups": [{
        "id": 0,
        "weight": {
          "min": 0,
          "max": 20
        }
      }],
      "prices": {
        "NL": {
          "base": [350]
        }
      }
    }, {
      "id": 4,
      "carrier_id": 3,
      "active": 1,
      "type": "parcel",
      "name": "Bpost Parcel",
      "groups": [{
        "id": 0
      }],
      "prices": {
        "NL": {
          "base": [942],
          "insurances": [{
            "amount": 5000,
            "price": 50
          }, {
            "amount": 10000,
            "price": 100
          }, {
            "amount": 50000,
            "price": 168
          }, {
            "amount": 100000,
            "price": 336
          }, {
            "amount": 150000,
            "price": 504
          }, {
            "amount": 200000,
            "price": 672
          }, {
            "amount": 250000,
            "price": 840
          }],
          "options": [
            {
              "name": "insured",
              "price": 0
            }
          ]
        },
        "BE": {
          "base": [442],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }, {
            "name": "saturday",
            "price": 42
          }]
        },
        "GB": {
          "base": [1244],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }]
        }
      }
    }, {
      "id": 5,
      "carrier_id": 4,
      "active": 1,
      "type": "parcel",
      "name": "DPD Parcel",
      "groups": [{
        "id": 0
      }],
      "prices": {
        "NL": {
          "base": [942],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }]
        },
        "GB": {
          "base": [1244],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }]
        }
      }
    }, {
      "id": 6,
      "carrier_id": 5,
      "active": 1,
      "type": "parcel",
      "name": "Hermes Parcel",
      "groups": [{
        "id":
      }],
      "prices": {
        "NL": {
          "base": [942],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }]
        },
        "GB": {
          "base": [1244],
          "insurances": [{
            "amount": 20000,
            "price": 0
          }],
          "options": [{
            "name": "insured",
            "price": 0
          }]
        }
      }
    }],
    "results": 6,
    "page": 1,
    "size": 6
  }
}

12.B.4 Object Definition

This is the CarrierService object.

id
Data type: integer
Required: n/a.

carrier_id
Data type: integer
Required: n/a.

active
Data type: integer
Required: n/a.

type
Data type: string
Required: n/a.

name
Data type: string
Required: n/a.

groups
Data type: CarrierServiceGroups
Required: n/a.

prices
Data type: CarrierServicePrices
Required: n/a.

13. Document changes

Last version update is done on 29-05-2017.