ParcelLabel API

Download
Opens request access modal
(2 reviews)

Create Label(s) - International (Offshore)

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 ParcelPost Flat (untracked) - standard postal service into New Zealand
  • International CourierPost (tracked) - courier service into New Zealand
  • ETOE (Please speak to your NZ Post account manager)

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.

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 labelling database. One or multiple labels can be generated within a consignment (for International CourierPost only)

Request Parameters

For each of these services, the parameter requirements are similar but each service has slightly different requirements and need 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. Additional requirements for CourierPost Tracked services are listed beneath the standard parameters.

Code samples for each of these separate service types is displayed further down this page.

Field Name Description Required for Int ParcelPost? Required for Int CourierPost? Required for ETOE?
carrier Carrier of the parcel. Value must be one of COURIERPOST or PARCELPOST Yes - ParcelPost Yes - CourierPost Yes - ParcelPost
logo_id Unique identifier for merchants logo. The field is only relevant for International CourierPost services N/A No N/A
format Format of the label. Value must be PDF or PNG. Default Value is PDF. No No No
notification_endpoint Merchants Webhook URL to receive notification when the label has been generated. No No No
delivery_choice_type Additional service requested for the delivery. Value is a string and must be either 1 or 2. No No No
sender_reference_1 Sender's reference for the consignment. Will not be printed on the label. No No No
sender_reference_2 Sender's reference. Will not be printed on the label. No No No
sender_details An object containing the sender contact details. See Sender Details Object Parameters below. Yes Yes Yes
sender_details.name Name of the sender. Yes Yes Yes
sender_details.phone Phone number of the sender. NO SPACES, DIGITS and '+' ONLY Yes Yes Yes
sender_details.email Email address of the sender. No but highly desirable No but highly desirable No but highly desirable
sender_details.fax Contact fax number of the sender No No No
sender_details.signatory Name of the individual sending the parcel, this is used for customs purposes. No No No
sender_details.company_name Company name of the sender. No No No
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. No Yes No
sender_details.customs_code Customs code of the sender. No No No
receiver_details An object containing the receiver contact details. See Receiver Details Object Parameters below. Yes Yes Yes
receiver_details.name Name of the receiver. Yes Yes Yes
receiver_details.phone Contact phone number of the receiver. NO SPACES, DIGITS and '+' ONLY No but highly desirable No but highly desirable No but highly desirable
receiver_details.email Email address of the receiver. No but highly desirable No but highly desirable No but highly desirable
receiver_details.fax Fax number of the person to receiver. No No No
receiver_details.vat_number The VAT or GST number of the receiver. The field should not be > 14 characters. No No No
receiver_details.registration_number Registration number of the receiver required for Delivery Location Options. No No No
pickup_address An object containing the sender pickup address details. See Pickup Address parameters below Yes (NB: this is used as the NZ return address for this service) Yes (NB: this is used as the NZ return address for this service) Yes (NB: this is used as the NZ return address for this service)
International CourierPost 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.company_name Company name of the pickup address No No No
pickup_address.building_name Building name of the pickup address. No No No
pickup_address.street_number Street number of the pickup address. No but highly desirable No but highly desirable No but highly desirable
pickup_address.street Street name of the pickup address. Yes Yes Yes
pickup_address.suburb Suburb of the pickup address No but highly desirable Yes No but highly desirable
pickup_address.city City of the pickup address Yes Yes Yes
pickup_address.state Regional, provincial or county name of the pickup address. No but highly desirable No No but highly desirable
pickup_address.locality_code Country subdivision code identifier that the pickup address belongs to. No N/A No
pickup_address.country_code Two character country code of the pickup address. Yes No Yes
pickup_address.postcode Postal or zip code of the pickup address. Yes Yes Yes
delivery_address An object containing the receiver delivery address details. See Receiver Address Object Parameters section Yes Yes 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.location_type Type of the delivery requested for the item. Value must be from UPU code list 199. No No No
delivery_address.building_name Building name of the delivery address. No No No
delivery_address.company_name Name of company that the parcel is being delivered to. No No No
delivery_address.street_number Street number of the delivery address. No but highly desirable No but highly desirable No but highly desirable
delivery_address.street Street name of the delivery address. Yes Yes Yes
delivery_address.suburb Suburb of the delivery address No but highly desirable Yes No but highly desirable
delivery_address.city City of the delivery address Yes Yes Yes
delivery_address.state State name of the delivery address No No No
delivery_address.locality_code Country subdivision code identifier that the delivery address belongs to. No N/A No
delivery_address.country_code Two character country code of the delivery address. For domestic labels, this must be set to NZ. Yes Yes Yes
delivery_address.postcode Postal or zip code of the delivery address. Yes Yes Yes
delivery_address.instructions Delivery instructions for courier No No No
parcel_details An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section Yes Yes Yes
parcel_details.service_code Code to represent a delivery service. This is the service code. Yes Yes 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 N/A Yes
parcel_details.undeliverable_instructions Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY. Yes No Yes
parcel_details.indicia_number Your indicia number Yes No Yes
parcel_details.insurance_required Whether insurance is required for the parcel. Value must be either TRUE or FALSE Yes No 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 No No Yes
parcel_details.postage_paid_amount Monetary value of postage that sender has paid. Value must be greater than 0. Yes No Yes
parcel_details.additional_fee_amount Monetary value of other fees that sender has paid. E.g. additional insurance No No No
parcel_details.insured_value_amount Monetary value the parcels are insured for. No No No
parcel_details.currency Currency code for the parcel Yes N/A Yes
parcel_details.dimensions An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. Yes Yes Yes
parcel_details.dimensions.length_cm Length of the parcel. Yes Yes Yes
parcel_details.dimensions.width_cm Width of the parcel. Yes Yes Yes
parcel_details.dimensions.height_cm Height of the parcel. Yes Yes Yes
parcel_details.dimensions.weight_kg Physical weight of the parcel in kilograms. No Yes No
parcel_details.dangerous_goods An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section. No No 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 No 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 No No
parcel_details.parcel_contents An array containing content details of a parcel. Yes No 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 No Yes
parcel_details.parcel_contents.description Description of the parcel contents. Yes No Yes
parcel_details.parcel_contents.harmonised_system_tariff Internationally standardized name and number of the classification of the parcel content. No No No
parcel_details.parcel_contents.quantity Quantity of units in the parcel. Yes No Yes
parcel_details.parcel_contents.weight_kg Weight of each individual unit in the parcel (kgs). Yes No Yes
parcel_details.parcel_contents.value Dollar value of each individual unit in the parcel. Yes No 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 No No
parcel_details.accompanying_documents An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section N/A N/A Yes
parcel_details.accompanying_documents.type Code must be one of an allowed subset of codes. Value must be one of: LIC, 811 or 911. N/A N/A Yes
parcel_details.accompanying_documents.identifier Value entered on the CN23 license box. N/A N/A Yes

International CourierPost Base Services

The following are sample base service codes for International inbound parcel and satchel courier services

GST inclusive Product CodeGST zero-rated Product CodeProduct Code Description
IWOLPIWXOLPOvernight Parcel
IWOLEIWXOLEEconomy Parcel
IWOLTPSDLIWXOLTPSDLSatchel (DLE)
IWOLTPSA5IWXOLTPSA5Satchel (A5)
IWOLTPSA4IWXOLTPSA4Satchel (A4)
IWOLTPSFSIWXOLTPSFSSatchel (FS)
IWOLTPSLFIWXOLTPSLFSatchel (LF)
IWOLTPSXLIWXOLTPSXLSatchel (XL)

International CourierPost Bag/Satchel Sizes

Where the parcel is a bag or satchel (and you intend to send as a bag or satchel), 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 e.g. IWOLTPSFS

Below is a list of valid bag/satchel/envelope sizes.

Size CodeDescription
A4A4
A5A5
DLDLE
FSFoolscap
LFLineFlow
XLXtra Large

International CourierPost Add ons

The following are sample value add-ons.

Add on NameDescription
IWSR or IWXSRCourierPost Signature Required
IWOLRD or IWXOLRDCourierPost Rural Delivery
IWOLSAT or IWXOLSATCourierPost Online Saturday Delivery
IWOLDG or IWXOLDGCourierPost 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: IWOLRD CourierPost Rural Delivery, IWOLSAT CourierPost Online Saturday Delivery or IWOLDG CourierPost Online Dangerous Goods
  3. Signature required, IWSR, 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

Sample Requests

International ParcelPost Flat (untracked) – United Kingdom to New Zealand

{
  "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": "4490000001",
    "email": "sender@example.co.nz",
    "company_name": "Test Sender Company",
    "site_code": 12345
  },
  "pickup_address": {
    "company_name": "Test Pickup Address Company",
    "building_name": "Test Pickup Address Building",
    "unit_type": "Unit",
    "unit_value": "2",
    "floor": "Floor 5",
    "street": "100 High St",    
    "city": "Liverpool",
    "suburb": "Wavertree",
    "country_code": "GB",
    "postcode": "L15 8HQ"
  },
  "receiver_details": {
    "name": "Receiver Name",
    "phone": "6490000002",
    "email": "receiver@example.co.nz"
  },
  "delivery_address": {
      "street": "122 Kerwyn Avenue",
      "suburb": "East Tamaki",
      "city": "Auckland",
      "country_code": "NZ",
      "postcode": "2013"
  },
   "parcel_details": [
      {
         "service_code": "TPPF",
         "undeliverable_instructions": "DESTROY",
         "indicia_number": "200003",
         "insurance_required": false,
         "nature_of_transaction_code": "11",
         "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
            }
         ]
      }
   ]
}

International CourierPost – Australia to New Zealand (Pickup address is the return address in NZ)

{
    "carrier": "COURIERPOST",
    "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": 12345
    },
    "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": {
        "is_collection": false,
        "building_name": "Test Delivery Building Name",
        "company_name": "Test Delivery Company Name",
        "unit_type": "Suite",
        "unit_value": "4",
        "floor": "Floor 2",
        "street": "122 Kerwyn Avenue",
        "suburb": "East Tamaki",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2013",
        "instructions": "Ask for John Smith at the reception."
    },
    "parcel_details": [
        {
            "service_code": "IWOLP",
            "add_ons": ["IWSR"],
            "undeliverable_instructions": "RETURN",
            "return_indicator": "OUTBOUND",
            "indicia_number": "200003",
            "insurance_required": false,
            "nature_of_transaction_code": "11",
            "postage_paid_amount": 0.01,
            "currency": "NZD",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            },            
        },
        {
            "service_code": "IWOLE",
            "add_ons": [],
            "return_indicator": "RETURN",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            }
        }
    ]
}

ETOE - USA to Australia

{
  "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": "01906004001",
    "email": "sender@example.co.nz",
    "company_name": "Test Sender Company",
    "site_code": 12345
  },
  "pickup_address": {
    "company_name": "Test Pickup Address Company",
    "building_name": "Test Pickup Address Building",
    "unit_type": "Unit",
    "unit_value": "8",
    "floor": "Floor 10",
    "street": "50 High Street",
    "suburb": "",
    "city": "New Haven",
    "state": "MA",
    "country_code": "US",
    "postcode": "06510"
  },
  "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": "WIASPP",
         "undeliverable_instructions": "RETURN",
         "indicia_number": "200003",
         "insurance_required": false,
         "nature_of_transaction_code": "11",
         "postage_paid_amount": 0.01,
         "currency": "USD",
         "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

{
  "consignment_id": "DVZQYF",
  "message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",
  "success": true
}

Reviews