NZ Post API Case Study


The online team at New Zealand Post run a very interesting blog called Postmodern. They wrote an article about us, which we have reproduced for you below. The original is here.

We’re very grateful to Andy Abel at Need a Part for taking the time to talk to us about their experience with the APIs, and for giving us some pointers on where we could improve.

What does Need a Part do?

Primarily we’re an online shop, selling bits and pieces for household appliances. We deal in consumable items like vacuum bags and shaver heads, as well as simple parts like coffee machine seals, microwave plates and blender jugs. Our aim is to make parts and consumables more accessible to New Zealanders.


The Need a Part team, Andy Abel (left) and Jared Tasker (right).

What cart software are you using or did you build one yourself?

We built one ourselves. Our website has some fairly unique features, and we felt it was easier to build what we wanted than to customise someone else’s code.

Which NZ Post APIs do you use? What do you use them for?

I’m pretty sure we use nearly all of them!

Most integral to our operation is the Label API, which allows us to generate courier tickets on-the-fly during the dispatch process. For international orders we use the Ratefinder APIto ensure we’re using the correct product. [editors note: if you’d like information on the Label API please email us at]

All of the other APIs are used on the front-end to make the checkout process as simple as possible. We use the Address Suggest API in conjunction with the Address Details API to make filling out forms easier  [editors note: these are currently in closed beta]. We use theTracking API and Tracking Notification API to keep customers up to date with their orders.

Do you use other APIs?

The only other one we use is Google’s Map API. When used with data from the Address Details API, we can plot delivery locations on a map.

What have you found the advantages of using the APIs to be?

The Label API allows us to run the dispatch process entirely from our own system.RedClick is a great piece of software, but with the API we don’t have to worry about transferring data between programs, making the process that little bit smoother.

The APIs we use on the frontend allow us to vastly improve user experience. Nobody likes filling out forms, so we use the Address Suggest API to help with that. Once an address has been selected, we use the the Address Details API to return us the coordinates. We can then plot the delivery address on a map, which gives the user confidence that we’ve got their details right. Our target audience includes many people who may not have made an online purchase before, so we try to make them as comfortable as possible.


We’ve recently started using the Tracking Notification API to send an email to the customer when a delivery scan is reported. We were regularly getting calls from customers who claimed that a package hadn’t been delivered, only to find that someone else in the household had received it and not told them. Since we started the delivery notification emails we hardly ever get those calls!

What advice do you have for someone integrating the Post APIs into their own applications?

We don’t really have much advice, because they’re so easy to use. The documentation is good, and for those edge cases you can always get great advice from the team. We definitely owe Stuart a bottle of wine this Christmas!

What would you like to see changed in the Post APIs? Is there anything we could do that would make it easier/better for you?

Perhaps not in the APIs as such, but in the way the data is used. When a parcel goes missing, we ring up the call centre and they always ask, ‘Do you have 15 minutes to go through the claims process?’

That 15 minutes is spent asking us for information that has already been provided via the API. Evidently NZ Post has that information, but for some reason it is not shared with all departments. We challenge NZ Post to make your data work for you!

[editors note: point taken, and we’ll look at what we can do to make this less painful by using the data we already have.]

Anything else you’d like to add?

Earlier this year we discovered a bug in the Label API, where some inner-city postcodes were being charged a Rural Delivery fee. Our proposed solution was implemented extremely quickly. This is very reassuring!

Find out more

You can find Need a Part’s website at You can find out more about the New Zealand Post APIs at the developer centre. If you’re interesting in using the Label API please email us at – you’ll need to be have a New Zealand Post credit account to use the Label API.

Share on FacebookShare on Google+Tweet about this on TwitterEmail this to someone