Generate method

This API generates a tracking code, and a printable label for your package.

To generate a label you need to work through the following steps:

  1. Generate Label. A successful label generation response will return a 'Details URL' and a 'Print URL'.
  2. Poll the Details URL until the label has been successfully generated -or- wait for the label generation callback.
  3. Download the PDF of the Label from the Print URL.

Label generation can fail at 2 points:

  1. The Generate Label call: this service can return a non-200 response code indicating failure based on some basic checks such as field lengths and mandatory fields. The response will provide a set of error messages to indicate why failure has occurred.
  2. The second point of failure is once the generation request has been accepted and is indicated based on a query of the Details URL or the receipt of the webhook. In either case, this indicates a failure to generate the label based on more advanced and rigorous checking such as an invalid postcode for the destination country. These more advanced errors are reported with both an error code and message.

Try it here

API Details

URL HTTP Request Types Request Formats
https://api.nzpost.co.nz/labels/generate POST JSON

Request Parameters

Parameter Description Required Value Maximum Length Example
api_key Your license key for the application. Please contact developer@nzpost.co.nz for a license key Yes String c4f820f0420a012ea143000c290fbf99
destination_contact_name Named person to receive this package Yes String 40 Ben Smith
destination_contact_phone Contact phone number of the person receiving this package No String 20 09 882 3478
destination_company The name of the company receiving the package. No String 40 Ben's Bins
destination_building The building name No String 40 Majestic Centre
destination_street Street and and number Yes String 40 135-139 Victoria St
destination_locality Typically the name of the suburb No String 40 Te Aro
destination_city The city name Yes String 40 Stratford
destination_state State or County of destination No String 40 NSW
destination_country_code Two-letter country code Yes String NZ
destination_postal_code Postal or Zip code of the destination No String 20 6011
destination_vat_number The VAT or GST number of the consignee No String 14 GB123123123123
destination_reference Reference field for the receiver No String Order #365
destination_email Contact email address of the receiver No String 50 jane.smith@zerocost.com
destination_fax Contact fax number of the receiver No String 20 09 882 3478
sender_contact_name Contact name of the person sending this package Yes String 40 John Smith
sender_signature Contact name of the person signing this package No String John Smith
sender_contact_phone Contact phone number of the person sending this package No String 20 04 910 3101
sender_company The name of the company sending the package. No String 40 Taranaki Recyclers Limited
sender_building The building name No String 40 Majestic Centre
sender_street Street and and number Yes String 40 8a High St
sender_locality Typically the name of the suburb No String 40 Korokoro
sender_city The city name Yes String 40 Lower Hutt
sender_state State or County of sender No String 40 NSW
sender_country_code Two-letter country code (defaults to NZ if left blank) No String NZ
sender_postal_code Postal or Zip code of the sender No String 20 AL11XU
sender_customs_code Customs code of the sender No String 15 HGD34373
sender_reference Reference code of the sender No String 123/456
sender_email Contact email address of the sender No String 50 john.smith@zerocost.com
service_code The NetDespatch service code. Must supply either service_code or cms_code Yes String 6 PCM3C4
cms_codes Codes that will be translated to a NetDespatch service code. Must supply either service_code or cms_code No String (of comma separated codes) PCMXT25,TSSUPCNS
indicia_number The NetDespatch Indicia number No String 6 123456
user_reference_code Sender's own unique identifier for this package. Must be unique, as used for duplicate identification. Yes String 20 PKG-23478236565
parcel_length Length of the package, measured in mm No Integer 600
parcel_height Height of the package, measured in mm No Integer 300
parcel_width Width of the package, measured in mm No Integer 300
parcel_unit_description Human readable description of the parcel contents Yes String 35 Eco-saver bulbs 23W
parcel_unit_quantity The quantity of units within the parcel Yes Integer 50
parcel_unit_value The NZ dollar value of each item in the parcel Yes 4.90
parcel_unit_currency The currency in which you are providing the parcel value (Defaults to NZD) Yes String NZD
parcel_unit_weight The weight in kilograms of each item in the parcel Yes 0.1
parcel_unit_hs_tariff Harmonised system tariff code for parcel unit (not entire parcel) - Refer to https://hts.usitc.gov/ to find the tariff for your item No String 121212
parcel_unit_country_of_origin The country where the goods were manufactured No String Australia
insurance_required Is insurance required for this package? Answer one of:
  • 1 for Yes
  • 0 for No
 Yes Integer 0
documents Does this package contain only documents? Answer one of:
  • 1 for Yes
  • 0 for No
 Yes Integer 1
delivery_instructions Delivery instructions for courier (30 chars max) No String 255 Leave on doorstep
non_delivery_instruction Instructions in case of non-delivery. Answer one of:
  • NONE for no instructions
  • RETURN for return to sender
  • DESTROY for destroy documents
 Yes String NONE
export_type Type of Export. Answer one of:
  • Sale of Goods
  • Commercial Sample
  • Gift
  • Returned Goods
  • Documents
  • Other
 Yes - International Shipments Only String Other
hs_tariff The Harmonised System Tariff for your entire parcel. Refer to https://hts.usitc.gov/ to find the tariff for your item. No String 12121212
validate_only Validate all fields but do not create the label. Helpful for pre-validating API submissions. Answer one of:
  • 1 for Yes
  • 0 for No
 No Integer 1
skip_print Skip downloading of the label PDF
  • 1 for Yes
  • 0 for No
 No Integer 1
batch_id The id of a batch that the label belongs to No String
collection_location_id The id of a location where reciever will pick up parcel. Must be a 3rd party partner that allows collection. No String
force_regenerate Should we force a label to be regenerated if one already exist? Answer one of:
  • 1 for Yes
  • 0 for No
 Yes Integer 0
prepaid Has the label been pre-paid? (only enabled for some licenses):
  • 1 for Yes
  • 0 for No
 No Integer 0
provided_tpid TPID for charging if different to license TPID (only enabled for some licenses): No String
provided_account_id Alternate Account ID to the license RedClick Account ID (only enabled for some licenses): No String

Types of Response

Response Type Status Code
Success 200
Invalid Request 400
Unauthorised Request 401

Response Elements

Element Description Value Required Example
success Overall request success or failure flag Boolean Yes true
message A message describing the outcome of the API call. String Yes Success
print_url URL to retrieve the PDF label once it is ready. String No https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.pdf
details_url URL to return the status if the label job as it is created. String No https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.json
label_uuid The unique id of the generated label String No bcdfh47fdgsd534
errors Optional further error details. Usually related to specific field validation errors. Hash No {destination_country_code: supplied country code is not recognised}

Examples

Note: When an error occurs, the content type is set to application/json.

Responses:

    
{
  "success": true,
  "message": "Success",
  "print_url": "https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.pdf",
  "details_url": "https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.json",
  "label_uuid": "bcdfh47fdgsd534"
}

{
  "success": false,
  "message": "Validation errors",
  "errors": {"destination_country_code":"supplied country code is not recognised"}
}

Callback Details

After a successful generate label request, a PDF containing the printable label and tracking code will be generated. When this is ready, a callback will be initiated by NZ Post. The callback uses the WebHook guidelines to deliver the required information.

If an error occurs during the label generation, the callback is also used to return the error details.

If you are unable to receive a WebHook callback, you can instead request the status of a label using the Label Details API call.

You specify the callback URL when you register for an API key. The following parameters are sent via an HTTP POST operation:

Request

Parameter Name Description Example Success/Error
label_uuid Label UUID The unique label identifier that was returned in the original response bcdfh47fdgsd534 Both
status_code Status Code Was the label request process successfully, or was there an error? OK or ERROR Both
user_reference_code User reference code Sender's own unique identifier for this package PKG-23478236565 Both
tracking_code Tracking Code New code to use for tracking this package RA123456789NZ Success
print_url Print URL URL to the printable label (in PDF format) https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.pdf Success
details_url Details URL URL to the download more details about the label (in JSON, XML or HTML format) https://api.nzpost.co.nz/labels/label/bcdfh47fdgsd534.json Success
error_code Error Code A number to represent the kind of error that occurred 1001 Error
error_reason Error Reason A human-readable message to describe the kind of error that occurred Account ID not valid for this User Error

Response

The receiving server is expected to respond with a 200 (success) status code.