ParcelLabel API

2.0.x
(2 reviews)

Operational Considerations

The following information is intended to inform integrating merchants using NZ Post of operational processes that may impact how the ParcelLabel API is used.

  1. The label formats produced by the ParcelLabel API are compliant with addressing standards for the NZ Post carriers (ParcelPost, CourierPost and Pace) and cannot be changed for specific customers or used for other carriers.
  2. Labels produced are in either .pdf or .png format depending on the format requested. It is the sender’s responsibility to print this label such that it can be affixed to the package and is of a resolution such that the printed bar code can be scanned. Thermal labels are recommended to provide a professional look for your customers and to ensure the label will remain affixed to the parcel throughout transit. Laser printers will also produce the resolution required. Ink-jet printers cannot be used. If labels are printed on plain paper (not thermal sticky labels) then the paper needs to be attached to the parcel securely. It is recommended that "plastic sleeves" are purchased and the paper is folded into it.
  3. Note that it is possible to request multiple labels. The consignment_id returned in the response identifies the consignment (the group of labels) not an individual label. Individual labels will be identified by the consignment_id plus a number relating to the sequence of the labels e.g. XYZ123-1 will identify the first label in consignment "XYZ123". A consignment is made up of multiple parcels being picked up from one location and being delivered to one location.
  4. Where Pace is the carrier, a Pace job number is required for the label request. This job number can be created as part of the ParcelPickup API process.
  5. The service code required in a label request can be identified using the ShippingOptions API. If not consuming the ShippingOptions API, please speak to the NZ Post Salesperson assigned to your account to receive a list of service codes.
  6. It is the merchant's responsibility to indicate by way of the "is_collection" flag if a delivery address is a NZ Post collection point so that the appropriate label can be generated. Please see the ParcelAddress Locations resource for more information regarding collection points.
  7. If the delivery address that is used for labeling is an NZ Post collection point then you MUST create a PCD type subscription for the parcel recipient via the ParcelNotification API. This requires the tracking reference from the label, parcel recipient's first and last names, email address and the location ID of the collection point.

Use of Company Logos on Labels

CourierPost and Pace labels can have company logos embedded in the label image. There are specific rules that apply to the use and application of logos.

  1. Merchants who have applied and been accepted to have their logo included on their labels must provide a logo image in .png format with dimensions of 1480 pixels wide and 380 pixels high to the API Support team (api@nzpost.co.nz)
  2. Upon provision of a logo, a unique logo id will be provided to the merchant. The merchant must provide this logo id as the value of the logo_id parameter in order for their logo to appear on the requested label
  3. If the logo id provided does not exist, is invalid or is associated with another merchant, the requested label will be generated without a logo
  4. If in the unlikely event that NZ Post is unable to retrieve the logo for inclusion on the label for technical reasons, the requested label will be generated without a logo
  5. A merchant may have more than one logo. Each will be assigned a unique logo id. It is the merchant's responsibility to provide the correct logo id with each label request
  6. Where the parcel contents have been identified as dangerous goods, the merchant logo will NOT be displayed on the label
  7. The use and placement of a logo is at NZ Post’s absolute discretion. NZ Post may decide not to apply a logo or may remove a logo at any time, for any reason, including where it believes such a logo may damage or diminish the reputation of NZ Post.

Reviews