ShippingOptions API

ShippingOptions API

(0 reviews)


Resource URL


Resource Description

The international method is used to retrieve a list of valid shipping options available for a delivery address outside of New Zealand.

Resource Information

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
country_codeCountry CodeThe destination country code of the package. Value must be in upper caseYesAU
valueValueApproximate commercial value in NZ dollarsYes9.50
lengthLengthLength of package (mm)Yes250
heightHeightHeight of the package (mm)Yes (if parcel is not a tube)150
widthWidthWidth of the package (mm)Yes (if parcel is not a tube)50
diameterDiameterDiameter of the package (mm)Yes (if parcel is tube)55
weightWeightPackage weight in kgYes1.2
promo_codePromo CodeNZ Post promotional codeNoXYZ001
formatFormatThe format of the responseYesjson
documentsDocumentsInclude document package types in results. Use "include" to include document types. Use "only" to return only document types. Leave blank to exclude document typesNoInclude

Sample Request

Response Parameters

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
servicesArray listing applicable service codesYesSee Services Object section below

Services Object Parameters

Field NameDescriptionMandExample
service_codeNZ Post code specifying serviceYesTIEX
descriptionDescription of service codeYesInt Express Pcl Zone A 13.0kg
price_excluding_gstPrice excluding GSTYes191.86
price_including_gstPrice with GSTYes220.64
min_delivery_targetThe minimum expected delivery timeYes1
max_delivery_targetThe maximum expected delivery timeYes5
tracking_includedBoolean indication tracking is included in serviceYestrue
signature_includedBoolean indication signature is included in serviceYestrue

Products available (and their prices) are contained in an array within the 'products' node.

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
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 errorCountry code is not a supported country code

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

400Bad request
409Invalid request
500System unavailable

Error Codes

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":    [
         "service_code": "TIEX",
         "description": "Int Express Pcl Zone A 13.0kg",
         "price_excluding_gst": 191.86,
         "price_including_gst": 220.64,
         "min_delivery_target": 1,
         "max_delivery_target": 5,
         "tracking_included": true,
         "signature_included": true
         "service_code": "TIEC",
         "description": "Int Econ Cour Pcl Zn A 13.0kg",
         "price_excluding_gst": 120.66,
         "price_including_gst": 138.76,
         "min_delivery_target": 2,
         "max_delivery_target": 6,
         "tracking_included": true,
         "signature_included": true
         "service_code": "TIALP",
         "description": "Zone A AirPost Cust Pcl 13.0kg",
         "price_excluding_gst": 105.18,
         "price_including_gst": 120.96,
         "min_delivery_target": 3,
         "max_delivery_target": 10,
         "tracking_included": false,
         "signature_included": false

Sample of failure message:

   "success": false,
   "errors": [   {
      "code": "400002",
      "message": "Invalid Parameter",
      "details": "Country code is not a supported country code"
   "message_id": "a1129930-0d7a-11e5-b1ba-06132e0eed7f"