ParcelLabel API

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

Resource Description

Request for creating labels which are to be delivered within New Zealand. These labels are returned in either a PDF or PNG format.

Resource Information

Request Parameters

A unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a domestic consignment.

All fields that are not applicable to the request will not be validated and will be ignored.

If the pickup and delivery country_codes are both NZ then the request is considered to be for a domestic label. Else, the request is considered to be for an international label.

Please note that all request and response parameter Field Names must be in lower case.

Field Name	Description	Required
carrier	Carrier of the parcel. Value must be one of COURIERPOST OR PACE	Yes
orientation	Print orientation of the label. Value must be PORTRAIT or LANDSCAPE. Default value is LANDSCAPE.	No
logo_id	Unique identifier for merchants logo. The field is only relevant for COURIERPOST and PACE	No
notification_endpoint	Merchants Webhook URL to receive notification when the label has been generated. See Webhook Usage below.	No
sender_reference_1	Sender's reference for the consignment. Will be printed on the label.	No
sender_reference_2	Sender's reference (e.g. cost centre number for CP manifesting). Will not be printed on the label.	No
account_number	Your NZ Post Billing Account number (9 or 5 series).This is highly recommended to pass in the API call to obtain your account rates.	No
despatch_date	Required field for CPOLPSED service - notifies of date that the parcel should be picked up and delivered. Format is DD/MM/YY	No
job_number	Pace Job Booking Number. Used to generate the tracking number for the label. This field is only relevant for PACE.	Yes if carrier is PACE
label_dimensions	An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or empty string. If it is empty then default value is 174x100. This field is only mandatory to generate 150x100 dimensions label.	No
paper_dimensions	An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters section.	No
paper_dimensions.width_cm	Width the label to be printed to. Default value is 17.4. Note: To print on a 150x100 label this value must be set to ‘15.0’	No
paper_dimensions.height_cm	Height of the label to be printed to. Default value is 10	No
paper_dimensions.stationery_size	Paper size upon which to print the label. Must be A4 or A5.	No
sender_details	An object containing the sender contact details. See Sender Details Object Parameters below.	Yes
sender_details.name	Name of the sender.	Yes
sender_details.phone	Phone number of the sender. NO SPACES, DIGITS ONLY	No but highly desirable
sender_details.site_code	Site code assigned to the address where the parcel will be picked up by the courier. This address is also used for the NZ Post manifest process.	Yes
sender_details.company_name	Company name of the sender.	No
sender_details.email	Email address of the sender.	No
sender_details.freepost_number	FreePost number of the sender. This field is for ParcelPost Domestic Return labels.	No
receiver_details	An object containing the receiver contact details. See Receiver Details Object Parameters below.	Yes
receiver_details.name	Name of the receiver.	Yes
receiver_details.phone	Contact phone number of the receiver. NO SPACES, DIGITS ONLY	No but highly desirable
receiver_details.email	Email address of the receiver.	No but highly desirable
pickup_address	An object containing the sender pickup address details. See Pickup Address parameters below	Yes
Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
pickup_address.address_id	Address ID for the pickup address sourced from the ParcelAddress API.	See pickup_address rules
pickup_address.dpid	Delivery Point ID for the pickup address sourced from the ParcelAddress API.	See pickup_address rules
pickup_address.site_code	Site code of the pickup address.	See pickup_address rules
pickup_address.street	Street name of the pickup address.	See pickup_address rules
pickup_address.suburb	Suburb of the pickup address	See pickup_address rules
pickup_address.city	City of the pickup address	See pickup_address rules
pickup_address.postcode	Postal or zip code of the pickup address.	See pickup_address rules
pickup_address.unit_type	Type of unit (if applicable) of the pickup address.	No
pickup_address.unit_value	Value of the unit type.	Yes if pickup_address.unit_type is not blank
pickup_address.floor	Floor of the pickup address.	No
pickup_address.country_code	Two character country code of the pickup address. For domestic labels, this must be set to NZ.	Yes
pickup_address.company_name	Company name of the pickup address	No
pickup_address.building_name	Building name of the pickup address.	No
pickup_address.lobby_location	An object containing PO Box or Private Bag details of the parcel to be returned to. This object is for ParcelPost Domestic Return labels only. See Pickup Address - Lobby Location Object Parameters.	No
pickup_address.lobby_location.type	Location type of the return address. Value must be one of: POBOX, PRIVATEBAG.	Yes
pickup_address.lobby_location.number	Private Bag number or the PO Box number of the parcel to be returned to. This field is for ParcelPost Domestic Return labels.	Yes
pickup_address.lobby_location.city	City of the return address	Yes
pickup_address.lobby_location.postcode	Postcode of the return address	Yes
pickup_address.lobby_location.name	Name of the recipient.	No
pickup_address.lobby_location.lobby	Lobby name of the return address.	No
delivery_address	An object containing the receiver delivery address details. See Delivery Address Object Parameters below.	Yes
delivery_address rules: country_code (mandatory) AND: only one of the following is required: address_id (highly desirable) OR dpid (highly desirable) OR site_code OR street, suburb, city, and postcode. Use the city for addresses without suburbs.	Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
delivery_address.address_id	Address ID for the delivery address sourced from the ParcelAddress API.	See delivery_address rules
delivery_address.dpid	Numeric Delivery Point Identifier for the delivery sourced from the ParcelAddress API.	See delivery_address rules
delivery_address.site_code	Site code of the pickup address.	See delivery_address rules
delivery_address.street	Street name of the pickup address.	See delivery_address rules
delivery_address.suburb	Suburb of the pickup address	See delivery_address rules
delivery_address.city	City of the pickup address	See delivery_address rules
delivery_address.postcode	Postal or zip code of the pickup address.	See delivery_address rules
delivery_address.unit_type	Type of unit (if applicable) of the pickup address.	No
delivery_address.unit_value	Value of the unit type.	Yes if delivery_address.unit_type is not blank
delivery_address.floor	Floor of the pickup address.	No
delivery_address.country_code	Two character country code of the pickup address. For domestic labels, this must be set to NZ.	Yes
delivery_address.company_name	Name of company that the parcel is being delivered to.	No
delivery_address.building_name	Building name of the delivery address.	No
delivery_address.instructions	Delivery instructions for courier	No
delivery_address.is_collection	Whether the delivery address is a NZ Post collection point. Default value is false.	No
parcel_details	An array containing the label details for each label in the consignment. See Parcel Details Object Parameters section	Yes
parcel_details.service_code	Code to represent a delivery service. For international labels, this is the NetDespatch service code. For domestic labels where carrier is COURIERPOST and the parcel is a Trackpak, see rules in the Envelope Sizes section.	Yes
parcel_details.add_ons	Array of ancillary codes. This field is only relevant for COURIERPOST. Valid addons are: CPSR, CPOLRD, CPOLOED, CPOLSED, CPOLSAT, CPOLDG. Please refer to the Add ons section below for further details.	No
parcel_details.return_indicator	Indications if the label is used for returning items. Values must be OUTBOUND or RETURN. This field is only relevant for COURIERPOST.	Yes if carrier is COURIERPOST
parcel_details.description	The box size name on the label for the dispatching person to choose the correct box for packing. This value is relevant only for PACE and COURIERPOST.	No
parcel_details.dimensions	An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section.	Yes
parcel_details.dimension rules: for courierpost/pace labels that aren't courierpost trackpaks only one of the following is required: length_cm, width_cm, and height_cm OR length_cm and diameter_cm OR volume_m3 (highly desirable - only an option if carrier is Courierpost)
parcel_details.dimensions.length_cm	Length of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.width_cm	Width of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.height_cm	Height of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.diameter_cm	Diameter of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.volume_m3	Volume of the parcel.	See parcel_details.dimension rules
parcel_details.dimensions.weight_kg	Physical weight of the parcel in kilograms.	Yes if not a COURIERPOST Trackpak

Envelope Sizes

Where the parcel is a TrackPak, and the service code has not been selected via the ShippingOptions API, then the envelope size must be concatenated to the end of the service code before submitting the label request.

Below is a list of valid Trackpak envelope sizes.

CourierPost Add ons

The following are sample value add-ons.

CourierPost Add-on Rules

The following rules apply to add-on services included in a label request:

1. Add-on services can only be present when the carrier is CourierPost
2. Only one of the following can be present on the label request: CPOLRD CourierPost Rural Delivery CPOLOED CourierPost Online Overnight Evening Delivery CPOLSAT CourierPost Online Saturday Delivery CPOLDG CourierPost Online Dangerous Goods
3. Signature required, CPSR, may always be present

Merchants must ensure that when appropriate, the prepaid ticket corresponding to the requested add-on service is affixed to the parcel.

**Please test these samples in the UAT environment only. Contact your NZ Post account manager to receive an account number (TPID) and a site_code to test. If testing is executed in the production environment, there is a risk that it may incur charges.**

Sample Request - Overnight CourierPost Outbound label for a single parcel (174x100mm)

(An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or an empty string. If it is empty then the default value is 174x100. This field is only mandatory to generate a 150x100 dimensions label.)

{
  "carrier": "COURIERPOST",
  "sender_reference_1": "Order Number 56452",
  "sender_reference_2": "Sales",
  "account_number": "99999999",
  "sender_details": {
  "company_name": "XYZ Widget Company",
  "name": "Bob",
  "phone": "+6425555916",
  "site_code": 96306,
  "email": "bob@xyzwidgets.com"
  },
  "receiver_details": {
    "name": "Alice",
    "phone": "+6424555105",
    "email": "example@example.co.nz"
  },
  "pickup_address": {
    "street": "107 Ransom Smyth Drive",
    "suburb": "Goodwood Heights",
    "city": "Auckland",
    "postcode": "2105",
    "country_code": "NZ"
  },
  "delivery_address": {
    "street": "105 Woodberry Drive",
    "suburb": "Flat Bush",
    "city": "Auckland",
    "postcode": "2016",
    "country_code": "NZ"
  },
  "parcel_details": [{
    "service_code": "CPOLP",
    "add_ons": [],
    "return_indicator": "OUTBOUND",
    "description": "Medium Box",
    "dimensions": {
      "length_cm": 30,
      "width_cm": 30,
      "height_cm": 30,
      "weight_kg": 2
    }
  }]
}

Sample Request - Overnight CourierPost Return label for a single parcel (174X100mm)

Note: The only difference to the above is the return indicator. The Parcel is now sent from Woodberry Drive to Ransom Smyth.

{
  "carrier": "COURIERPOST",
  "sender_reference_1": "Order Number 56452",
  "sender_reference_2": "Sales",
  "sender_details": {
    "company_name": "XYZ Widget Company",
    "name": "Bob",
    "phone": "+6425555916",
    "site_code": 96306,
    "email": "bob@xyzwidgets.com"
  },
  "receiver_details": {
    "name": "Alice",
    "phone": "+6424555105",
    "email": "example@example.co.nz"
  },
  "pickup_address": {
    "street": "107 Ransom Smyth Drive",
    "suburb": "Goodwood Heights",
    "city": "Auckland",
    "postcode": "2105",
    "country_code": "NZ"
  },
  "delivery_address": {
    "street": "105 Woodberry Drive",
    "suburb": "Flat Bush",
    "city": "Auckland",
    "postcode": "2016",
    "country_code": "NZ"
  },
  "parcel_details": [{
    "service_code": "CPOLP",
    "add_ons": [],
    "return_indicator": "RETURN",
    "description": "Medium Box",
    "dimensions": {
      "length_cm": 30,
      "width_cm": 30,
      "height_cm": 30,
      "weight_kg": 2
    }
  }]
}

Sample Request - 3HRA PACE Label for a single parcel

{
  "carrier": "PACE",
  "sender_reference_1": "Order Number 56452",
  "sender_reference_2": "Sales",
  "job_number": 567862,
  "sender_details": {
    "company_name": "XYZ Widget Company",
    "name": "Bob",
    "phone": "+6425555916",
    "site_code": 96306,
    "email": "bob@xyzwidgets.com"
  },
  "receiver_details": {
    "name": "Alice",
    "phone": "+6424555105",
    "email": "example@example.co.nz"
  },
  "pickup_address": {
    "street": "107 Ransom Smyth Drive",
    "suburb": "Goodwood Heights",
    "city": "Auckland",
    "postcode": "2105",
    "country_code": "NZ"
  },
  "delivery_address": {
    "building": "Acme Building",
    "street": "105 Kerwyn Avenue",
    "suburb": "East Tamaki",
    "city": "Auckland",
    "postcode": "2013",
    "country_code": "NZ",
    "instructions": "Ask for John Smith at the reception."
  },
  "parcel_details": [
    {
      "service_code": "3HRA",
      "return_indicator": "OUTBOUND",
      "dimensions": {
        "length_cm": 50,
        "width_cm": 50,
        "height_cm": 50,
        "weight_kg": 2
      }
    }
  ]
}

Sample Request - 150x100mm label - Overnight CourierPost Outbound label for a single parcel

(An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or an empty string. If it is empty then the default value is 174x100. This field is only mandatory to generate a 150x100 dimensions label.)

{
  "carrier": "COURIERPOST",
  "sender_reference_1": "Order Number 56452",
  "sender_reference_2": "Sales",
  "label_dimensions" : "150x100",
  "paper_dimensions" : {
        "width_cm" : 15.0,
        "height_cm" : 10.0
  },
  "sender_details": {
    "company_name": "XYZ Widget Company",
    "name": "Bob",
    "phone": "+6425555916",
    "site_code": 96306,
    "email": "bob@xyzwidgets.com"
  },
  "receiver_details": {
    "name": "Alice",
    "phone": "+6424555105",
    "email": "example@example.co.nz"
  },
  "pickup_address": {
    "street": "107 Ransom Smyth Drive",
    "suburb": "Goodwood Heights",
    "city": "Auckland",
    "postcode": "2105",
    "country_code": "NZ"
  },
  "delivery_address": {
    "street": "105 Woodberry Drive",
    "suburb": "Flat Bush",
    "city": "Auckland",
    "postcode": "2016",
    "country_code": "NZ"
  },
  "parcel_details": [{
    "service_code": "CPOLP",
    "add_ons": [],
    "return_indicator": "OUTBOUND",
    "description": "Medium Box",
    "dimensions": {
      "length_cm": 30,
      "width_cm": 30,
      "height_cm": 30,
      "weight_kg": 2
    }
  }]
}

Response Parameters

Field Name	Description	Mandatory
consignment_id	Unique identifier for the consignment if the request is successful.	Yes
message_id	A unique ID for the API call	Yes
success	Returns true if request is successful. Returns false if request is not successful.	Yes

Sample Response

{
  "consignment_id": "S3BGUH",
  "message_id": "bb590940-97b5-11e9-813b-02168927813a",
  "success": true
}