VibeFox NZ Post for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

NZ Post API access (for live rates only): live rates use the NZ Post ShippingOptions API. Request API access in the NZ Post Developer Resource Centre on the NZ Post website. NZ Post gives a Client ID and a Client Secret, first for the testing (UAT) environment and then for production after its go-live checklist. For rates within New Zealand you also need an NZ Post business account: the account number and its auth code (or site code). If you only use fixed prices, you do not need API access.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_nz_post folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox NZ Post, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. For live rates fill in the NZ Post API (live rates) section. Optionally enter fixed prices, which are used without live rates and as the fallback (see Configuration).

6. Add VibeFox NZ Post to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox NZ Post. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name customers see for this zone. Leave it empty to use the global Method title.

Every time you save the settings, the cached NZ Post rates and access tokens are cleared. If live rates cannot work with the saved values (only one of Client ID and Client Secret, no NZD conversion rate, incomplete data for domestic rates), a warning appears above the settings.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. A zone can override it. Default: NZ Post.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. See also API prices below.

NZ Post API (live rates) (leave the Client ID empty to use only fixed prices)

Environment: Production (api.nzpost.co.nz) (default) or Testing / UAT (api.uat.nzpost.co.nz). Use the environment your Client ID was issued for.

Client ID: the OAuth2 client ID of your NZ Post API application.

Client Secret: the OAuth2 client secret. It is exchanged for an access token, which is cached until it expires.

Account number: your NZ Post business (billing) account number. Required for rates within New Zealand. For international rates it is optional; with it NZ Post returns your contract rates.

Auth code: the account auth code for domestic rates. Not needed if you enter a site code.

Site code: the alternative to the auth code: your NZ Post pickup site code.

Ship-from suburb: the suburb of the address parcels are sent from, for example Petone. Needed for domestic rates.

Ship-from city: the town or city parcels are sent from, for example Lower Hutt. Needed for domestic rates.

Ship-from postcode: the 4-digit New Zealand postcode parcels are sent from, for example 5012. Needed for domestic rates.

Services: optional NZ Post service codes, comma separated, for example CPOLP, ICOU. Only these services are priced. Leave empty to use the cheapest service NZ Post returns for the parcel.

API prices: Including GST (default) or Excluding GST. Domestic NZ Post prices include 15% GST; international postage is zero-rated. Choose Excluding GST when Tax status is Taxable, so GST is not charged twice.

NZD → (store currency) rate: NZ Post prices are in NZD. If your store currency is not NZD, enter how many units of your currency one NZD is worth, for example 0.55. Without it live rates are not used. The same rate converts the order value sent with international requests. If your store currency is NZD, leave it empty.

Parcel for live rates

The cart is sent to NZ Post as one parcel. Product weights and dimensions are converted from your store units to kg and cm. The parcel takes the largest length and width of the products, and its height grows until it holds the volume of all items. The values below are used for products without weight or dimensions.

Default product weight (kg): used for each product that has no weight. Default: 0.5.

Default parcel length (cm): used when no product in the cart has dimensions. Default: 30.

Default parcel width (cm): used when no product in the cart has dimensions. Default: 20.

Default parcel height (cm): used when no product in the cart has dimensions. Default: 10.

Fixed prices (used when live rates are not set up or NZ Post gives no rate)

Prices are in the store currency.

Country prices: one row per destination country. Click + Add country to add a row and the cross to remove one. Choose * Default for a row that covers all other countries. Each row has an Any weight price and optional weight columns: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg and > 5 kg (cart weight). A filled weight column overrides Any weight; an empty or 0 column uses Any weight. An Any weight price of 0 means free shipping to that country. Both "9.99" and "9,99" are accepted. Rows without any price, invalid country codes and negative prices are removed when you save. Only one row per country is kept.

Fallback cost: used when neither the API nor the country table gives a price. Leave it empty to hide the method in that case.

Fixed price per: Order charges the price once. Item (price × quantity) multiplies it by the number of items in the cart. This applies to fixed prices and the fallback cost only. Live rates are always calculated for the whole parcel.

Conditions

Min cart weight (kg): hide the method when the cart weighs less. 0 means no limit.

Max cart weight (kg): hide the method when the cart weighs more. Default: 25 (NZ Post courier parcels go up to 25 kg). 0 means no limit.

Minimum order amount: show the method only when the cart subtotal reaches this amount. Leave empty to always show it.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Free shipping from: the cart subtotal from which NZ Post delivery is free. It applies only where the method has a price: a country price or the fallback cost (then no request goes to NZ Post), or a live rate. Leave empty to never offer free shipping.

The cart weight for these conditions counts products without a weight as 0.

Availability without shipping zones

Ignore shipping zones: offer NZ Post for the countries below even if the method is not added to any shipping zone.

Countries: the destination countries for that mode. Leave empty to use all countries you ship to. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations to WooCommerce > Status > Logs (source "vfd-nz-post"). API errors are always logged, even with the debug log off. Credentials, tokens and customer addresses are not logged. Turn the log off when you are done.

Remove data on uninstall: when on, deleting the plugin removes its settings, zone methods and cached rates. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. Then it looks for a price: the live NZ Post rate, then the country table, then the fallback cost. If there is no price, the method is hidden. If free shipping applies, the customer sees the method at no cost.

With live rates set up, the plugin gets an access token with your Client ID and Client Secret and asks NZ Post for a price. For an address in New Zealand it sends your account details, the ship-from address, the customer's suburb, city and postcode and the parcel weight and size. WooCommerce has no suburb field: the plugin uses Address line 2 when it holds a suburb name, otherwise the town or city. A domestic rate is requested only after the customer has entered a city and a 4-digit postcode. For other countries it sends the destination country, the parcel weight and size and the order value in NZD.

The cheapest allowed service with a price is used, including surcharges and mandatory add-ons. The price is converted from NZD to your store currency. The priced service is saved with the order as NZ Post service and is visible on the order screen. Each answer is cached for 1 hour. A failed request is cached for 10 minutes, so the checkout does not wait for NZ Post on every refresh. The API timeout is 10 seconds. An expired access token is renewed automatically.

If NZ Post gives no rate (API not set up, error, incomplete address, service not available, no NZD rate), the customer sees no error. The price from the country table is used, then the fallback cost. If there is no fixed price, the method is hidden. The reason is written to the log.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin calculates rates only. It does not create shipping labels, book pickups, make manifests, track parcels, validate addresses or let customers choose a pick-up point, PO Box or parcel locker. The cart is priced as one parcel, and the customer sees one NZ Post rate, not a list of services.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox NZ Post. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, NZ Post is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

NZ Post does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. If NZ Post gives no rate, the method is shown only with a country price or a Fallback cost.

Live rates do not appear: open WooCommerce > Status > Logs, source "vfd-nz-post". API errors are always there. Turn on Debug log for details. The log shows the reason: missing Client ID or Client Secret, a rejected token, missing account or ship-from data, no customer city or postcode yet, no NZD rate, or no priced service. Fixed prices are used while you fix the problem.

Token request fails: check the Client ID, the Client Secret and the Environment. UAT credentials do not work with production, and the other way round.

Domestic rates are missing, international rates work: rates within New Zealand need the Account number, the Auth code or Site code, and the full ship-from address with a 4-digit postcode. The customer must enter a city and a 4-digit postcode. Developers can change the suburb sent for the delivery address with the vfd_nzpt_delivery_suburb filter.

My store is not in NZD: enter the NZD → (store currency) rate. Fixed prices are always in the store currency.

GST is charged twice on shipping: domestic NZ Post prices include 15% GST. If Tax status is Taxable, set API prices to Excluding GST.

Rates look outdated after a change: save the settings page. This clears the cached NZ Post rates and tokens.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods, cached rates and access tokens are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

NZ Post is a trademark of its respective owner. This plugin is not affiliated with or endorsed by NZ Post.