ShippingOptions API

(0 reviews)

International

Resource URL

UAT:

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

Production:

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

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

Attribute	Detail
Response Format	JSON
Requires Authentication	Yes
Rate Limited	15 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

Field	Field Name	Description	Mand	Example
country_code	Country Code	The destination country code of the package. Value must be in upper case	Yes	AU
value	Value	Approximate commercial value in NZ dollars	Yes	9.50
length	Length	Length of package (mm)	Yes	250
height	Height	Height of the package (mm)	Yes (if parcel is not a tube)	150
width	Width	Width of the package (mm)	Yes (if parcel is not a tube)	50
diameter	Diameter	Diameter of the package (mm)	Yes (if parcel is tube)	55
weight	Weight	Package weight in kg	Yes	1.2
promo_code	Promo Code	NZ Post promotional code	No	XYZ001
format	Format	The format of the response	Yes	json
documents	Documents	Include document package types in results. Use "include" to include document types. Use "only" to return only document types. Leave blank to exclude document types	No	Include
account_number	Account Number	Your NZ Post Billing Account number (9 or 5 series). This is highly recommended to pass in the API call to obtain your account rates	No	12345678
channel	Account	This is highly recommended to pass in the API call to obtain the service codes that are appropriate for you to access our services	No	Online,Offshore,Account or ETOE
service_code	Service Code	Code to represent a delivery service. This is highly recommended to get service and country specific validations	No	ICOU
postcode	Postcode	Postal or zip code of the Box or Bag location	No	1142
insurance_required	Insurance Required	Indicates whether insurance is required for the parcel	No	true
pickup_country_code	Pickup Country Code	Two letter country code of pickup_address. Only required for Saudi post labels (GoSPL) service	No	NZ
location_type	Location Type	Type of delivery location requested for the item. Only required for Saudi post labels (GoSPL) service	No	HOM

Shipping Options Country Specific Validations

To support AusPost-Courier International/EMS requirements, below country specific restrictions have been added for some services

resources/SO_CountrySpecificValues-fec5c53f-be6a-4600-b1db-27d0176667f7.PNG

Retails services country specific restrictions

resources/RetailsServiceCodesCountrySpecificValidations-b1386a16-b227-4a32-8a7b-3a23f9c4262a.JPG

Sample Request

https://api.uat.nzpost.co.nz/shippingoptions/2.0/international?value=100&country_code=AU&length=10&height=10&width=10&weight=10&documents=&account_number=12345678

Response Parameters

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	True
services	Array listing applicable service codes and rates	Yes	See Services Object section below

Services Object Parameters

Field Name	Description	Mand	Example
service_code	NZ Post code specifying service	Yes	TIEX
description	Description of service code	Yes	Int Express Pcl Zone A 13.0kg
min_delivery_target	The minimum expected delivery time	Yes	1
max_delivery_target	The maximum expected delivery time	Yes	5
tracking_included	Boolean indication tracking is included in service	Yes	true
signature_included	Boolean indication signature is included in service	Yes	true
price_excluding_gst	Price excluding GST	Yes	191.86
price_including_gst	Price with GST	Yes	220.64
cms_code	This is the product code that will show on your invoice if you use this service with the parameters you have provided in the API call	Yes	IACNA10

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

Error Response Elements

Field Name	Description	Mand	Example
success	Returns if request is successful	Yes	True
errors	Error object with error details	Y if success =false	See Error Object Parameters below
message_id	The unique message identifier	Yes	ec608f40-2a8b-11e5-a9c0-025c481d35ef

Error 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	Country 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

Code	Message
200	Success
400	Bad request
401	Unautorized
403	Forbidden
409	Invalid request
500	System unavailable

Error Codes

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

Sample Response

Sample of success message:


 {
  "success": true,
  "contract_rates": true,
  "message_id": "ec76ef20-6347-11ef-abf9-064f0484fceb",
  "products": [
    {
      "code": "IECOPA2",
      "cms_code": "IECOPA2",
      "service_code": "IECOP",
      "name": "Economy Plus",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": true,
      "signature_required": false,
      "special_arrangements": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IECOPA2",
      "cms_code": "IECOPA2",
      "service_code": "IECOP7",
      "name": "Economy Plus Thermal",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "special_arrangements": true,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IECOPRESA5",
      "cms_code": "IECOPRESA5",
      "service_code": "IECOPRES",
      "name": "Economy Plus Restricted",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "special_arrangements": true,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IECOTA500",
      "cms_code": "IECOTA500",
      "service_code": "IECOT",
      "name": "Economy Tracked",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": true,
      "signature_required": false,
      "special_arrangements": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IEECONOUKAU",
      "cms_code": "IEECONOUKAU",
      "service_code": "IEECONOUK",
      "name": "ETOE Untracked UK -ORG",
      "channel": "ETOE",
      "group": "My Service Group",
      "min_delivery_target": 4,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "special_arrangements": true,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IEECONUSAU",
      "cms_code": "IEECONUSAU",
      "service_code": "IEECONUS",
      "name": "ETOE US Semi-tracked packet",
      "channel": "ETOE",
      "group": "My Service Group",
      "min_delivery_target": 4,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "special_arrangements": true,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IEXPPA1",
      "cms_code": "IEXPPA1",
      "service_code": "IEXP",
      "name": "Express",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 1,
      "max_delivery_target": 5,
      "has_tracking": true,
      "signature_required": true,
      "special_arrangements": false,
      "weight": 0.56,
      "promo_code": ""
    },
    {
      "code": "IEXPPA500",
      "cms_code": "IEXPPA500",
      "service_code": "IEXP7",
      "name": "Express",
      "channel": "Account",
      "group": "My Service Group",
      "min_delivery_target": 1,
      "max_delivery_target": 5,
      "has_tracking": true,
      "signature_required": true,
      "special_arrangements": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IHCOUPIAAU",
      "cms_code": "IHCOUPIAAU",
      "service_code": "IHCOU",
      "name": "Hubbed - Courier",
      "channel": "Hubbed",
      "group": "My Service Group",
      "min_delivery_target": 2,
      "max_delivery_target": 6,
      "has_tracking": true,
      "signature_required": true,
      "special_arrangements": true,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IOCOUPA40",
      "cms_code": "IOCOUPA40",
      "service_code": "IOCOU",
      "name": "Courier",
      "channel": "Online",
      "group": "My Service Group",
      "min_delivery_target": 2,
      "max_delivery_target": 6,
      "has_tracking": true,
      "signature_required": true,
      "special_arrangements": false,
      "weight": 0.56,
      "promo_code": ""
    },
    {
      "code": "IOECOA",
      "cms_code": "IOECOA",
      "service_code": "IOECO",
      "name": "Economy",
      "channel": "Online",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "special_arrangements": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IOECOPA",
      "cms_code": "IOECOPA",
      "service_code": "IOECOP",
      "name": "Economy Plus",
      "channel": "Online",
      "group": "My Service Group",
      "min_delivery_target": 3,
      "max_delivery_target": 10,
      "has_tracking": true,
      "signature_required": false,
      "special_arrangements": false,
      "weight": 0.56,
      "promo_code": ""
    },
    {
      "code": "IREXPPA30",
      "cms_code": "IREXPPA30",
      "service_code": "IREXP",
      "name": "Express",
      "channel": "Retail",
      "group": "My Service Group",
      "min_delivery_target": 1,
      "max_delivery_target": 2,
      "has_tracking": true,
      "signature_required": true,
      "special_arrangements": false,
      "weight": 0.08,
      "promo_code": ""
    }
  ],
  "surcharges": [
    {
      "code": "IETEFSGAU",
      "cms_code": "IETEFSGAU",
      "service_code": "IEECONCSG",
      "name": "ETOE Semi-tracked packet SG Alg",
      "channel": "ETOE",
      "group": "My Service Group",
      "min_delivery_target": 4,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IETEFSGAU",
      "cms_code": "IETEFSGAU",
      "service_code": "IEECONSG",
      "name": "ETOE Semi-tracked packet SG Alg",
      "channel": "ETOE",
      "group": "My Service Group",
      "min_delivery_target": 4,
      "max_delivery_target": 10,
      "has_tracking": false,
      "signature_required": false,
      "weight": 0.08,
      "promo_code": ""
    },
    {
      "code": "IETEFUSAU",
      "cms_code": "IETEFUSAU",
      "service_code": "IEECOTUS",
      "name": "ETOE US Tracked packet",
      "channel": "ETOE",
      "group": "My Service Group",
      "min_delivery_target": 4,
      "max_delivery_target": 10,
      "has_tracking": true,
      "signature_required": false,
      "weight": 0.08,
      "promo_code": ""
    }
  ],
  "insuranceCodesFixed": [
  ],
  "insuranceCodesCalculated": [
  ]
}

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"
}