ParcelLabel API
Create label(s) - Offshore Tradelanes
How to generate international parcel labels for parcels being sent from overseas locations
When generating parcel labels for packages originating from outside of New Zealand, merchants are able to choose the shipping method for how the parcel will be delivered to its destination. NZ Post currently offers the following services for customers:
- International Courier (tracked) - courier service into New Zealand. Refer to Create Label(s) - International Inbound to NZ (Offshore)
- International Courier (tracked) - courier service into countries apart from New Zealand.
- ETOE (Please speak to your NZ Post account manager) Refer to Create Label(s) - International ETOE
These services need to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.
Service Description
| Service Name | Service Code | Origin Country(s) | Destination Country | Service Specific Rules |
| Courier Select AU Standard Signature with ATL | IXBCSAUS | China, India | Australia | • Does not support insurance |
| Courier Select AU Standard Sig Reqd No ATL | IXBCSAUN | China, India | Australia | • Does not support insurance |
| Courier Select AU Express Sign with ATL | IXBCEAUS | China, India | Australia | • Does not support insurance |
| Courier Select AU Express Sig Reqd No ATL | IXBCEAUN | China, India | Australia | • Does not support insurance |
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 labeling database. One or multiple labels can be generated within a consignment (for International Courier only)
Request Parameters
For each of these services, the parameter requirements are similar but each service has slightly different requirements and needs to use the relevant service code. In the following table, we have provided which fields are required in the label request for a particular service.
A JSON sample for service IXBCSAUS is provided below. The structure of the payload is the same for each service code - simply replace the service code with the one you need.
| Field Name | Type (Length Limit) | Description | Required? |
| carrier | string | Carrier of the parcel. Value must be PARCELPOST | Yes - ParcelPost |
| format | string | Format of the label. Value must be PDF or PNG. Default Value is PDF. | No |
| notification_endpoint | string(2048) | Merchants Webhook URL to receive notification when the label has been generated. | No |
| sender_reference_1 | string(35) | Sender's reference for the consignment. Will be printed on the label. | No |
| sender_reference_2 | string(35) | Sender's reference. Will not be printed on the label. | No |
| paper_dimensions | object | An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters section. | No |
| paper_dimensions.width_cm | number | 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 | number | Height of the label to be printed to. Default value is 10 | No |
| paper_dimensions.stationery_size | string | Paper size upon which to print the label. Must be A4 or A5. | No |
| sender_details | object | An object containing the sender contact details. See Sender Details Object Parameters below. | Yes |
| sender_details.name | string(40) | Name of the sender. | Yes |
| sender_details.phone | string(20) | Phone number of the sender. NO SPACES, DIGITS and '+' ONLY | Yes |
| sender_details.email | string(254) | Email address of the sender. | No but highly desirable |
| sender_details.fax | string(26) | Contact fax number of the sender | No |
| sender_details.signatory | string(40) | Name of the individual sending the parcel, this is used for customs purposes. | No |
| sender_details.company_name | string(40) | Company name of the sender. | No |
| sender_details.customs_code | string(15) | Customs code of the sender. | No |
| receiver_details | object | An object containing the receiver contact details. See Receiver Details Object Parameters below. | Yes |
| receiver_details.name | string(40) | Name of the receiver. | Yes |
| receiver_details.phone | string(20) | Contact phone number of the receiver. NO SPACES, DIGITS and '+' ONLY | No but highly desirable |
| receiver_details.email | string(254) | Email address of the receiver. | No but highly desirable |
| receiver_details.fax | string(26) | Fax number of the person to receiver. | No |
| receiver_details.vat_number | string(25) | The VAT or GST number of the receiver. The field should not be > 14 characters. | No |
| receiver_details.registration_number | string(30) | Registration number of the receiver required for Delivery Location Options. | No |
| pickup_address | object | An object containing the pickup address details. This will need to be set to hardcoded values depending on the destination country. Refer to the below table of pickup countries for values to use |
Yes |
| pickup_address.company_name | string(40) | Company name of the pickup address | No |
| pickup_address.building_name | string(40) | Building name of the pickup address. | No |
| pickup_address.street_number | string(10) | Street number of the pickup address. | No but highly desirable |
| pickup_address.street | string(40) | Street name of the pickup address. | Yes |
| pickup_address.suburb | string(40) | Suburb of the pickup address | No but highly desirable |
| pickup_address.city | string(40) | City of the pickup address | Yes |
| pickup_address.state | string(35) | Regional, provincial or county name of the pickup address. | No but highly desirable |
| pickup_address.locality_code | string(9) | Country subdivision code identifier that the pickup address belongs to. | No |
| pickup_address.country_code | string(2) | Two character country code of the pickup address. | Yes |
| pickup_address.postcode | string(17) | Postal or zip code of the pickup address. | Yes |
| delivery_address | object | An object containing the receiver delivery address details. See Receiver Address Object Parameters section | Yes |
| delivery_address.location_type | string(3) | Type of the delivery requested for the item. Value must be from UPU code list 199. | No |
| delivery_address.building_name | string(40) | Building name of the delivery address. | No |
| delivery_address.company_name | string(40) | Name of company that the parcel is being delivered to. | No |
| delivery_address.street_number | string(10) | Street number of the delivery address. | No but highly desirable |
| delivery_address.street | string(40) | Street name of the delivery address. | Yes |
| delivery_address.suburb | string(40) | Suburb of the delivery address | No but highly desirable |
| delivery_address.city | string(40) | City of the delivery address | Yes |
| delivery_address.state | string(35) | State name of the delivery address | No |
| delivery_address.locality_code | string(9) | Country subdivision code identifier that the delivery address belongs to. | No |
| delivery_address.country_code | string(2) | Two character country code of the delivery address. | Yes | delivery_address.postcode | string(17) | Postal or zip code of the delivery address. | Yes |
| delivery_address.instructions | string(255) | Delivery instructions for courier | No |
| parcel_details | object | An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section | Yes |
| parcel_details.service_code | string(15) | Code to represent a delivery service. This is the service code. | Yes |
| parcel_details.receiver_charging_arrangement | string | Duty and tax payment method as it applies to the item. Value must be DDP (Delivery Duty Paid) OR DDU (Delivery Duty Unpaid) | No |
| parcel_details.undeliverable_instructions | string | Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY. | Yes |
| parcel_details.insurance_required | boolean | Whether insurance is required for the parcel. Value must be either true or false. Use false if the service does not support insurance |
Yes |
| parcel_details.nature_of_transaction_code | string(3) | Mandatory field which needs to be set to 11. This corresponds to Sales of goods | Yes |
| parcel_details.postage_paid_amount | number | Monetary value of postage that sender has paid. Value must be greater than 0. | No |
| parcel_details.additional_fee_amount | number | Monetary value of other fees that sender has paid. E.g. additional insurance | No |
| parcel_details.currency | string(3) | Currency code for the parcel | Yes |
| parcel_details.dimensions | object | An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. | Yes |
| parcel_details.dimensions.length_cm | number | Length of the parcel. | Yes |
| parcel_details.dimensions.width_cm | number | Width of the parcel. | Yes |
| parcel_details.dimensions.height_cm | number | Height of the parcel. | Yes |
| parcel_details.dimensions.weight_kg | number | Physical weight of the parcel in kilograms. | No |
| parcel_details.dangerous_goods | object | 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. | No |
| parcel_details.dangerous_goods.hazard_class | string(4) | Classification of dangerous items in the parcel. If provided must be 9 | No |
| parcel_details.dangerous_goods.un_number | string(4) | United Nations Dangerous Goods identification code for dangerous items in the parcel. If provided must be either 3481 or 3091 | No |
| parcel_details.parcel_contents | array | An array containing content details of a parcel. | Yes |
| parcel_details.parcel_contents.content_number | integer | Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive. | Yes |
| parcel_details.parcel_contents.description | string(35) | Description of the parcel contents. | Yes |
| parcel_details.parcel_contents.harmonised_system_tariff | string(18) | Internationally standardized name and number of the classification of the parcel content. | No |
| parcel_details.parcel_contents.quantity | integer | Quantity of units in the parcel. | Yes |
| parcel_details.parcel_contents.weight_kg | number | Weight of each individual unit in the parcel(kgs). | Yes |
| parcel_details.parcel_contents.value | number | Dollar value of each individual unit in the parcel. | Yes |
| parcel_details.parcel_contents.country_code | string(2) | Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters. | No |
Pickup Address Hardcoded Values
Each destination country has a pickup location which must be used in your label request.
| Destination Country | Pickup Address Values |
| Australia (AU) | "pickup_address": { "company_name": "", "building_name": "", "unit_type": "Unit", "unit_value": "8", "floor": "", "street_number": "87", "street": "Fitzroy Street", "suburb": "MARRICKVILLE", "city": "NSW", "state": "NSW", "locality_code": "", "country_code": "AU", "postcode": "2204" } |
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 within.
- 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_AUS_PROCESS (CS_AUS) | IXBCSAUS, IXBCSAUN, IXBCEAUS, IXBCEAUN | 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. |
Australia tradelane - China to Australia
{
"carrier": "PARCELPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "1731",
"sender_reference_2": "NZP-TEST-012",
"sender_details": {
"name": "Sender Company Name",
"phone": "+64123456789",
"email": "sendercompany@nzpost.co.nz",
"company_name": "Test Sender Company",
"signatory": "Sender Company Limited"
},
"pickup_address": {
"company_name": "",
"building_name": "",
"unit_type": "Unit",
"unit_value": "8",
"floor": "",
"street_number": "87",
"street": "Fitzroy Street",
"suburb": "MARRICKVILLE",
"city": "NSW",
"state": "NSW",
"locality_code": "",
"country_code": "AU",
"postcode": "2204"
},
"receiver_details": {
"name": "Test Receiver",
"phone": "6490000002",
"email": "testreceiver@nzpost.co.nz",
"vat_number": "NONE"
},
"delivery_address": {
"building_name": "Sydney Opera House",
"street": "Bennelong Point",
"suburb": "Sydney",
"city": "Sydney",
"state": "New south wales",
"country_code": "AU",
"postcode": "2000"
},
"parcel_details": [
{
"service_code": "IXBCSAUS",
"undeliverable_instructions": "RETURN",
"insurance_required": false,
"nature_of_transaction_code": "11",
"is_only_documents": false,
"postage_paid_amount": 0.01,
"currency": "NZD",
"dangerous_goods": {
"items": [
{
"un_number": "3091",
"hazard_class": "9"
}
]
},
"dimensions": {
"length_cm": 16.0,
"width_cm": 15.0,
"height_cm": 10.0,
"weight_kg": 0.300
},
"parcel_contents": [
{
"content_number": 1,
"description": "Dietary Supplement",
"quantity": 1,
"weight_kg": 0.3,
"value": 150.81
}
]
}
]
}
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": "DVZQYF",
"message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",
"success": true
}