ShippingOptions API

(0 reviews)

Domestic

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

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

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

Request Parameters

FieldField NameDescriptionMandExample
weightWeightThe physical weight in kilograms of the item being sent. Note: If the carrier is CourierPost, the volumetric weight is calculated from the dimensions of the parcel. The rated weight is the greater of the physical weight provided as a request parameter and the calculated volumetric weight. A large parcel of low weight will have a higher rated weight to account for the amount of space it takes in the delivery vehicle. The rated weight will determine the charges for shipping the parcel.Yes1.2
envelope_sizeEnvelope sizeIf fitting into a Trackpak Envelope indicate TrackPak size or ALL to return shipping options for all envelope sizes. See section "Envelope Sizes" for valid values.NoA4
lengthLengthThe length (cm) of the parcel being sentYes15
diameterDiameterThe diameter (cm) of the parcel being sentY if parcel is tube3
widthWidthThe width (cm) of the parcel being sent.Y if parcel is not a tube7
heightHeightThe height (cm) of the parcel being sentY if parcel is not a tube2
pickup_address_idPickup Address IdA validated address ID used to identify an individual addressNo839750
pickup_site_codePickup Address Site CodeA validated site code used to identify an address where a courier is scheduled for regular pickupsNo79012
pickup_suburbPickup Address SuburbSuburb of the pickup addressNoParnell
pickup_cityPickup Address TownTown of the pickup addressNoAuckland
pickup_postcodePickup Address Post CodePost Code specific to pick up addressNo1052
pickup_dpidPickup Address DPIDA validated DPID used to identify an individual addressN if Pickup AID, Site code or Suburb+Town+Postcode are used914092
delivery_address_idDelivery Address IDA validated address ID used to identify an individual addressNo839750
delivery_site_codeDelivery Address Site CodeA validated site code used to identify an address where a courier is scheduled for regular pickupsNo68521
delivery_suburbDelivery Address SuburbSuburb of the delivery addressNoGlenfield
delivery_cityDelivery Address TownTown of the delivery addressNoAuckland
delivery_postcodeDelivery Address Post CodePost code specific to delivery addressNo0629
delivery_dpidDelivery Address DPIDA validated DPID used to identify an individual addressNo if Delivery AID, Site code or Suburb+Town+Postcode are used839750
account_numberaccount numberYour NZ Post Billing Account number (9 or 5 series).This is highly recommended to pass in the API call to obtain your account ratesNo12345678

Envelope Sizes

Envelope Size CodeEnvelope Size NameDescription
A4A4A4 Trackpak
A4BA4BA4 Bubble Trackpak
A5A5A5 Trackpak
A5BA5BA5 Bubble Trackpak
DLDLDLE Trackpak
FSFSFoolScap Trackpak
LFLFLineFlow Trackpak
CDLCDLEco DLE Trackpak
CA5CA5Eco A5 Trackpak
CFSCFSEco Foolscap Trackpak
XLXLXtra Large Trackpak

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

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
servicesDetails regarding the services applicable to the input parametersYSee Services Details section for response details
rated_weightIf the carrier is CourierPost, the volumetric weight is calculated from the dimensions of the parcel. The rated weight is the greater of the physical weight provided as a request parameter and the calculated volumetric weight. A large parcel of low weight will have a higher rated weight to account for the amount of space it takes in the delivery vehicle. The rated weight will determine the charges for shipping the parcel.Yes1.2
error_listDetails regarding any errors encountered.NoSee Error Response section for details
message_IDUnique ID associated with the requestYesc8853bb7-4b05-4f45-894a-6cff03765c02

Services Details

Field NameDescriptionMandExample
service_codeA service code.YesCPOLP
descriptionDescription of service.YesCP Online Parcel
price_excluding_gstPrice of service excluding GST (2 decimal points).Yes10.00
price_including_gstGST inclusive price of service (2 decimal points).Yes11.50
estimated_delivery_timeAn estimated delivery time for PACE. CourierPost returns null.No30 minutes, 60 minutes, 180 minutes
service_standardIndicates the time that the product will take to be delivered from the time that it is picked up.No“60 Minutes” for Pace,“Overnight” for CourierPost
tracking_includedIndicates whether tracking functionality is included as part of the quoted price.YesTrue
signature_includedIndicates whether a signature is included as part of the quoted price.YesFalse
carrierIndicates the carrier offering the option. The options are CourierPost or PACE.YesCourierPost
add_onsContains a list of add ons applicable to the service.NoSee Add ons Details section for details.

Add ons Details

Field NameDescriptionMandExample
addon_codeAn add on product codeYesCPOLRD
descriptionDescription of add onYesRural Delivery Code
price_excluding_gstPrice of service excluding GST (2 decimal points)Yes1.86
price_including_gstGST inclusive price of service (2 decimal points)Yes2.14
mandatoryIndicates if the add on must be selected as part of the service.YesTrue

Rated Weight Details

Field NameDescriptionMandExample
rated_weightIndicates value the Merchant will be billed.No6

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorCould not calculate volume for a box. Missing or invalid Height, Length or Width.

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

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned, not all system(s) have responded
200002All sources responded, data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

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
                                }
                           ]
              }
       ],
   "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."
   }]
}

Reviews