Labels

Labels — Get a shipping label for your deliveries and drop them off at our location. On this page, we'll dive into the different label endpoints you can use to manage shipments programmatically. We'll look at how to query, create and get labels.

The label model

The label model contains all the information about labels, such as their tracking information, prefered shipping method and delivery address.

Properties

Name
trackingCode
Type
string
Description
The unique trackingCode that identifies the label.
This will be returned when creating a label.
Name
orderRef
Type
string
maxLength(35)
Description
Your order reference as given to the receiver, helping them recognizing the shipment as it is received
Name
customerRef
Type
string
Description
Your customerRef reference as given to the receiver, helping them recognizing the shipment as it is received
Name
shipToName
Type
string
maxLength(100)
Description
The name of the recipient
Name
shipToContact
Type
string
maxLength(100)
Description
The contact or second name line for the recipient
Name
shipToAddressLine1
Type
string
maxLength(100)
Description
Address Line 1
Name
shipToAddressLine2
Type
string
maxLength(100)
Description
Address Line 2
Name
shipToPostCode
Type
string
maxLength(20)
Description
The zipcode for the shipTo Address
Name
shipToCity
Type
string
maxLength(30)
Description
The city of the recipient
Name
shipToCountryCode
Type
string
maxLength(2)
Description
The code for the country of the recipient
Name
shippingContactName
Type
string
maxLength(100)
Description
The name of the contact for the shipping, the shipping agent can contact the recipient to plan the shipment or if they are not at home.
Name
shippingContactEmail
Type
string
maxLength(80)
Description
The emailaddress of the contact for the shipping.
Name
shippingContactPhonenumber
Type
string
maxLength(30)
Description
The phonenumber of the contact for the shipping.
Name
shippingContactAddress
Type
string
maxLength(100)
Description
The address of the contact for the shipping. Used by the shipping agent for example to verify ownership when picking up.
Name
shippingContactPostCode
Type
string
maxLength(20)
Description
The zipcode of the contact for the shipping.
Name
shippingContactCity
Type
string
maxLength(30)
Description
The city of the contact for the shipping.
Name
shippingContactCountryCode
Type
string
maxLength(2)
Description
The country code of the contact for the shipping.
Name
shipmentMethodCode
Type
string
Description
Tell us how you what kind of label you want. Valid values can be found in your partner portal under settings/shipping.
Name
status
Type
enum
Description
The status of the label. Valid values: new, cancelled, waiting_for_dropoff, dropped_off, ready
Name
shipmentStatus
Type
enum
Description
The shipmentStatus of the label. Valid values: none, error, new, on_hold, label_printed, manifest, accepted, in_transit, delay, done, automatic_proof_of_delivery, deleted
none - means the shipment is in preparation but not yet booked. new - means the shipment has been booked. label_printed - means the label has been printed. on_hold - means the label has been printed, but the shipment has been put on hold for manifesting/shipping. manifest - means that the shipment has been manifested to the carrier (this status can only be retrieved if the carrier connection is via manifesting). accepted - means that the shipment has been accepted by the carrier error - means that an error has occured which can have multiple causes. in_transit - means the shipment is in transit/transport. done - means the shipment has been delivered. automatic_proof_of_delivery - means Automatic Proof Of Delivery, this status is triggered when we didn't get any status feedback from the carrier for this shipment. deleted - means the shipment has been deleted.
Name
shipmentStatusDescription
Type
string
Description
The detailed description for the shipmentStatus of the label.
Name
shipmentStatusDate
Type
date
Description
The date on wich the shipmentStatus was entered
Name
shipmentDate
Type
date
Description
The date on wich the shipment was shipped
Name
shippingAgent
Type
string
Description
The shipping agent that handled the shipment.
Name
shippingService
Type
string
Description
The code for the service of the shipping agent.
Name
trackingLink
Type
string
Description
The trackingLink for the shipment. Share this with your customer.
Name
pdf
Type
string
Description
Base64 string containing the label in pdf format
Name
zpl
Type
string
Description
Base64 string containing the label in pdf format
Name
packages
Type
array
Description
Array containing the packages for the shipment. In case of multi colli you can have more than one package.

GET/fulfilment/v3/labels?skip=:skip&take=:take&filter=:filter

List your labels

This endpoint allows you to retrieve a list of labels.

Optional arguments

Name
skip
Type
number
Description
How many outbounds to skip
Name
take
Type
number
Description
How many outbounds to return
Name
filter
Type
filter
Description
Consult the filtering guide for more information.
Name
change-interval
Type
integer
Description
Get all records that have changed in the last change-interval minutes. Value between 5 and 2800
Allthough we support polling. We recommend using webhooks. If you are going to poll please use this property to keep traffic manageable.

Request

GET

/fulfilment/v3/labels

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/labels \
  --header "Authorization: Bearer {token}" \

Response

[
  {
    "trackingCode": "3SYSWD0000001",
    "orderRef": "# 1083",
    "customerRef": "# 3920",
    "shipToName": "Bart Smit",
    "shipToContact": "Simone Haring",
    "shipToAddressLine1": "Picassopassage 35",
    "shipToAddressLine2": null,
    "shipToCity": "Emmen",
    "shipToCountryCode": "NL",
    "shipToPostCode": "7811 DN",
    "shippingContactName": "Status 418",
    "shippingContactEmail": "info@status418.nl",
    "shippingContactPhonenumber": "06123456789",
    "shippingContactAddress": "Picassopassage 35",
    "shippingContactPostCode": "7811 DN",
    "shippingContactCity": "Emmen",
    "shippingContactCountryCode": "NL",
    "shipmentMethodCode": "POSTNL-3085-DAP",
    "status": "new",
    "shipmentStatus": "labl",
    "shipmentStatusDescription": null,
    "shipmentStatusDate": "2024-09-30T13:44:16.902Z",
    "shipmentDate": null,
    "shippingAgent": "POSTNL",
    "shippingService": "3085",
    "trackingLink": "http://postnl.nl/tracktrace/?B=3SYSWD0000001&P=1234AA&D=NL&L=NL&T=C",
    "pdf": "JVBERi0xLjcKJ...UlRU9G",
    "zpl": "JVBERi0xLjcKJ..UlRU9G",
    "packages": [
      {
        "LineNo": 1,
        "trackingCode": "3SDEVC9023286"
      },
      ...
    ]
  },
  ...
]

POST/fulfilment/v3/labels?numberOfPackages=:numberOfPackages&format=:format

Create a label

This endpoint allows you to create a label.

As there is some processing time involved we recommend limiting Label creation to 10 labels/minute, to ensure that labels are processed without error.

Required attributes

Name
body
Type
json
Description
json containing the label to create. Refer to the label model at the top of this page to see the properties we support.

Optional arguments

Name
numberOfPackages
Type
number
Description
How many colli are in the shipment. Defaults to 1
Name
format
Type
enum
Description
The format for the label you want returned. Valid values: pdf, zpl. Defaults to pdf

Request

POST

/fulfilment/v3/labels

curl https://partner.punt-uit.nl/api/fulfilment/v3/labels \
  -H "Authorization: Bearer {token}" \
  -d '{
      "orderRef": "# 1083",
      "customerRef": "# 3920",
      "shipToName": "Bart Smit",
      "shipToContact": "Simone Haring",
      "shipToAddressLine1": "Picassopassage 35",
      "shipToCity": "Emmen",
      "shipToPostCode": "7811 DN",
      "shipToCountryCode": "NL",
      "shippingContactName": "Status 418",
      "shippingContactEmail": "info@status418.nl",
      "shippingContactPhonenumber": "06123456789",
      "shippingContactAddress": "Picassopassage 35",
      "shippingContactPostCode": "7811 DN",
      "shippingContactCity": "Emmen",
      "shippingContactCountryCode": "NL",
      "shipmentMethodCode": "POSTNL-3085-DAP",
  }

Response

{
  "trackingCode": "3SYSWD0000001",
  "orderRef": "# 1083",
  "customerRef": "# 3920",
  "shipToName": "Bart Smit",
  "shipToContact": "Simone Haring",
  "shipToAddressLine1": "Picassopassage 35",
  "shipToAddressLine2": null,
  "shipToCity": "Emmen",
  "shipToCountryCode": "NL",
  "shipToPostCode": "7811 DN",
  "shippingContactName": "Status 418",
  "shippingContactEmail": "info@status418.nl",
  "shippingContactPhonenumber": "06123456789",
  "shippingContactAddress": "Picassopassage 35",
  "shippingContactPostCode": "7811 DN",
  "shippingContactCity": "Emmen",
  "shippingContactCountryCode": "NL",
  "shipmentMethodCode": "POSTNL-3085-DAP",
  "status": "waiting_for_dropoff",
  "shipmentStatus": "labl",
  "shipmentStatusDescription": null,
  "shipmentStatusDate": "2024-09-30T13:44:16.902Z",
  "shipmentDate": null,
  "shippingAgent": "POSTNL",
  "shippingService": "3085",
  "trackingLink": "http://postnl.nl/tracktrace/?B=3SYSWD0000001&P=1234AA&D=NL&L=NL&T=C",
  "pdf": "JVBERi0xLjcKJ...UlRU9G",
  
  "packages": [
    {
      "LineNo": 1,
      "trackingCode": "3SDEVC9023286",
      "zpl": "JVBERi0xLjcKJ..UlRU9G",
    },
    ...
  ]
}

GET/fulfilment/v3/labels/:trackingCode?format=:format

Retrieve a label

This endpoint allows you to retrieve a label by providing the trackingCode. Refer to the label model at the top of this page to see which properties are included with label objects.

Required arguments

Name
trackingCode
Type
string
Description
Path parameter representing the trackingCode of the label.

Optional arguments

Name
format
Type
enum
Description
The format for the label you want returned. Valid values: pdf, zpl. Defaults to pdf

Request

GET

/fulfilment/v3/labels/:trackingCode

curl --location https://partner.punt-uit.nl/api/fulfilment/v3/labels/3SDEVC9023119 \
  --header "Authorization: Bearer {token}"

Response

{
"orderRef": "2026",
"customerRef": null,
"shipToName": "Bart Smit",
"shipToContact": "Simone Haring",
"shipToAddressLine1": "Picassopassage 35",
"shipToAddressLine2": null,
"shipToCity": "Emmen",
"shipToCountryCode": "NL",
"shipToPostCode": "7811 DN",
"shippingContactName": "Status 418",
"shippingContactEmail": "info@status418.nl",
"shippingContactPhonenumber": "06123456789",
"shippingContactAddress": "Picassopassage 35",
"shippingContactPostCode": "7811 DN",
"shippingContactCity": "Emmen",
"shippingContactCountryCode": "NL",
"shipmentMethodCode": "POSTNL-3085-DAP",
"status": "waiting_for_dropoff",
"shipmentStatus": "labl",
"shipmentStatusDescription": null,
"shipmentStatusDate": "2024-09-30T13:44:16.902Z",
"shipmentDate": null,
"trackingCode": "3SDEVC9023119",
"shippingAgent": "POSTNL",
"shippingService": "3085",
"trackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9023119&P=7811%20DN&D=NL&T=C",
"pdf": "JVBERi0xL...",

"packages": [
    {
      "LineNo": 1,
      "trackingCode": "3SDEVC9023286",
      "zpl": "JVBERi0xLjcKJ...",
    },
    ...
  ]

DELETE/fulfilment/v3/labels/:trackingCode

Cancel a label

Only labels for shipments that havent been dropped of can be cancelled.

Let us know that you won't be dropping off a shipment.

Required attributes

Name
trackingCode
Type
string
Description
Path parameter representing your trackingCode of the label.

Request

DELETE

/fulfilment/v3/labels/:trackingCode

curl --location --request DELETE https://partner.punt-uit.nl/api/fulfilment/v3/labels/3SDEVC9023119 \
  --header "Authorization: Bearer {token}"