Resource URL
UAT:
https://api.uat.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/status
Production:
https://api.nzpost.co.nz/parcellabel/v3/labels/{consignment_id}/status
Resource Description
Returns the status of all labels within a consignment.
Note if webhook URL is not provided in the request for label generation, you will need to call the Status resource to get the status of the labels within a consignment.
| Attribute |
Detail |
| Response Format |
JSON |
| Requires Authentication |
Yes |
| Rate Limited |
30 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Request Parameters
| Field Name |
Description |
Mandatory |
Example |
| consignment_id |
Unique id of a consignment |
Yes |
CLV27N |
Sample Request
https://api.nzpost.co.nz/parcellabel/v3/labels/CLV27N/status
Response Parameters
| Field Name |
Description |
Mandatory |
Example |
| consignment_id |
Unique id of a consignment |
Yes |
CLV27N |
| consignment_status |
Status of the consignment. See Consignment Status Values. |
Yes |
Complete |
| consignment_url |
Download URL for the consignment, in format PDF. |
Yes if the status of the consignment is Complete |
https://api.nzpost.co.nz/parcellabel/v3/labels/CLV27N?format=PDF |
| errors |
An array containing the error details. See Errors Object Parameters. |
Yes if request is unsuccessful |
JSON Array |
| expiry_date_utc |
Date the label expires in UTC format. |
No |
2019-09-17T12:00:00Z |
| labels |
An array containing the status of each label in the consignment. See Labels Object Parameters. |
Yes |
JSON Array |
| message_id |
A unique id for the API call. |
Yes |
293e9e80-9305-11e9-a34b-0647d8507b90 |
| page_urls |
An array containing the download URLs for each page in the consignment, in format PNG. |
No |
https://api.nzpost.co.nz/parcellabel/v3/labels/CLV27N?format=PNG&page=1 |
| success |
Flag indicating success or failure of the request. Value is true or false. |
Yes |
true |
Labels Object Parameters
| Field Name |
Description |
Mandatory |
Example |
| label_id |
Unique identifier for the label. |
Yes |
CLV27N-1 |
| tracking_reference |
Tracking reference for the label |
Yes |
8963063547000301AKL004AN |
| label_generation_status |
Generation status of the label. See Label Status List below. |
Yes |
Complete |
| errors |
An array containing the error details. See Errors Object Parameters. |
Yes if request is unsuccessful |
JSON Array |
Consignment Status Values
| Status |
Definition |
| Accepted |
ParcelLabel Request has been received into NZ Post Group systems |
| Processing |
ParcelLabel Request has passed all validation and has been passed to the Label Generator |
| Complete |
Label Rendering has successfully created an image of all the labels |
| Complete with warnings |
All label images have been generated successfully but the merchant logo was not able to be put into the label image. |
| Failed |
The Label Rendering has failed to create an image for at least one label |
Errors Object Parameters
| Field Name |
Description |
Example |
| code |
Error code where first 3 digits are http status code, last three digits identify error type |
400002 |
| message |
Description of error code |
Invalid Parameter(s) |
| details |
Description of specific error |
Carrier is a mandatory field. |
Sample Response
