ParcelLabel API

Resource URL

UAT:

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

Production:

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

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 consignment.

The request is considered international if the pickup or delivery address is not New Zealand.

Request Parameters

Field Name	Description	Required	Notes
format	Format of the label. Value must be PDF or PNG. Default Value is PDF.	No	No
notification_endpoint	Merchants Webhook URL to receive notification when the label has been generated.	No	No
delivery_choice_type	Additional service requested for the delivery. Value is a string and must be either 1 or 2.	No	No
sender_reference_1	Sender's reference for the consignment. Will not be printed on the label.	No	No
sender_reference_2	Sender's reference. Will not be printed on the label.	No	No
sender_details	An object containing the sender contact details. See Sender Details Object Parameters below.	Yes	No
sender_details.name	Name of the sender.	Yes	Both firstname and surname should be included
sender_details.phone	Phone number of the sender	Yes	NO SPACES, DIGITS and '+' ONLY
sender_details.email	Email address of the sender.	No but highly desirable	No
sender_details.fax	Contact fax number of the sender	No	No
sender_details.signatory	Name of the individual sending the parcel, this is used for Customs purposes.	No	No
sender_details.customs_code	OverseasTax Code	No	For example: IOSS Number (EU),EORI number (UK), ABN/ABR(Australia)
receiver_details	An object containing the receiver contact details. See Receiver Details Object Parameters below.	Yes	No
receiver_details.name	Name of the receiver.	Yes	For International sending this must be both first and surname.
receiver_details.phone	Contact phone number of the receiver.	No but highly desirable	NO SPACES, DIGITS and '+' ONLY
receiver_details.email	Email address of the receiver.	No but highly desirable	No
receiver_details.fax	Fax number of the person to receiver.	No	No
receiver_details.vat_number	The VAT or GST number of the receiver. For international labels, the field should not be > 14 characters.	No	No
receiver_details.registration_number	Registration number of the receiver required for Delivery Location Options.	No	No
pickup_address	An object containing the sender pickup address details. See Pickup Address parameters below	Yes	No
pickup_address.company_name	Company name of the pickup address	No	No
pickup_address.building_name	Building name of the pickup address.	No	No
pickup_address.street_number	Street number of the pickup address.	No but highly desirable	No
pickup_address.street	Street name of the pickup address.	Yes	No
pickup_address.suburb	Suburb of the pickup address	No but highly desirable	No
pickup_address.city	City of the pickup address	Yes	No
pickup_address.state	Regional, provincial or county name of the pickup address.	No but highly desirable	No
pickup_address.locality_code	Country subdivision code identifier that the pickup address belongs to.	No	No
pickup_address.country_code	Two character country code of the pickup address.	Yes	No
pickup_address.postcode	Postal or zip code of the pickup address.	Yes	No
delivery_address	An object containing the receiver delivery address details. See Receiver Address Object Parameters section	Yes	No
delivery_address.location_type	Type of the delivery requested for the item. Value must be from UPU code list 199.	No	No
delivery_address.building_name	Building name of the delivery address.	No	No
delivery_address.company_name	Name of company that the parcel is being delivered to.	No	No
delivery_address.street_number	Street number of the delivery address.	No but highly desirable	No
delivery_address.street	Street name of the delivery address.	Yes	No
delivery_address.suburb	Suburb of the delivery address	No but highly desirable	No
delivery_address.city	City of the delivery address	Yes	No
delivery_address.state	State name of the delivery address	Yes	No
delivery_address.locality_code	Country subdivision code identifier that the delivery address belongs to.	No	No
delivery_address.country_code	Two character ISO country code of the delivery address. For domestic labels, this must be set to NZ.	Yes	No
delivery_address.postcode	Postal or zip code of the delivery address.	Yes	No
delivery_address.instructions	Delivery instructions	No	No
return_address	An object containing the return address details. See Return Address parameters below	Yes	Mandatory for ETOE services
return_address.company_name	Company name of the return address	No	No
return_address.building_name	Building name of the return address.	No	No
return_address.street_number	Street number of the return address.	No but highly desirable	No
return_address.street	Street name of the return address.	Yes	No
return_address.suburb	Suburb of the return address	No but highly desirable	No
return_address.city	City of the return address	Yes	No
return_address.state	Regional, provincial or county name of the return address.	No but highly desirable	No
return_address.locality_code	Country subdivision code identifier that the return address belongs to.	No	No
return_address.country_code	Two character country code of the return address.	Yes	Must be NZ for ETOE services
return_address.postcode	Postal or zip code of the return address.	Yes	No
parcel_details	An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section	Yes	No
parcel_details.service_code	Code to represent a delivery service.	Yes	No
parcel_details.receiver_charging_arrangement	Duty and tax payment method as it applies to the item. Value must be DDP (Delivery Duty Paid) OR DDU (Delivery Duty Unpaid)	No	No
parcel_details.undeliverable_instructions	Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY.	Yes	No
parcel_details.indicia_number	Your indicia (PermitPost or DirectPost) number	Yes	No
parcel_details.insurance_required	Whether additional cover is required for the parcel. Value must be either TRUE or FALSE	Yes	No
parcel_details.nature_of_transaction_code	Category of goods that appears on the CN23 form. Value depends on the nature of the items.	Yes	Must be one of: 11=Sale of goods; 21=Returned Goods; 31=Gift; 32=Commercial Sample; 91=Documents; 999=Other
parcel_details.postage_paid_amount	Monetary value of postage that sender has paid. Value must be greater than $0.00.	Yes	No
parcel_details.additional_fee_amount	Monetary value of other fees that sender has paid. E.g. additional insurance	No	No
parcel_details.insured_value_amount	Monetary value the parcels are covered for.	No	No
parcel_details.currency	Currency code for the parcel	Yes	No
parcel_details.dimensions	An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section.	Yes	No
parcel_details.dimensions.length_cm	Length of the parcel.	Yes	No
parcel_details.dimensions.width_cm	Width of the parcel.	Yes	Not required for tubes.
parcel_details.dimensions.height_cm	Height of the parcel.	Yes	Not required for tubes.
parparcel_details.dimensions.diameter_cm	Diameter of the parcel.	No	Mandatory for tubes.
parcel_details.dangerous_goods	An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section.	No	No
parcel_details.dangerous_goods.hazard_class	Classification of dangerous items in the parcel. Value must be from Hazard Identification Code.	No	http://www.ilo.org/legacy/english/protection /safework/cis/products/safetytm/tranann5.htm
parcel_details.dangerous_goods.type_code	United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits.	No	No
parcel_details.parcel_contents	An array containing content details of a parcel.	Yes	No
parcel_details.parcel_contents.content_number	Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive.	Yes	No
parcel_details.parcel_contents.description	Description of the parcel contents.	Yes	HS Tariff and TARIC codes are numeric only and restricted to 6, 8, 10 or 12 numbers in length (excluding permitted special characters).
parcel_details.parcel_contents.harmonised_system_tariff	Internationally standardised name and number of the classification of the parcel content.	No	It is strongly recommended to remove all non-numeric characters, however use of ‘.’, or ‘ ‘ [space] is permitted between HS Tariff groupings. Examples: 1234567890 (preferred) 1234.56.78.90 (acceptable) 1234-56-78-90 (invalid characters) 1234.56.7 (invalid field length (7 numbers))
parcel_details.parcel_contents.quantity	Quantity of units in the parcel.	Yes	No
parcel_details.parcel_contents.weight_kg	Weight of each individual unit in the parcel (kgs).	Yes	No
parcel_details.parcel_contents.value	Dollar value of each individual unit in the parcel.	Yes	No
parcel_details.parcel_contents.country_code	ISO Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters.	No	No
parcel_details.accompanying_documents	An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section	No	No
parcel_details.accompanying_documents.type	Code must be one of an allowed subset of codes.	No	Value must be one of LIC, 811 or 911
parcel_details.accompanying_documents.identifier	Value entered on the CN23 license box.	No	No

Sample Request

{
  "carrier": "PARCELPOST",
  "orientation": "LANDSCAPE",
  "format": "PDF",
  "sender_reference_1": "reference_1",
  "sender_reference_2": "reference_2",
  "paper_dimensions": {
    "width_cm": 21.0,
    "height_cm": 29.7,
    "stationery_size": "A4"
  },
  "sender_details": {
    "name": "Sender Name",
    "phone": "+6490000001",
    "email": "sender@example.co.nz",
    "company_name": "Test Sender Company",
    "site_code": 96306
  },
  "pickup_address": {
    "company_name": "Test Pickup Address Company",
    "building_name": "Test Pickup Address Building",
    "unit_type": "Unit",
    "unit_value": "2",
    "floor": "Floor 5",
    "street": "151 Victoria Street West",
    "suburb": "Auckland Central",
    "city": "Auckland",
    "country_code": "NZ",
    "postcode": "1010"
  },
  "receiver_details": {
    "name": "Receiver Name",
    "phone": "6490000002",
    "email": "receiver@example.co.nz"
  },
  "delivery_address": {
      "street": "20 George St",
      "suburb": "",
      "city": "Liverpool",
      "state": "NSW",
      "country_code": "AU",
      "postcode": "2170"
  },
  "return_address": {
    "company_name": "Test Return Address Company",
    "building_name": "Test Return Address Building",
    "unit_type": "Unit",
    "unit_value": "2",
    "floor": "Floor 5",
    "street": "151 Victoria Street West",
    "suburb": "Auckland Central",
    "city": "Auckland",
    "country_code": "NZ",
    "postcode": "1010"
  },
   "parcel_details": [
      {
         "service_code": "TIEC",
         "undeliverable_instructions": "RETURN",
         "indicia_number": "200003",
         "insurance_required": false,
         "nature_of_transaction_code": "91",
         "postage_paid_amount": 0.01,
         "currency": "NZD",
         "dimensions": {
            "length_cm": 30,
            "width_cm": 30,
            "height_cm": 30,
            "weight_kg": 1
         },
         "parcel_contents": [
            {
               "content_number": 1,
               "description": "Package Desc",
               "quantity": 1,
               "weight_kg": 1,
               "value": 1
            }
         ]
      }
   ]
}

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