ParcelLabel API

(2 reviews)

Create Label(s) - Domestic

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

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited30 calls per second across all merchants using the API. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

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
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
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 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
pickup_address rules:
country_code (mandatory)
AND:
only one of the following is required:
address_id (highly desirable)
OR
dpid (highly desirable)
OR
site_code (highly desirable)
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.
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.

Size CodeDescription
A4A4 Trackpak
A4BA4 Bubble Trackpak
A5A5 Trackpak
A5BA5 Bubble Trackpak
DLDLE Trackpak
FSFoolscap Trackpak
LFLineFlow Trackpak
CDLEco DLE Trackpak
CA5Eco A5 Trackpak
CFSEco Foolscap Trackpak
XLXtra Large Trackpak

CourierPost Add ons

The following are sample value add-ons.

Add on NameDescription
CPSRCourierPost Signature Required
CPOLRDCourierPost Rural Delivery
CPOLSATCourierPost Online Saturday Delivery
CPOLDGCourierPost Online Dangerous Goods

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.

Prepaid TicketDescription
GreenSaturday delivery
BlackRural delivery (not required when the rural delivery rate is part of contractual arragements with NZ Post)
RedSame day evening delivery
BlueEvening overnight delivery

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

{
  "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": "OUTBOUND",
    "description": "Medium Box",
    "dimensions": {
      "length_cm": 30,
      "width_cm": 30,
      "height_cm": 30,
      "weight_kg": 2
    }
  }]
}

resources/Parcellabel174X100-9fb3d8a6-1b62-475d-bd5b-37bd452a008c.png

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

resources/Parcellabel174X100_Return-774edf6e-42ad-435a-a2aa-d3150f8d7fe8.png

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

resources/Express-75052fab-1683-429d-a4fa-8dddb89d6d45.png

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
}

Reviews