1. Documentation /
  2. Extensions /
  3. New Zealand Post Shipping

New Zealand Post Shipping

PLEASE NOTE: This plugin is the product of OPMC and is not associated with New Zealand Post. New Zealand Post is not able to assist with any support or inquiries on this product.  Any customer service requests must be directed only to OPMC.

New Zealand Post is a premium shipping method which let you get shipping rates from the New Zealand Post API. It requires that your store uses NZ Dollars for it’s currency and a base country of New Zealand. The extension primarily works with mm and kgs, but other units can be converted automatically.

This extension can calculate quotes worldwide as it handles both domestic and international parcels.

The API, and the built in box-packer, require that your non-virtual products have weights and dimensions set. See here if you need to know how to do this.

Installation ↑ Back to top

  1. Upload the plugin folder to the ‘/wp-content/plugins/’ directory.
  2. Activate the plugin through the ‘Plugins’ menu in WordPress.
  3. Thats it – you can now configure the plugin.

API & Debug  ↑ Back to top

Go to: WooCommerce > Settings > Shipping > New Zealand Post.

  1. Connect/Disconnect your New Zealand Post Account
  2. Debug Mode – Tick the checkbox to log API requests and responses for the cart and checkout pages. Useful for troubleshooting.
  3. API Key – NZ Post will provide you with an API key after you signup for their API services. Enter this here – it is required.
PLEASE NOTE:  When you need advise of  NZ Post on any NZ Post account related issue, Please specify to NZ Post that you are using Plugin for WooCommerce for their undestanding. This would help them understand to resolve your issue easily.

Configuration ↑ Back to top

  1. Go to: WooCommerce > Settings > Shipping.
  2. Select your Shipping Zone that you want to add the method to, and press the Add shipping method + button on the right
    Add shipping method
  3. Select New Zealand Post from the dropdown and press Add shipping method:
  4. Click on the New Zealand Post method to configure the settings:
    • Method Title – Name the shipping method. This will be visible by customers.
    • Origin Postcode – This should be set to the postcode from which you will ship. It is sent to the NZ Post API. It should match with the Postcode / Zip specified in WooCommerce => Settings => Gereral => Store Address.

Note: The store address specified in general WooCommerce setting is an important part that affects several WooCommerce features, so it should be mentioned correctly. The user should also make sure that their store address is available in NZ Post API database. If not, then they must request to get their store address added into NZ Post API database

    • Method Availability –  This setting lets you narrow down the countries which can get quotes. Leave set to All Countries to have it available for all customers.
    • Rates and Services – These settings control the services and rates you offer customers.
      • Parcel Packing Method – See below.
      • Offer Rates – Choose to return all rates (user will get the choice) or just return a single rate.
      • Services – Here you can rename, and re-order, NZ Post shipping rates.
  1. Add shipping method.


Parcel Packing Method ↑ Back to top

There are 2 packing methods with NZ Post; each affects the parcels you send to the API.

Pack items individually (Default) ↑ Back to top

Each item in your cart (non virtual) will be sent to the NZ Post API. Quotes for all items will be combined for the final cost.

Pack into boxes with weights and dimensions (Recommended) ↑ Back to top

Items will be packed into pre-defined boxes and sent to the API. We recommend this option. See box-packing below for more information on this.

Box-Packing ↑ Back to top

The box packer included with this shipping method lets you group items into packages of which you define the height, width, length, weight and max-weight. The packing is mainly volume based, but does also consider item sizes too.

The box packer is volume based. This will in most cases provide good results, but will never be as accurate as a real person packing a box (see BIN Packing Problem) therefore it is important you understand that packing results are as accurate as they can be and any anomalies should be accepted.

Setting up box sizes ↑ Back to top

Within the settings, look for the boxes setting. Click ‘add box’ to set up the boxes dimensions:

  1. Outer dimensions are used for parcel dimensions and are passed to the API.
  2. Inner dimensions are used for packing, and items will be fit within these.
  3. Box weight is the weight of the actual box, and will be added to the weight of the contents.
  4. Max weight is the maximum weight your box can hold. This includes contents weight and box weight.
Box Settings
Box Settings

How the calculation works ↑ Back to top

The packer does the following:

  1. Finds boxes which fit the items being packed (uses H x W x D).
  2. Packs all fitting items into boxes (using volume).
  3. The largest box which fits 100% of items is used *or* use the highest % packed box, and then pass unpacked items back (and repeat the process)
  4. Unpackable items are packed alone, using the item dimensions.
  5. All packed boxes are returned.

Customer Usage ↑ Back to top

Customers will get quotes (after inputting their address) from two places;

  • The cart page – by using the shipping calculator
  • The checkout page – by filling in the shipping and billing forms
Rates can be selected by customers as normal.

Troubleshooting ↑ Back to top

No rates returned/no rates available ↑ Back to top

    1. Enable debug mode to see debugging information on the cart page. This will often reveal the problem.
    2. Check your products have sizes and weights set – without this the calculation cannot be performed.
    3. Check your store’s base country is New Zealand and that you are using NZ Dollars (from WooCommerce > Settings > General).
    4. The store address specified in general WooCommerce setting is an important part that affects several WooCommerce features, so it should be mentioned correctly. The user should also make sure that their store address is available in NZ Post API database. If not, then they must request to get their store address added into NZ Post API database.
    5. The plugin works correctly when both the store address and buyers shipping address details match an address within the NZ Post address database. However, when the address does not exist in the NZ Post database, or the address is entered in the wrong format, the plugin does not work.
      If the buyer finds that shipping options are not coming up, then he can directly search his shipping address on NZ Post address locator here: https://www.nzpost.co.nz/tools/postshop-kiwibank-locator/. Then, they can retry and specify exactly as its appearing in the address locator search result.
    6. The plugin needs to be able to talk to NZ Post API. For this it uses wp_remote_post which makes use of fsockopen/CURL.

Questions and Support ↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Get in touch with the developer via the Help Desk.


The most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment