ShippingOptions API

Resource URL

UAT:

https://api.uat.nzpost.co.nz/shippingoptions/2.0/domestic

Production:

https://api.nzpost.co.nz/shippingoptions/2.0/domestic

Resource Description

The domestic method is used to retrieve a list of valid shipping options available from a pickup address to a delivery address within New Zealand.

Resource Information

Please note that all request parameters should be in lower case.

Request Parameters

Envelope Sizes

Sample Request

https://api.nzpost.co.nz/shippingoptions/2.0/domestic?weight=10&length=10&width=10&height=10&pickup_address_id=990003&delivery_dpid=2727895

Business Rules

The following business rules are applied on each /domestic request:

BR001 Valid combinations of envelope size and dimensions are as follows:

Envelope size with length, width and height or

Envelope size with length and diameter or

Length, width and height or

Length and diameter

BR002 Address information must include one and only one of the following options:

• Address_id or
• DPID or
• Site_code or
• Suburb, city and postcode

BR003 Paces services are available for Auckland, Palmerston North, Napier/Hastings, Wellington, Christchurch, and Dunedin. If Pace services are not available for the addresses offered in the API request no Pace options will be returned.

For further information about Pace service please click on this link: http://www.pace.co.nz/services.

Response Parameters

Services Details

Add ons Details

Rated Weight Details

Error Response Elements

Error Object Parameters

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

Error Codes

Sample Response

Sample of success message:

{
    "success": true,
    "services": [
        {
            "carrier": "Pace",
            "description": "3 HOUR SERVICE AUCKLAND",
            "service_code": "3HRA",
            "price_excluding_gst": 30.09,
            "price_including_gst": 34.6,
            "estimated_delivery_time": "180",
            "service_standard": "180 Minutes",
            "tracking_included": true,
            "signature_included": true,
            "addons": []
        },
        {
            "carrier": "CourierPost",
            "description": "CP Online Parcel",
            "service_code": "CPOLP",
            "price_excluding_gst": 2.44,
            "price_including_gst": 2.81,
            "estimated_delivery_time": null,
            "service_standard": "Overnight",
            "tracking_included": true,
            "signature_included": false,
            "addons": [
                {
                    "description": "CP Online Sig Rq",
                    "addon_code": "CPSR",
                    "mandatory": false,
                    "price_excluding_gst": 0.29,
                    "price_including_gst": 0.33
                },
                {
                    "description": "CP Online Rural Delivery",
                    "addon_code": "CPOLRD",
                    "mandatory": true,
                    "price_excluding_gst": 0,
                    "price_including_gst": 0
                }
            ]
        },
        {
            "carrier": "Fliway",
            "description": "Oversize by Fliway",
            "service_code": "FLWY",
            "price_excluding_gst": 34.20,
            "price_including_gst": 39.34,
            "estimated_delivery_time": null,
            "tracking_included": true,
            "signature_included": false,
            "addons": [
                {
                    "description": "Oversize by Fliway Home Delivery add-on",
                    "addon_code": "FLHD",
                    "mandatory": false,
                    "price_excluding_gst": 0.00,
                    "price_including_gst": 0.00,
                    "surcharge": 0.00,
                    "price_including_surcharge_and_gst": 0.00
                }
            ]
        }
    ],
    "rated_weight": 1,
    "message_id": "7b067255-b43c-4ea8-8fdb-0308565b58ad"
}

Sample of partial failure message:

{
    "success": true,
    "errors": [
        {
            "code": "200001",
            "message": "Partial results returned, not all system(s) have responded",
            "details": "There is an issue with retrieving ALL applicable options.  Try again later for all options."
        }
    ],
    "services": [
        {
            "carrier": "CourierPost",
            "description": "CP Online W/Island Contract",
            "service_code": "CPOLCT1",
            "price_excluding_gst": 0,
            "price_including_gst": 0,
            "estimated_delivery_time": null,
            "service_standard": "Next working day - delivery to remote or rural area's may take longer",
            "tracking_included": true,
            "signature_included": false,
            "addons": [
                {
                    "description": "CP Online Sig Rq",
                    "addon_code": "CPSR",
                    "mandatory": false,
                    "price_excluding_gst": 2.08,
                    "price_including_gst": 2.39
                },
                {
                    "description": "CP Online Rural Delivery",
                    "addon_code": "CPOLRD",
                    "mandatory": true,
                    "price_excluding_gst": 2.88,
                    "price_including_gst": 3.31
                }
            ]
        },
        {
            "carrier": "CourierPost",
            "description": "CP Online Parcel",
            "service_code": "CPOLP",
            "price_excluding_gst": 5.56,
            "price_including_gst": 6.39,
            "estimated_delivery_time": null,
            "service_standard": "Next working day - delivery to remote or rural area's may take longer",
            "tracking_included": true,
            "signature_included": false,
            "addons": [
                {
                    "description": "CP Online Sig Rq",
                    "addon_code": "CPSR",
                    "mandatory": false,
                    "price_excluding_gst": 2.08,
                    "price_including_gst": 2.39
                },
                {
                    "description": "CP Online Rural Delivery",
                    "addon_code": "CPOLRD",
                    "mandatory": true,
                    "price_excluding_gst": 2.88,
                    "price_including_gst": 3.31
                }
            ]
        }
    ],
    "rated_weight": 10,
    "message_id": "9d10c19c-3d85-4661-afcb-a292abffc615"
}

Sample of failure message:

{
    "success": false,
    "errors": [
        {
            "code": "400001",
            "message": "Parameter(s) missing",
            "details": "Could not calculate volume for a box. Missing or invalid Height, Length or Width."
        }
    ]
}