📦 Create a draft shipment

This endpoint allows you to create draft shipments. These shipments will be visible in the API shipments section in your MyParcelParcel account.

If you successfully created the draft shipment, it will look like this:

You can still edit all the information of your draft shipment and decide to book the shipment to get the labels.

Method

In order to create a draft shipment, you need to use the following method:

POST

Endpoint

You need the following endpoint:

https://services.parcelparcel.com/partners-api/v1/shipments

Header

You need to add the following headers:

Name	Value
Content-Type	application/json
X-PP-API	{YourAPIKey}@{YourAPISecret}

Don't you have an API Key and API Secret yet? Check our Authentication page and how to get them in under a minute.

Body

The Request body must contain a JSON structure with the following definition

Name	Value	Required	Comments
reference	(string)	false
currency	(string) EUR \| USD	true
insured	(bool)	true
preferredShippingOption	(number)	false	If you want to create a draft shipment with a specific shipping option, you can set the productId through this element. The productId is acquired from the response when you use our compare shipping options endpoint. If you don't specify this element, we select the cheapest shipping option by default.
schedulePickup	(bool)	true
pickupTimeFrom	(string)	false	For example "12:00"
pickupTimeTo	(string)	false	For example "16:00"
pickupInstructions	(string)	false
reasonForExport	(string) Available options: - commercial - replacement - sample - gift - repair - return - personal_use - personal_effect - intercompany - exhibition	true (if dutiable shipment)
incoterms	(string) DAP \|\| DDP	true (if dutiable shipment)
parcels	(object array) Parcel
contentItems	(object array) ContentItem	true must have at least one item
pickupAddress	(object) Address	true
destinationAddress	(object) Address	true

ContentItem type

Name	Value	Required	Comments
description	(string)	true	The description of an item. Make sure you describe your item well (e.g. 100% cotton white T-shirt Male")
quantity	number	true	The number of pieces you have of this item
price	(float) 2 digits	true	The price per item
country	2-digit ISO code	true	The country where the item is manufactured
hsCode	(string)	false	You can specify an HS code per item

Example:

{  
  "description": "awesome product ",  
  "quantity": "1",  
  "price": "69.00",  
  "country": "NL",
  "hsCode": "61091000"
}

Parcel type

Name	Value	Required	Comments
type	NONDOC	true	You should choose NONDOC if you're shipping a parcel
weight	1 decimal	true	For example "10" or "15.2". This value should be stated in kilograms (kg).
length	integer	true	For example "40". This value should be stated in centimetres (cm).
width	integer	true	For example "30". This value should be stated in centimetres (cm).
height	integer	true	For example "40". This value should be stated in centimetres (cm).
count	integer	true	For example "1"

Example NONDOC (Parcel):

{  
  "type": "NONDOC",  
  "weight": "8.3",  
  "height": "21",  
  "width": "25",  
  "length": "65",  
  "count": "1"  
}

Address type

Name	Value	Required	Comments
countryCode	(string)	true	You should provide the country is ISO-2 format (e.g. NL or US)
companyName	(string)	false
contactPerson	(string)	true
email	(email)	true
phone	(string)	true
addressLine1	(string)	true	We have some logic regarding the addressLine1 and Addressline2 fields. We first concatenate addressline1 with addressline2. Then we split into max allowed chars for address line 1 and put the remaining into address line 2.
addressLine2	(string)	false	We have some logic regarding the addressLine1 and Addressline2 fields. We first concatenate addressline1 with addressline2. Then we split into max allowed chars for address line 1 and put the remaining into address line 2.
zipcode	(string)	true
city	(string)	true
vatNumber	(string)	false	The VAT number is only required for shipments to the US that are to a company and/or if the total value of the shipment is more than €2300.
sendNotification	(bool)	false	This element can only be set for the destinationAddress and sends out a notification email from ParcelParcel to the recipient email whenever the shipment is in transit. You can read more about this functionality on this page. This email contains also the Track & Trace number and a tracking link. If you don't set this element, the default value is false.

Example:

{
  "countryCode": "FR",
  "companyName": "My Company",
  "contactPerson": "John Doe",
  "email": "[email protected]",
  "phone": "+31855871656",
  "addressLine1": "street Name and numer for instance",
  "addressLine2": "Extra details",
  "zipcode": "75001",
  "city": "Paris",
  "vatNumber": "0000"
}

Examples

Below, we have created multiple examples so that you are up and running ASAP. Don't know how to test these requests? Check our guide.

Request example - Parcel shipment from the Netherlands to France

curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/shipments' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
 
    "parcels": [
        {
            "type": "NONDOC",
            "weight": "20",
            "height": "10",
            "width": "74",
            "length": "84",
            "count": "1"
        }
    ],
    "contentItems": [
        {
            "description": "This is a description of an content item",
            "quantity": "1",
            "price": "1600.00",
            "country": "NL"
        },
          {
            "description": "This is a description of an content item",
            "quantity": "1",
            "price": "1600.00",
            "country": "NL",
            "hsCode": "61091000"
        }
        
        
        
    ],
    "reasonForExport": "commercial",
    "reference": "#123126",
    "currency": "EUR",
    "incoterms": "DAP",
    
     "pickupAddress": {
            "countryCode": "NL",
        "companyName": "ParcelParcel",
        "contactPerson": "John Doe",
        "email": "[email protected]",
        "phone": "+31858771656",
        "addressLine1": "Energiestraat 14E",
        "addressLine2": "Extra details-",
        "zipcode": "1411 AT",
        "city": "Naarden"
    },
    "destinationAddress": {
         "countryCode": "FR",
        "companyName": "Company x",
        "contactPerson": "John Croissant",
        "email": "[email protected]",
        "phone": "+5218112278399",
        "addressLine1": "Rue de Baquette 34",
        "addressLine2": "Dans la rue",
        "zipcode": "75001",
        "vatNumber": "0000",
        "city": "Paris"
    },
    "schedulePickup": 1,
    "pickupTimeFrom": "12:00",
    "pickupTimeTo": "16:00",
    "pickupInstructions": "Ring the bell",
    "insured": 0
}'

POST /partners-api/v1/shipments HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

{
 
    "parcels": [
        {
            "type": "NONDOC",
            "weight": "20",
            "height": "10",
            "width": "74",
            "length": "84",
            "count": "1"
        }
    ],
    "contentItems": [
        {
            "description": "This is a description of an content item",
            "quantity": "1",
            "price": "1600.00",
             "country": "NL"
        },
          {
            "description": "This is a description of an content item",
            "quantity": "1",
            "price": "1600.00",
            "country": "NL",
            "hsCode": "61091000"
        }
        
        
        
    ],
    "reasonForExport": "commercial",
    "reference": "#123126",
    "currency": "EUR",
    "incoterms": "DAP",
     "pickupAddress": {
            "countryCode": "NL",
        "companyName": "ParcelParcel",
        "contactPerson": "John Doe",
        "email": "[email protected]",
        "phone": "+31858771656",
        "addressLine1": "Energiestraat 14E",
        "addressLine2": "Extra details-",
        "zipcode": "1411 AT",
        "city": "Naarden"
    },
    "destinationAddress": {
         "countryCode": "FR",
        "companyName": "Company x",
        "contactPerson": "John Croissant",
        "email": "[email protected]",
        "phone": "+5218112278399",
        "addressLine1": "Rue de Baquette 34",
        "addressLine2": "Dans la rue",
        "zipcode": "75001",
        "vatNumber": "0000",
        "city": "Paris"
    },
    "schedulePickup": 1,
    "pickupTimeFrom": "12:00",
    "pickupTimeTo": "16:00",
    "pickupInstructions": "Ring the bell",
    "insured": 0
}

Don't forget to change the X-PP-API element in the header in order for this request to work. Don't know where to get your API Key and API Secret? Check our Authentication page and how to get them in under a minute.

Response example - Parcel shipment from the Netherlands to France

{
    "errors": false,
    "message": "Your draft shipment is successfully created in your API shipments section",
    "data": {
        "id": 1
    }
}

Request example - Parcel shipment from the Netherlands to the United States

curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/shipments' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "parcels": [
        {
            "type": "NONDOC",
            "weight": "9.6",
            "height": "10",
            "width": "74",
            "length": "84",
            "count": "1"
        }
    ],
    "contentItems": [
        {
            "description": "Awesome Product",
            "quantity": "1",
            "price": "69.00",
            "hsCode": "61091000",
            "country": "NL"
        }
    ],
    "reasonForExport": "commercial",
    "reference": "#123126",
    "currency": "EUR",
    "incoterms": "DAP",
    "pickupAddress": {
        "countryCode": "NL",
        "companyName": "CompanyOne",
        "contactPerson": "John Doe 1",
        "email": "[email protected]",
        "phone": "+31858771656",
        "addressLine1": "street Name ...",
        "addressLine2": "extra details",
        "zipcode": "3542 AB",
        "city": "Utrecht"
    },
    "destinationAddress": {
        "countryCode": "US",
        "companyName": "CompanyTwo",
        "contactPerson": "John Doe",
        "email": "[email protected]",
        "phone": "+31858771656",
        "addressLine1": "street Name ...",
        "addressLine2": "Dover market",
        "zipcode": "10001",
          "vatNumber": "0000",
        "city": "New York"
    },
    "schedulePickup": 1,
    "pickupTimeFrom": "12:00",
    "pickupTimeTo": "16:00",
    "pickupInstructions": "Ring the bell",
    "insured": 0
}'

POST /partners-api/v1/shipments HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

{
    "parcels": [
        {
            "type": "NONDOC",
            "weight": "9.6",
            "height": "10",
            "width": "74",
            "length": "84",
            "count": "1"
        }
    ],
    "contentItems": [
        {
            "description": "Awesome Product",
            "quantity": "1",
            "price": "69.00",
            "hsCode": "61091000",
            "country": "NL"
        }
    ],
    "reasonForExport": "commercial",
    "reference": "#123126",
    "currency": "EUR",
    "incoterms": "DAP",
    "pickupAddress": {
        "countryCode": "NL",
        "companyName": "CompanyOne",
        "contactPerson": "John Doe 1",
        "email": "[email protected]",
        "phone": "+31858771656",
        "addressLine1": "street Name ...",
        "addressLine2": "extra details",
        "zipcode": "3542 AB",
        "city": "Utrecht"
    },
    "destinationAddress": {
        "countryCode": "US",
        "companyName": "CompanyTwo",
        "contactPerson": "John Doe",
        "email": "[email protected]",
        "phone": "+52....",
        "addressLine1": "street Name ...",
        "addressLine2": "Dover market",
        "zipcode": "10001",
          "vatNumber": "0000",
        "city": "New York"
    },
    "schedulePickup": 1,
     "pickupTimeFrom": "12:00",
     "pickupTimeTo": "16:00",
    "pickupInstructions": "Ring the bell",
    "insured": 0
}

Response example - Parcel shipment from the Netherlands to the United States

{
    "errors": false,
    "message": "Your draft shipment is successfully created in your API shipments section",
    "data": {
        "id": 1
    }
}