ParcelLabel API
Create Label(s) - International Outbound from NZ
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parcellabel/v3/labelsProduction:
https://api.nzpost.co.nz/parcellabel/v3/labelsA unique consignment_id is returned once the details of the request are stored in the labelling database. One or multiple labels can be generated within a consignment Only a few [service codes][1] accept requests for multiple parcels.
The request is considered international outbound if the pickup address is in New Zealand and the delivery address is not New Zealand.
The service codes for the reverse journey may have the delivery address in New Zealand.
Request Parameters
| Field Name | Description | Level of requirement | Notes on API validation rule | Notes on sending rules |
| format | Format of the label. | Not required | Value must be PDF or PNG. Default Value is PDF. | |
| notification_endpoint | Merchants Webhook URL to receive notification when the label has been generated. | Not required | ||
| delivery_choice_type | Additional service requested for the delivery. Value is a string and must be either 1 or 2. | Not required | ||
| sender_reference_1 | Sender's reference. Will be printed on the label and invoices for some services. | Recommended | ||
| sender_reference_2 | Sender's reference. Will not be printed on the label and invoices for some services. | Recommended | ||
| sender_details | An object containing the sender contact details. See Sender Details Object Parameters below. | Required | ||
| sender_details.name | Name of the sender. | Required | Both first name and surname should be included for customs clearance at destinations. | |
| sender_details.phone | Contact phone number of the sender. | Required if, otherwise highly recommended | NO SPACES, DIGITS and '+' ONLY | Required - If Express International services are used. |
| sender_details.email | Email address of the sender. | Recommended | ||
| sender_details.fax | Contact fax number of the sender. | Not required | ||
| sender_details.signatory | Name of the individual sending the parcel, this is used for customs purposes. | Recommended | This is used for customs purposes. | |
| sender_details.customs_code | Identification number assigned by overseas tax authorities. | Not required | For example: IOSS Number (EU),EORI number (UK and EU),ABN/ABR(Australia). | |
| receiver_details | An object containing the receiver contact details. See Receiver Details Object Parameters below. | Required | ||
| receiver_details.name | Name of the receiver. | Required | Both first name and surname should be included for customs clearance at destinations. | |
| receiver_details.phone | Contact phone number of the sender. | Required If or highly recommended | NO SPACES, DIGITS and '+' ONLY | Required - If Express International services are used. |
| receiver_details.email | Email address of the receiver. | Recommended | ||
| receiver_details.fax | Fax number of the person to receiver. | Not required | ||
| receiver_details.vat_number | The VAT or GST number of the receiver. | Required if | Maximum length of the field is 14 characters. | Required - If the parcels are sent: - to Brazil - to India and - Jordan via Express International services |
| pickup_address | An object containing the sender pickup address details. See Pickup Address parameters below: | Required | ||
| pickup_address.company_name | Company name of the pickup address. | Recommended if applicable | ||
| pickup_address.building_name | Building name of the pickup address. | Recommended if applicable | ||
| pickup_address.street_number | Street number of the pickup address. | Recommended if applicable | ||
| pickup_address.street | Street name of the pickup address. | Required | ||
| pickup_address.suburb | Suburb of the pickup address. | Required if | Some destination countries use suburb for delivery. | |
| pickup_address.city | City of the pickup address. | Required | ||
| pickup_address.state | Regional, provincial or county name of the pickup address. | Not required | ||
| pickup_address.locality_code | Country subdivision code identifier that the pickup address belongs to. | Not required | ||
| pickup_address.country_code | Two character country code of the pickup address. | Required | ||
| pickup_address.postcode | Postal or zip code of the pickup address. | Required If | Postcodes of some destinations are validated. | |
| delivery_address | An object containing the receiver delivery address details. See Receiver Address Object Parameters section. | Required | ||
| delivery_address.location_type | Type of the delivery requested for the item. Value must be from UPU code list 199. | Not required | ||
| delivery_address.building_name | Building name of the delivery address. | Recommended if applicable | ||
| delivery_address.company_name | Name of company that the parcel is being delivered to. | Recommended if applicable | ||
| delivery_address.street_number | Street number of the delivery address. | Required | ||
| delivery_address.street | Street name of the delivery address. | Required | ||
| delivery_address.suburb | Suburb of the delivery address | Required | If the destinations use suburb for delivery. | |
| delivery_address.city | City of the delivery address. | Required | ||
| delivery_address.state | State name of the delivery address. | Required If | If the destinations use state for delivery. | |
| delivery_address.locality_code | Country subdivision code identifier that the delivery address belongs to. | Recommended if applicable | ||
| delivery_address.country_code | Two character ISO country code of the delivery address. For domestic labels, this must be set to NZ. | Required | delivery_address.postcode | Postal or zip code of the delivery address. | Required If | Required - If the destination has a postcode system. |
| delivery_address.instructions | Delivery instructions. | Not required | ||
| parcel_details | An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section. | Required | ||
| parcel_details.service_code | Code to represent a delivery service. | Required | ||
| 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). | Not required | ||
| parcel_details.undeliverable_instructions | Instructions in case of non-delivery. | Required If | Value must be NONE, RETURN or DESTROY. | The undeliverable instructions vary for the services used. |
| parcel_details.indicia_number | Your indicia (PermitPost or DirectPost) number. | Required If available | ||
| parcel_details.insurance_required | Whether additional cover is required for the parcel. Value must be either TRUE or FALSE. | Required If | Value must be either TRUE or FALSE. | The availability of Additional Cover varies by service and by the declared value of the parcel. |
| parcel_details.nature_of_transaction_code | Category of goods that appears on the CN23 form. Value depends on the nature of the items. | Required | Must be one of: 11=Sale of goods; 21=Returned Goods; 31=Gift; 32=Commercial Sample; 91=Documents; 991=Other | |
| parcel_details.postage_paid_amount | Monetary value of postage that sender has paid. | Required | Value must be greater than $0.00. | |
| parcel_details.additional_fee_amount | Monetary value of other fees that sender has paid. E.g. additional insurance. | Not required | ||
| parcel_details.insured_value_amount | Monetary value the parcels are covered for. | Not required | ||
| parcel_details.currency | Currency code for the parcel. | Required | ||
| parcel_details.dimensions | An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. | Required | ||
| parcel_details.dimensions.length_cm | Length of the parcel. | Required | ||
| parcel_details.dimensions.width_cm | Width of the parcel. | Required If | Required for rectangle parcels. | |
| parcel_details.dimensions.height_cm | Height of the parcel. | Required If | Required for rectangle parcels. | |
| parparcel_details.dimensions.diameter_cm | Diameter of the parcel. | Required If | Required for tubes. | |
| parparcel_details.dimensions.weight_kg | Weight of the parcel. | Required | ||
| parcel_details.dangerous_goods | An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section. Please refer to Dangerous Goods section for more information. | Required If | ||
| parcel_details.dangerous_goods.items.hazard_class | Classification of dangerous items in the parcel. Value must be from Hazard Identification Code. | Required If | Value must be from Hazard Identification Code and can only be 9. | |
| parcel_details.dangerous_goods.items.un_number | United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits. | Required If | Value can only either 3481 or 3091. | |
| parcel_details.parcel_contents | An array containing content details of a parcel. | Required If | ||
| parcel_details.parcel_contents.content_number | Number specifying an item in the parcel. | Required | Value must be an integer between 1 to 20 inclusive. | |
| parcel_details.parcel_contents.description | Description of the parcel contents. | Required | ||
| parcel_details.parcel_contents.harmonised_system_tariff | Harmonized System (HS) codes are commonly used throughout the import and export process for the classification of goods. The Harmonized System is a standardized numerical method of classifying traded products. | Required If | 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)). | List of destinations that require HS tariff codes to be provided can be found at nzpost.co.nz/ead. |
| parcel_details.parcel_contents.quantity | Total number of units for each individual item type in the parcel. NZ Customs require declaration of the quantity per item type separately. | Required | ||
| parcel_details.parcel_contents.weight_kg | Declared total combined weight of all items in the parcel. This is the sum of the weights of each individual item type | Required | ||
| parcel_details.parcel_contents.value | Declared total value of each item type. Each separate item type should be declared with its total value. Customs value excluding freight or insurance. | Required | ||
| parcel_details.parcel_contents.country_code | The 2-letter country code of the location in which the content piece was produced or manufactured. | Recommended if known | Value must be 2 characters. | |
| parcel_details.accompanying_documents | An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section. | Not required | ||
| parcel_details.accompanying_documents.type | Code must be one of an allowed subset of codes. | Not required | Value must be one of LIC, 811 or 911 | |
| parcel_details.accompanying_documents.identifier | Value entered on the CN23 license box. | Not required |
Dangerous Goods - Lithium Battery
Below are the details and validations that are implemented when the customer is requesting labels for parcels containing devices that have lithium batteries either packed with, or contained with in it.
- Hazard Identification Details
| Field | Description | Supported values |
| parcel_details.dangerous_goods.items.hazard_class | Classification of dangerous items-Lithium Battery in the parcel. Value must be from Hazard Identification Code. | 9 |
| parcel_details.dangerous_goods.items.un_number | Dangerous Goods-Lithium Battery identification code for dangerous goods in the parcel. Value must be 4 digits. | 3091,3481 |
- Supported services and details
| Supported Label Provider(For Internal Use) | Supported service Codes | Remarks |
| GO_UPU_PROCESS | IECOT, IECOP, ICOU, ICOUE, IECOPRES, ICOU7, ICOURES, IECOP7 | All destinations available for the service except Germany and Italy. |
| GO_DHL_PROCESS | IEXP,IEXPDTP,IEXPRES | All destinations available for the service. |
| GO_AUS_PROCESS(CS_AUS) | ICOUSSAUN,ICOUSSAUT,ICOUSEAUS,ICOUSEAUN,ICOUSSAUS | Destination Australia is available for the service. |
- Validations
| Dangerous_Goods-Lithium Battery(LB) Validations | Validation results |
| Dangerous_Goods(DG) not provided in label request, then continue 'regular' label generation. | Label Generated. |
| Dangerous_Goods(DG) provided, but Label service is not Lithium Battery supported service label provider, then continue 'regular' label generation. | Label Generated. |
| Dangerous_Goods(DG) provided and Lithium Battery supported label provider, but service code is not Lithium Battery supported, then return an error message. | Error message: "The service is not available to send equipment including lithium batteries, visit nzpost.co.nz and search ECLB for more information." |
| Dangerous_Goods(DG) provided and service code is Lithium Battery supported service, but destination is not Lithium Battery supported destination, then return an error message. | Error message: "The last-mile delivery agent at the destination is not authorised to accept equipment including lithium batteries (ECLB), visit nzpost.co.nz and search ECLB for more information." |
| Dangerous_Goods(DG) provided and Lithium Battery supported service code and destination, but dangerous_goods/items/hazard_class is NOT 9, then return an error message. | Error message: "The only acceptable value of the field hazard_class is “9”, representing Class 9 - miscellaneous dangerous goods, which the lithium batteries are classified as." |
| Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, but dangerous_goods/items/un_number is NOT 3091 or 3481, then return an error message. | Error message: "The acceptable value of the field un_number is “3481” - Lithium ion batteries contained in equipment or “3091”- Lithium ion batteries packed with equipment." |
| Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, dangerous_goods/items/hazard_class is 9 and dangerous_goods/items/un_number is in (3091 or 3481), then continue label generation with ECLB indicator. | Label Generated with ECLB indicator. |
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"
},
"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",
"dangerous_goods": {
"items": [
{
"un_number": "3091",
"hazard_class": "9"
}
]
},
"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
