New Zealand Post Shipping

New Zealand Post is a premium shipping method which lets you get shipping rates from the New Zealand Post API. It makes shipping calculations for your product and ordrs effortless.

Because of the NZ Post API, using the Plugin 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.

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 

The plugin requires an NZ Post API Credentials and other supporting information. This varies on the API you are using.

To get started you will need to configure the API to access your specific NZ post account. To access the plugin settings go to: WooCommerce > Settings > Shipping > New Zealand Post. Next, select API Type from NZ Post API Type drop-down.

We recommend using Shipping Option V2 API since it is the latest version of New Zealand Post API.

Here is the process to integrate with the ShippingOptionsV2 API. For ShippingOptions(V1) and RateFinder API, see below. 

Shipping Option V2 API 

To use the ShippingOptions V2 API with the NZ Post Plugin you require the following information:

• NZ Post Account Number
• NZ Post Site Code

Both the NZ Post Account Number and Site code can be obtained by contacting NZ Post. On the plugin settings page you will see NZ Post Account Number and Site code –  Enter your NZ Post account number or (TPID) and NZ Post Site Code .

Other options on the settings table:

• Enable auto-generate Shipping Options Label – Enable to generate shipping labels on checkout
• Enable Sandbox Mode – Enable Sandbox for API testing
• Debug Mode – Enabling this will show you debugging information on your cart and checkout pages.
• Domestic shipping surcharge – Add surcharge amount per order if any.
• International shipping surcharge – Add surcharge amount per order if any
• Save Changes – Click Save changes to store settings. Always store settings after making any change.   

If you would like to configure the plugin to use your unique client ID and client secret provided by NZ Post please follow the guide here:

NZ Post API Configuration

1. Go to: WooCommerce > Settings > Shipping. We want to add a shipping Method.
3. Select your Shipping Zone that you want to add the method to, and press the Add shipping method + button on the right
   
   
4. Select New Zealand Post from the dropdown and press Add shipping method:
   
5. 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.

• 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 available NZ rates and options (user will get the choice) or just return a single, cheapest shipping rate.
  • Services – Here you can rename, and re-order, NZ Post shipping rates.

There are 2 packing methods with NZ Post; each affects the parcels you send to the API. This determines if the rate is calculated based on each items dimensions or packed in to a predefined box and rate.

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.

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.

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.

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.

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.

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

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.

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.

Working with Legacy APIs: ShippingOptions and RateFinder: 

RateFinder API

1. API Key – NZ Post will provide you with an API key after you signup for their API services. Enter this here – it is required.
2. Debug Mode – Tick the checkbox to log API requests and responses for the cart and checkout pages. Useful for troubleshooting.
3. Domestic shipping surcharge – Add surcharge amount per order if any.
4. International shipping surcharge – Add surcharge amount per order if any.
5. Click Save changes to store settings

This Shipping option is for existing customers of NZ Post with active API Access:

1. Signin to your account Developer Resource Center here 
2. Click Public portal and you’ll be redirected to another page.
   
3. Navigate to Shipping Options API or search for ShippingOptions API in the search bar and click on it
   
4. On the top right corner, click on Request access button.
   
5. Select Production version from API instance and Standard in SLA tier.
   
6. Read and accept Terms and Conditions.
7. Now go to the Application drop-down field and follow these steps.

1. In Application field, click create a new application. 
2. Enter any name for your application.
3. Select the following
   1.  Resource Owner Grant
   2.  Client Credentials Grant 
   3. Refresh Token and Automatically register the URIs for API Notebook and API Console
      
4. And click create.
5. You’ll come back to the previous popup and now click Request Access.
   
6. You’ll get a notification message in your email and also in the application tab here from NZ Post.
7. Click the name of your Application. 
8. Now, you can see Client ID and Client Secret in this tab.

Adding credentials to Shipping Option API 

Client ID – Copy and paste Client ID from the application you have created. 

Client Secret – Available in application also copy and paste from there. 

Username –  Enter username or email address of your NZ Post account 

NZ Post Account Number and Site code –  Enter your NZ Post account number or (TPID) and NZ Post Site Code provided by New Zealand Post. If you doesn’t have it, please call the NZ POST National Call Center for assistance with query on – 0800 501 501
or email NZ Post Sales leads – leads@nzpost.co.nz 

 Enable auto-generate Shipping Options Label – Enable to generate shipping labels on checkout

Enable Sandbox Mode – Enable Sandbox for API testing

Debug Mode – Enabling this will show you debugging information on your cart and checkout pages.

Domestic shipping surcharge – Add surcharge amount per order if any.

International shipping surcharge – Add surcharge amount per order if any

Save Changes – Click Save changes to store settings. Always store settings after making any change.   

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.

Enhanced CourierPost Services

The plugin now includes expanded CourierPost services, enabling greater shipping flexibility:

• CourierPost Signature Required: Ensures packages are signed for upon delivery.

• CourierPost Photo Required: Adds a photo confirmation for delivery verification.

• CourierPost Rural Delivery: Supports delivery to rural addresses.

Address Validation

To minimize errors and improve delivery accuracy:

• Integrated NZ Post address validation system.

• Automatic address verification during checkout.

• Direct link to the NZ Post Address Locator tool for easy correction of invalid addresses.

• Custom error messages guiding customers to verify their address.

PUDO (Pick Up Drop Off) Integration

The new PUDO integration offers more delivery options:

• Support for NZ Post pickup locations.

• Customers can select a nearby collection point during checkout.

• Integrated functionality for selecting and confirming collection points.

• Enhanced shipping flexibility for customers with alternative pickup options.

UI and On-Screen Features

1. Collection Point Selection UI

• Checkbox: New “Delivery to Collection Point?” option on the checkout page.

• Dropdown Menu: Allows customers to select from nearby collection points.

• Details Display:

• Full address of the selected collection point.

• Distance from delivery address in kilometers.

• Informative description explaining the benefits of using a collection point.

2. Address Validation Features

• Error Messages: User-friendly error messages for invalid addresses.

• NZ Post Address Locator Tool: Direct link provided in the error message to assist in correcting the address.

• Automatic Validation: Real-time validation during checkout ensures address accuracy.

3. New Shipping Service Options

• UI elements for new CourierPost services:

• CourierPost Signature Required.

• CourierPost Photo Required.

• CourierPost Rural Delivery.

• Dynamic sorting and filtering of shipping options for easier selection.

4. Dynamic UI Behavior

• Conditional Fields: Collection point fields automatically show or hide based on:

• Country selection (enabled only for New Zealand).

• Whether the “Delivery to Collection Point” checkbox is selected.

• Real-Time Updates:

• Updates to available collection points when the delivery address changes.

• Dynamic sorting based on proximity and user preferences.

5. Order Tracking Enhancements

• Order Emails: Shipping status and tracking reference numbers are now included.

• Tracking Status Popup: A detailed event timeline for tracking updates.

6. Responsive Design

• Mobile-friendly interface for the collection point selector.

• Styled description boxes and form fields for clarity.

• Clear visual hierarchy for shipping options to enhance usability.