VibeFox NZ Post for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox NZ Post in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. 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). Click Save.

On install the module creates the NZ Post carrier with the delivery time text NZ Post parcel delivery. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox NZ Post > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached NZ Post rates and access tokens.

Warnings appear above the settings when live rates cannot work with the saved values: only one of Client ID and Client Secret, no NZD conversion rate, or incomplete data for domestic rates. A warning also appears if the shop weight or dimension unit is not known to the module (weights are then taken as kg, dimensions as cm). Set the units in International > Localization (Local units). Number fields must contain 0 or a positive number; otherwise the page shows an error and nothing is saved.

General

Enable NZ Post: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Method title: the carrier name shown in the cart and at checkout. Default: NZ Post. Required, 64 characters at most.

Tax: the tax rule of the carrier, or No tax (the shipping cost is not taxed). If the shop adds GST on shipping, set API prices below to Excluding GST so GST is not charged twice.

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. Clearing it also clears the saved Client Secret.

Client Secret: the OAuth2 client secret. It is exchanged for an access token, which is cached until it expires. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

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. Clearing it also clears the saved auth code.

Auth code: the account auth code for domestic rates. Not needed if you enter a site code. Like the Client Secret, it is not shown again after saving.

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 the carrier has a tax rule (Tax above), so GST is not charged twice.

NZD → (shop currency) rate: NZ Post prices are in NZD. If your shop default 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. The rate must be greater than 0. If your shop 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 shop 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 configured or NZ Post gives no rate)

Prices are in the shop default currency, tax excluded.

Country prices: one row per destination country. Click Add country to add a row and the trash icon 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 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 carrier 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 carrier when the cart weighs less. 0 means no limit.

Max cart weight (kg): hide the carrier when the cart weighs more. Default: 25 (NZ Post courier parcels go up to 25 kg); an empty field also means 25. 0 means no limit. With Ignore shipping zones on, an empty field means no limit outside the carrier's own zones. If Min cart weight is greater than Max cart weight, the page shows an error and nothing is saved, because the carrier would never be shown.

Minimum order amount: show the carrier only when the cart subtotal (products that need shipping, after discounts, before tax) reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal (after discounts, before tax) from which NZ Post delivery is free. No request goes to NZ Post then. Leave empty to never offer free shipping.

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

Availability without shipping zones

Normally the carrier is shown in the zones it is assigned to in Shipping > Carriers.

Ignore shipping zones: offer NZ Post for the countries below, whatever zone matches. On save the carrier is added to all zones (also to zones created later). Switching the option off removes those added zones again.

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

Advanced

Debug log: writes rate calculations to logs/vfd_nzpt_debug.log.php in the module folder. The file cannot be opened from the web. 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.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the module deletes the settings, the carrier, cached rates, saved order details and logs. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the NZ Post price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to NZ Post. Otherwise it looks for a price: the live NZ Post rate, then the country table, then the fallback cost. If there is no price, the carrier is hidden.

With live rates set up, the module 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. PrestaShop has no suburb field: the module uses Address line 2 when it holds a suburb name (no digits), otherwise the 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 shop default currency and then shown in the customer's cart currency. 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 carrier is hidden. The reason is written to the log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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.

Orders

When an order with the NZ Post carrier is placed, the module saves what the shipping price was based on. The admin order page shows an NZ Post block with NZ Post service (the priced NZ Post service of a live rate) and Price source: Live rate (NZ Post ShippingOptions API), Fixed price or Free shipping. The block shows the values from the moment of the order, even if rates or settings change later.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox NZ Post is the first block on Modules > Module Manager > VibeFox NZ Post > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-nz-post and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the NZ Post carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

NZ Post does not appear at checkout: check that the license is active and Enable NZ Post is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or Ignore shipping zones is on and the country is allowed). Check the weight limits and Minimum order amount. If NZ Post gives no rate, the carrier is shown only with a country price or a Fallback cost. Products can also be limited to certain carriers in the product page.

Live rates do not appear: look at the warnings at the top of the module page. Then turn on Debug log, reload the checkout and look at the Log field. API errors are always there. 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 actionVfdNzptDeliverySuburb hook.

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

GST is charged twice on shipping: domestic NZ Post prices include 15% GST. If the carrier has a tax rule in Tax, set API prices to Excluding GST.

Rates look outdated after a change: click Save on the module page. This clears the cached NZ Post rates and tokens.

The page says the NZ Post carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox NZ Post and choose Uninstall. The license key and the license status are always removed. The cached rates and tokens are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, saved order details and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again, or a Reset, gives the saved carrier back the status it had before (on or off).

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