ShippingOptions API
International
Resource URL
UAT:
https://api.uat.nzpost.co.nz/shippingoptions/2.0/internationalhttps://api.nzpost.co.nz/shippingoptions/2.0/internationalResource 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
Retails services country specific restrictions
Sample Request
https://api.uat.nzpost.co.nz/shippingoptions/2.0/international?value=100&country_code=BE&length=10&height=10&width=10&weight=10&documents=&account_number=12345678Response 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 |
| service_cost_breakdown | Service cost breakdown for each service based on cms_code | Yes | Please refer Service cost breakdown page Service cost breakdown for more details |
| customs_charges_options | Customs charges options available for the service | Yes | Please refer Customs charges options Customs charges options page for more details |
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": "16f52b10-9136-11f1-a81b-06a6a287bad2",
"services": [
{
"service_code": "ICOU7",
"description": "Courier Thermal",
"min_delivery_target": 2,
"max_delivery_target": 6,
"tracking_included": true,
"signature_included": true,
"channel": "Account",
"price_excluding_gst": 380.75,
"price_including_gst": 380.75,
"cms_code": "ICOUPD10,ISURCOUD",
"service_cost_breakdown": [
{
"cms_code": "ICOUPD10",
"type": "product",
"price": 363.85
},
{
"cms_code": "ISURCOUD",
"type": "surcharge",
"price": 16.9
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "ICOU",
"description": "Courier",
"min_delivery_target": 2,
"max_delivery_target": 6,
"tracking_included": true,
"signature_included": true,
"channel": "Account",
"price_excluding_gst": 380.75,
"price_including_gst": 380.75,
"cms_code": "ICOUPD10,ISURCOUD",
"service_cost_breakdown": [
{
"cms_code": "ICOUPD10",
"type": "product",
"price": 363.85
},
{
"cms_code": "ISURCOUD",
"type": "surcharge",
"price": 16.9
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IECOP",
"description": "Economy Plus",
"min_delivery_target": 3,
"max_delivery_target": 10,
"tracking_included": true,
"signature_included": false,
"channel": "Account",
"price_excluding_gst": 361.76,
"price_including_gst": 361.76,
"cms_code": "IECOPD10,ISURECOPD",
"service_cost_breakdown": [
{
"cms_code": "IECOPD10",
"type": "product",
"price": 344.86
},
{
"cms_code": "ISURECOPD",
"type": "surcharge",
"price": 16.9
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IEXP7",
"description": "Express",
"min_delivery_target": 1,
"max_delivery_target": 5,
"tracking_included": true,
"signature_included": true,
"channel": "Account",
"price_excluding_gst": 627.57,
"price_including_gst": 627.57,
"cms_code": "IEXPPD10",
"service_cost_breakdown": [
{
"cms_code": "IEXPPD10",
"type": "product",
"price": 627.57
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IEXP",
"description": "Express",
"min_delivery_target": 1,
"max_delivery_target": 5,
"tracking_included": true,
"signature_included": true,
"channel": "Account",
"price_excluding_gst": 748.05,
"price_including_gst": 748.05,
"cms_code": "IEXPPD10,IBCLLV,ISUREXPD",
"service_cost_breakdown": [
{
"cms_code": "IEXPPD10",
"type": "product",
"price": 627.57
},
{
"cms_code": "IBCLLV",
"type": "surcharge",
"price": 2.48
},
{
"cms_code": "ISUREXPD",
"type": "surcharge",
"price": 118
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
}
]
},
{
"service_code": "IOCOU",
"description": "Courier",
"min_delivery_target": 2,
"max_delivery_target": 6,
"tracking_included": true,
"signature_included": true,
"channel": "Online",
"price_excluding_gst": 370.41,
"price_including_gst": 370.41,
"cms_code": "IOCOUPD40",
"service_cost_breakdown": [
{
"cms_code": "IOCOUPD40",
"type": "product",
"price": 370.41
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IOECOP",
"description": "Economy Plus",
"min_delivery_target": 3,
"max_delivery_target": 10,
"tracking_included": true,
"signature_included": false,
"channel": "Online",
"price_excluding_gst": 336.76,
"price_including_gst": 336.76,
"cms_code": "IOECOPD",
"service_cost_breakdown": [
{
"cms_code": "IOECOPD",
"type": "product",
"price": 336.76
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IOEXP",
"description": "Express",
"min_delivery_target": 1,
"max_delivery_target": 5,
"tracking_included": true,
"signature_included": true,
"channel": "Online",
"price_excluding_gst": 655.68,
"price_including_gst": 655.68,
"cms_code": "IOEXPPD30",
"service_cost_breakdown": [
{
"cms_code": "IOEXPPD30",
"type": "product",
"price": 655.68
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
}
]
},
{
"service_code": "IRCOU7",
"description": "Courier",
"min_delivery_target": 2,
"max_delivery_target": 6,
"tracking_included": true,
"signature_included": true,
"channel": "Retail",
"price_excluding_gst": 370.41,
"price_including_gst": 370.41,
"cms_code": "IRCOUPD40",
"service_cost_breakdown": [
{
"cms_code": "IRCOUPD40",
"type": "product",
"price": 370.41
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IRECOP",
"description": "Economy Plus",
"min_delivery_target": 3,
"max_delivery_target": 10,
"tracking_included": true,
"signature_included": false,
"channel": "Retail",
"price_excluding_gst": 336.76,
"price_including_gst": 336.76,
"cms_code": "IRECOPD20",
"service_cost_breakdown": [
{
"cms_code": "IRECOPD20",
"type": "product",
"price": 336.76
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
},
{
"incoterm": "DDP",
"methods": [
"TAX_NZP_REMIT",
"TAX_SENDER_REMIT"
]
}
]
},
{
"service_code": "IREXP",
"description": "Express",
"min_delivery_target": 1,
"max_delivery_target": 2,
"tracking_included": true,
"signature_included": true,
"channel": "Retail",
"price_excluding_gst": 655.68,
"price_including_gst": 655.68,
"cms_code": "IREXPPD30",
"service_cost_breakdown": [
{
"cms_code": "IREXPPD30",
"type": "product",
"price": 655.68
}
],
"customs_charges_options": [
{
"incoterm": "DAP",
"methods": [
"COLLECT_FROM_RECEIVER"
]
}
]
}
]
}
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"
}