ParcelLabel API
3.0.0
Download
Create Label(s) - International Outbound from NZ
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 |
format | Format of the label. Value must be PDF or PNG. Default Value is PDF. | No |
notification_endpoint | Merchants Webhook URL to receive notification when the label has been generated. | No |
delivery_choice_type | Additional service requested for the delivery. Value is a string and must be either 1 or 2. | No |
sender_reference_1 | Sender's reference for the consignment. Will not be printed on the label. | No |
sender_reference_2 | Sender's reference. Will not be printed on the label. | 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 and '+' ONLY | Yes |
sender_details.email | Email address of the sender. | No but highly desirable |
sender_details.fax | Contact fax number of the sender | No |
sender_details.signatory | Name of the individual sending the parcel, this is used for customs purposes. | No |
sender_details.customs_code | Customs code of the sender. | 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 and '+' ONLY | No but highly desirable |
receiver_details.email | Email address of the receiver. | No but highly desirable |
receiver_details.fax | Fax number of the person to receiver. | No |
receiver_details.vat_number | The VAT or GST number of the receiver. For RedClick international labels, the field should not be > 14 characters. | No |
receiver_details.registration_number | Registration number of the receiver required for Delivery Location Options. | No |
pickup_address | An object containing the sender pickup address details. See Pickup Address parameters below | 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.street_number | Street number of the pickup address. | No but highly desirable |
pickup_address.street | Street name of the pickup address. | Yes |
pickup_address.suburb | Suburb of the pickup address | No but highly desirable |
pickup_address.city | City of the pickup address | Yes |
pickup_address.state | Regional, provincial or county name of the pickup address. | No but highly desirable |
pickup_address.locality_code | Country subdivision code identifier that the pickup address belongs to. | No |
pickup_address.country_code | Two character country code of the pickup address. | Yes |
pickup_address.postcode | Postal or zip code of the pickup address. | Yes |
delivery_address | An object containing the receiver delivery address details. See Receiver Address Object Parameters section | Yes |
delivery_address.location_type | Type of the delivery requested for the item. Value must be from UPU code list 199. | No |
delivery_address.building_name | Building name of the delivery address. | No |
delivery_address.company_name | Name of company that the parcel is being delivered to. | No |
delivery_address.street_number | Street number of the delivery address. | No but highly desirable |
delivery_address.street | Street name of the delivery address. | Yes |
delivery_address.suburb | Suburb of the delivery address | No but highly desirable |
delivery_address.city | City of the delivery address | Yes |
delivery_address.state | State name of the delivery address | Yes |
delivery_address.locality_code | Country subdivision code identifier that the delivery address belongs to. | No |
delivery_address.country_code | Two character country code of the delivery address. For domestic labels, this must be set to NZ. | Yes | delivery_address.postcode | Postal or zip code of the delivery address. | Yes |
delivery_address.instructions | Delivery instructions for courier | No |
parcel_details | An object 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. This is the NetDespatch service code. | Yes |
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 |
parcel_details.undeliverable_instructions | Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY. | Yes |
parcel_details.indicia_number | Your indicia number | Yes if service_code is TEXPRE, TPASIA, TIASPP or TIASPD |
parcel_details.insurance_required | Whether insurance is required for the parcel. Value must be either TRUE or FALSE | Yes |
parcel_details.nature_of_transaction_code | Category of goods that appears on the CN23 form. Value depends on the nature of the items. Must be one of: 11 = Sales of goods; 21 = Returned Goods; 31 = Gift; 32 = Commercial Sample; 91 = Documents; 999 = Other | Yes |
parcel_details.postage_paid_amount | Monetary value of postage that sender has paid. Value must be greater than 0. | Yes |
parcel_details.additional_fee_amount | Monetary value of other fees that sender has paid. E.g. additional insurance | No |
parcel_details.insured_value_amount | Monetary value the parcels are insured for. | No |
parcel_details.currency | Currency code for the parcel | Yes |
parcel_details.dimensions | An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. | Yes |
parcel_details.dimensions.length_cm | Length of the parcel. | Yes |
parcel_details.dimensions.width_cm | Width of the parcel. | Yes |
parcel_details.dimensions.height_cm | Height of the parcel. | Yes |
parcel_details.dangerous_goods | An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section. | No |
parcel_details.dangerous_goods.hazard_class | Classification of dangerous items in the parcel. Value must be from Hazard Identification Code List at: http://www.ilo.org/legacy/english/protection/safework/cis/products/safetytm/tranann5.htm | No |
parcel_details.dangerous_goods.type_code | United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits. | No |
parcel_details.parcel_contents | An array containing content details of a parcel. | Yes |
parcel_details.parcel_contents.content_number | Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive. | Yes |
parcel_details.parcel_contents.description | Description of the parcel contents. | Yes |
parcel_details.parcel_contents.harmonised_system_tariff | Internationally standardized name and number of the classification of the parcel content. | No |
parcel_details.parcel_contents.quantity | Quantity of units in the parcel. | Yes |
parcel_details.parcel_contents.weight_kg | Weight of each individual unit in the parcel (kgs). | Yes |
parcel_details.parcel_contents.value | Dollar value of each individual unit in the parcel. | Yes |
parcel_details.parcel_contents.country_code | Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters. | No |
parcel_details.accompanying_documents | An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section | No |
parcel_details.accompanying_documents.type | Code must be one of an allowed subset of codes. Value must be one of: LIC, 811 or 911. | No |
parcel_details.accompanying_documents.identifier | Value entered on the CN23 license box. | 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"
},
"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 |