Merchants API setup guide

Summary

The Merchants API can be used to get updates on tracked parcels, in particular for use with the Parcel Collect beta. Find out more about Parcel Collect.

The Merchants API contains all the functionality of the Tracking Notifications API, with the addition of notifications for parcel collections. This includes the initial ‘ready to collect’ notification as well as reminder notifications.

Account setup

To use the Merchants API you will need an API key.

Your account will specify whether or not New Zealand Post will send notifications direct to your customer via email. Either way, notification data will be sent to your nominated webhook URL.

‘Create subscription’ method

To subscribe to notifications for a particular parcel, make an HTTP POST request to the following endpoint:

https://api.nzpost.co.nz/merchants_api/api/v1/subscriptions/create

Use the following parameters in your request:

private_api_key (required)
Your API key will be provided when we create your licence

tpid (required)
The TPID is a unique identifier for your merchant account. It will be given to you along with the API key

tracking_code (required)
The tracking number of the parcel you wish to subscribe to notifications for

receiver_email (required)
The email address of the person receiving the parcel

receiver_first_name (required)
The first name of the person receiving the parcel

receiver_last_name (required)
The last_name of the person receiving the parcel

subscription_category (required)
Specify which events you would like to be notified about. Use either ‘collection’ or ‘all_events’. If you use ‘all_events’, all notifications will be sent to your webhook URL, but email notifications will only be sent for events relating to parcel collection.

collection_location_id (optional)
If the parcel is to be collected, you will need to specify the id of the location. Location ids can be found via the Locator API. For example, Kelburn Four Square has the id 72288. You must specify a collection_location_id if you subscribe to ‘collection’ notifications.

webhook_url (optional)
The URL for receiving notifications. This will override your account default for this subscription. If left blank, notifications will be sent to your account’s default webhook URL.

Collection notifications

A collection reminder notification will be sent 5 days after the initial ‘ready to collect’ notification, and again after 8 days. After 10 days the item is returned to the sender.

Example response from a successful request:

{
  "success": true
}

Example response from an unsuccessful request:

{
  "success": false,
  "error": {
    "code": 400,
    "message": [
      "Receiver first name can't be blank",
      "Receiver last name can't be blank"
     ]
  }
}

Example of a notification posted to webhook:

{
  "message": "Acceptance",
  "tracking_code": "JP230200301NZ",
  "subscription_guid": "200ee4aa-67ac-4795-9901-e2ad3709e18e",
  "event_code": "SHIPPED",
  "occurred_at": "2015-02-09 09:16:43 +1300"
}

Example of a collection notification posted to webhook:

{
  "message": "Parcel is ready to collect",
  "tracking_code": "JP100000286NZ",
  "occurred_at": "2015-02-04 15:58:43 +1300",
  "subscription_guid": "297ffd19-67a2-4eaa-86e1-8085bac0aff9",
  "event_code": "READY_TO_COLLECT",
  "location_data": {
    "location_name": "Wellington-Ngaio Depot",
    "opening_hours":[
      {
        "day": "Monday",
        "open": "08:00",
        "close": "17:00"
      },
      {
        "day": "Tuesday",
        "open": "08:00",
        "close": "17:00"
      },
      {
        "day": "Wednesday",
        "open": "08:00",
        "close": "17:00"
      },
      {
        "day": "Thursday",
        "open": "08:00",
        "close": "17:00"
      },
      {
        "day": "Friday",
        "open": "08:00",
        "close": "17:00"
      },
      {
        "day":"Saturday",
        "closed": true
      },
      {
        "day":"Sunday",
        "closed": true
      }],
    "address_details":{
      "address_line_1": "36 Kaiwharawhara Road",
      "suburb": "Kaiwharawhara",
      "city": "Wellington",
      "post_code": "6035"
    }
  }
}

Example of a collection reminder notification posted to webhook:

{
  "message": "Reminder 2: Parcel is ready to collect",
  "tracking_code": "JP230202069NZ",
  "occurred_at": "2015-02-10T18:01:19.718+13:00",
  "subscription_guid": "0e874f1c-d109-40e0-b78d-2cdc5accf9b4",
  "event_code": "PARCEL_COLLECTION_REMINDER"
}