ShippingOptions API

ShippingOptions API – Domestic (POST)

Resource URLs

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

Description

Use this endpoint to retrieve available shipping options for one or more parcels sent within New Zealand, from a pickup location to a delivery location.

This is a full replacement for the legacy GET endpoint and supports multi‑parcel input and consignment pricing (pricing a group of parcels together).

This endpoint supports sending just a single parcel (similar to the GET endpoint).

Note for Oversize by Fliway: multi-item pricing is only valid if you have been specifically onboarded. If you are not onboarded only submit items one-by-one for Oversize by Fliway.

Contact your Business manager for more information or if you would like to be onboarded.

Resource Information

HTTP Headers

Send the following headers with your requests:

Authorization: Bearer <your_access_token>
Content-Type: application/json
Accept: application/json

Request

Overview

Post a JSON body containing your account, pickup, delivery, and an array of parcels.

See below for a full input JSON payload.

Units:

• weight in kilograms (kg) up to 3 decimal places
• dimensions in centimetres (cm) as integers.

JSON schema (by section)

account_information (object) – required

pickup (object) – required

Provide exactly one of the following methods (free‑form, address_id, dpid, or site_code). It is valid to use different methods for pickup vs delivery.

Free‑form requires: suburb, city, and postcode (4 digits).

delivery (object) – required

Same rules as pickup. Use exactly one method; free‑form requires suburb, city, postcode.

parcels (array) – required (min 1)

If sending a regular parcel, send weight, length, width, and height.

If you require Express (Pace) pricing, you may optionally add quantity (number of identical items).

If sending an envelope (Trackpak), you can send just envelope_size (omit weight/ dimensions).

It is valid to provide both physical dimensions and envelope_size to get all possible shipping options.

Envelope Sizes

Sample Request

The following is a request for two items to be sent from Karori in Wellington to Petone in Lower Hutt.

The request is eligible for all our service types: CourierPost, Pace (Express), and Oversize by Fliway.

Be sure to include your own account_information.account_number, and either your account_information.auth_code or account_information.site_code.

This is needed to retrieve rates for your account, and to authenticate your request.

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

{
  "account_information": {
    "account_number": "12345678",
    "auth_code": "3U16B57B"
  },
  "delivery": {
    "city": "Wellington",
    "postcode": "6012",
    "suburb": "Karori"
  },
  "pickup": {
    "city": "Lower Hutt",
    "postcode": "5012",
    "suburb": "Petone"
  },
  "parcels": [
    {
      "length": 30,
      "width": 30,
      "weight": 28.489,
      "height": 30
    },
    {
      "length": 10,
      "width": 30,
      "weight": 12.4,
      "height": 30,
      "quantity": 2
    }
  ]
}

Business Rules

BR1 – Customer identification

Include account_information.account_number and one of auth_code or site_code.These values must match your account or the call will fail authorization.

BR2 – Address method exclusivity

Each of pickup and delivery must use exactly one method:

• Free‑form (suburb, city, postcode) or
• address_id or
• dpid or
• site_code

Pickup and delivery may use different methods.

BR3 – Parcel dimensions

For each parcel, supply either:

• weight (kg), length (cm), width (cm), height (cm), or
• envelope_size.

You may include both to receive all eligible options for that parcel.

BR4 – Express (Pace) availability

Express (Pace) appears under consignment_priced when eligible.

Express (Pace) services are available for:

• Auckland
• Hamilton
• Tauranga
• Palmerston North
• Napier/Hastings
• New Plymouth
• Wellington
• Nelson
• Christchurch
• Queenstown
• Dunedin

Express (Pace) services will only be returned if the locations provided are eligible.For further information about the Express (Pace) service please click this link: http://www.pace.co.nz/services.

BR5 – Oversize by Fliway availability

If your request is eligible for Oversize by Fliway it will be included in the consignment_priced array in the response.

Oversize by Fliway is only valid for specific dimensions of parcels, so if it is not in the response then your request is not eligible.For further about the Oversize by Fliway service please click this link: https://www.nzpost.co.nz/about-us/oversize-by-fliway.

Use-Cases

CourierPost

CourierPost is the standard service for shipping most items within New Zealand.

If you wish to use CourierPost, then use any of the services within the parcel_priced array.

This service is individually (parcel) priced. That means each item is priced separately.

The carrier field will always be CourierPost for this service.

Express (Pace)

Express (Pace) is a same-day delivery service.

Availability depends on the pickup and send location (see above for more information).

If you wish to use Express (Pace), then look for a Pace service in the consignment_priced part of the response.

Note that the service returned is priced for the entire consignment, and the price applies to shipping all parcels together.

The carrier field will always be Pace for this service.

Oversize by Fliway

Oversize by Fliway is a service to ship oversize items within New Zealand.

If you wish to use Oversize by Fliway, then look for a Fliway service in the consignment_priced part of the response.

This is similar to Express (Pace) in that it is also consignment priced.

The price you see is to ship all items within your request together.

The carrier field will always be Fliway for this service.

Note for Oversize by Fliway: multi-item pricing is only valid if you have been specifically onboarded. If you are not onboarded only submit items one-by-one for Oversize by Fliway.

Contact your Business manager for more information or if you would like to be onboarded.

Response

The following describes the fields that are returned in the JSON response from the API.

See below for a full response JSON payload.

Top-level fields

parcel_priced (array of objects)

consignment_priced (array of service objects)

Services priced for all items together (Express (Pace), Oversize by Fliway).

service object (used in both arrays)

addon object (entries in top‑level addons)

Add-on information is contained in this array.

Each service can have one of more-addons, and you can do a lookup in this list to find more information on those addons.

Pricing model indicates whether an add‑on is charged once per consignment or per for each parcel that uses the addon.

As a worked example consider the response payload below. It is for two parcels.

If you send them both via CourierPost and use addon CPSR for those parcels, this addon would be charged only once for the entire consignment, regardless of the number of parcels that use that addon.

However, if you used addon CPOLDG for both parcels, you would be charged twice for this addon.

Sample Responses

Success (similar services are removed for brevity)

This response is for two items, and the request is eligible for all services of CourierPost, Express (Pace), and Oversize by Fliway.

{
  "success": true,
  "message_id": "0e4efab0-0d39-11f1-9185-06e40fb7cdb1",
  "parcel_priced": [
    {
      "index": 0,
      "rated_weight": 80,
      "services": [
        {
          "carrier": "CourierPost",
          "description": "Courier Parcel",
          "service_code": "CPOLP",
          "price_excluding_gst": 15.16,
          "price_including_gst": 17.43,
          "surcharge_excluding_gst": 0,
          "surcharge_including_gst": 0,
          "price_and_surcharge_excluding_gst": 15.16,
          "price_and_surcharge_including_gst": 17.43,
          "service_standard": "Next working day - delivery to remote or rural area's may take longer",
          "tracking_included": true,
          "signature_included": false,
          "mandatory_addons": [
            "CPOLRD"
          ],
          "optional_addons": [
            "CPSR",
            "CPOLDG"
          ]
        },
        {
          "carrier": "CourierPost",
          "description": "Freight Forward Overnight",
          "service_code": "CFF",
          "price_excluding_gst": 26.75,
          "price_including_gst": 30.76,
          "surcharge_excluding_gst": 0,
          "surcharge_including_gst": 0,
          "price_and_surcharge_excluding_gst": 26.75,
          "price_and_surcharge_including_gst": 30.76,
          "service_standard": "Next working day - delivery to remote or rural area's may take longer",
          "tracking_included": true,
          "signature_included": false,
          "mandatory_addons": [],
          "optional_addons": []
        }
      ]
    },
    {
      "index": 1,
      "rated_weight": 2,
      "services": [
        {
          "carrier": "CourierPost",
          "description": "Courier Parcel",
          "service_code": "CPOLP",
          "price_excluding_gst": 3.79,
          "price_including_gst": 4.36,
          "surcharge_excluding_gst": 0,
          "surcharge_including_gst": 0,
          "price_and_surcharge_excluding_gst": 3.79,
          "price_and_surcharge_including_gst": 4.36,
          "service_standard": "Next working day - delivery to remote or rural area's may take longer",
          "tracking_included": true,
          "signature_included": false,
          "mandatory_addons": [
            "CPOLRD"
          ],
          "optional_addons": [
            "CPSR",
            "CPOLDG"
          ]
        },
        {
          "carrier": "CourierPost",
          "description": "Freight Forward Overnight",
          "service_code": "CFF",
          "price_excluding_gst": 6.69,
          "price_including_gst": 7.69,
          "surcharge_excluding_gst": 0,
          "surcharge_including_gst": 0,
          "price_and_surcharge_excluding_gst": 6.69,
          "price_and_surcharge_including_gst": 7.69,
          "service_standard": "Next working day - delivery to remote or rural area's may take longer",
          "tracking_included": true,
          "signature_included": false,
          "mandatory_addons": [],
          "optional_addons": []
        }
      ]
    }
  ],
  "consignment_priced": [
    {
      "carrier": "Fliway",
      "description": "Oversize by Fliway",
      "service_code": "FLWY",
      "quantity": 2,
      "total_rated_weight": 27,
      "total_rated_volume": 0.4004,
      "price_excluding_gst": 44.52,
      "price_including_gst": 51.2,
      "tracking_included": true,
      "signature_included": false,
      "mandatory_addons": [],
      "optional_addons": [
        "FLHD"
      ]
    },
    {
      "carrier": "Pace",
      "description": "PRIORITY 3 HOUR WLG",
      "service_code": "3HRW",
      "quantity": 2,
      "total_rated_weight": 27,
      "price_excluding_gst": 35.27,
      "price_including_gst": 40.56,
      "estimated_delivery_time": "180",
      "service_standard": "180 minutes",
      "tracking_included": true,
      "signature_included": true,
      "mandatory_addons": [],
      "optional_addons": []
    }
  ],
  "addons": [
    {
      "description": "Courier Dangerous Goods add-on",
      "addon_code": "CPOLDG",
      "price_excluding_gst": 6.5,
      "price_including_gst": 7.48,
      "surcharge_excluding_gst": 0,
      "surcharge_including_gst": 0,
      "price_and_surcharge_excluding_gst": 6.5,
      "price_and_surcharge_including_gst": 7.48,
      "pricing_model": "parcel"
    },
    {
      "description": "Courier Rural Delivery add-on",
      "addon_code": "CPOLRD",
      "price_excluding_gst": 4.67,
      "price_including_gst": 5.37,
      "surcharge_excluding_gst": 0,
      "surcharge_including_gst": 0,
      "price_and_surcharge_excluding_gst": 4.67,
      "price_and_surcharge_including_gst": 5.37,
      "pricing_model": "parcel"
    },
    {
      "description": "Courier Signature Required add-on",
      "addon_code": "CPSR",
      "price_excluding_gst": 0.75,
      "price_including_gst": 0.86,
      "surcharge_excluding_gst": 0,
      "surcharge_including_gst": 0,
      "price_and_surcharge_excluding_gst": 0.75,
      "price_and_surcharge_including_gst": 0.86,
      "pricing_model": "consignment"
    },
    {
      "description": "Home Delivery ",
      "addon_code": "FLHD",
      "price_excluding_gst": 0,
      "price_including_gst": 0,
      "surcharge_excluding_gst": 0,
      "surcharge_including_gst": 0,
      "price_and_surcharge_excluding_gst": 0,
      "price_and_surcharge_including_gst": 0,
      "pricing_model": "consignment"
    }
  ]
}

Error responses

Note these examples are non-exhaustive, but show the error structure and what types of messages can be returned.

Multiple address methods used:

{
  "success": false,
  "errors": [
    {
      "code": "400003",
      "message": "Non mutually exclusive parameters detected",
      "details": "/delivery/site_code is mutually exclusive with other address information."
    }
  ],
  "message_id": "0bce7910-0851-11f1-8459-02c60b84e957"
}

Missing pickup address:

{
  "success": false,
  "errors": [
    {
      "code": "400001",
      "message": "BAD_REQUEST",
      "details": "No Pickup Address information found. Please specify either /pickup/address_id, /pickup/dpid, /pickup/site_code, /pickup/suburb and /pickup/postcode, /pickup/city and /pickup/postcode."
    }
  ],
  "message_id": "28b4d970-0851-11f1-8459-02c60b84e957"
}

Missing dimension field within a parcel:

{
  "success": false,
  "errors": [
    {
      "code": "400002",
      "message": "Invalid Parameters",
      "details": "/parcels/0 is missing mandatory field width."
    }
  ],
  "message_id": "35e30680-0851-11f1-9aaa-067299d1e813"
}

Empty parcel array:

{
  "success": false,
  "errors": [
    {
      "code": "400002",
      "message": "BAD_REQUEST",
      "details": "/parcels expected minimum item count: 1, found: 0"
    }
  ],
  "message_id": "4d3b2150-0851-11f1-8459-02c60b84e957"
}

HTTP Status Codes & Error Codes

Status codes: 200 Success; 400 Bad request; 401 Unauthorized; 403 Forbidden; 409 Invalid request; 500 System unavailable. (400 messages are customized to describe the request problem.)

Error codes

• 200001 Partial results returned (not all systems responded).
• 200002 All sources responded, data may be incomplete.
• 400001 Parameters missing.
• 400002 Invalid parameters.
• 400003 Non mutually exclusive parameters detected.
• 401001 Unauthorized access, contact administrator.
• 500001 General exception.
• 500002 Systems offline.

Migration: moving from GET → POST

• What changes?
  • Query parameters from GET map to JSON fields in POST (e.g., weight → parcels[0].weight, pickup_city → pickup.city).
  • POST supports multiple parcels per call and consignment pricing (Express (Pace), Oversize by Fliway) in addition to per‑parcel CourierPost pricing.
• What stays the same?
  • Validation rules for address methods, rate limiting, and general error structure & codes.
• Tip: If you currently consume the GET shape, first migrate one path of your app to POST using a single‑parcel request (parity with GET), then enable multi‑parcel and consignment options incrementally.

Sending one item with any provider

If you wish to have similar functionality to the existing GET endpoint and display all services for a single parcel, do the following:

• send only one parcel in your POST request
• extract the services under parcel_priced[0].services
• extract the services under consignment_priced
• combine these two lists, and treat them the same as the current results from the GET endpoint