VibeFox NZ Post for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_nz_post-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_nz_post.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_nz_post-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox NZ Post and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

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

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). Turn on Enable NZ Post and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_nz_post.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox NZ Post, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable NZ Post and save. If you install the extension again after an uninstall, the NZ Post settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox NZ Post > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached NZ Post rates and access tokens. Only admin users with the modify permission for this extension can save the settings.

Nothing is saved and an error is shown when Method title is empty, longer than 64 characters or contains < > ; = # { }, a number field holds text or a negative number, the NZD rate is 0, Min cart weight (kg) is greater than Max cart weight (kg), or Sort order is not a whole number. 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 store has no weight class with the unit kg or no length class with the unit cm: weights and dimensions are then converted by the unit name of their class (kg, g, lb, oz; cm, mm, m, in), other units are read as kg and cm.

General

The settings apply to every geo zone. You can limit the method to a geo zone, or to countries, in Availability.

Enable NZ Post: switches the method on or off at checkout. Default: off.

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

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

Sort order: the position of NZ Post among the shipping methods at checkout. A whole number.

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 it 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 method has a tax class (General), so GST is not charged twice.

NZD → (store currency) rate: NZ Post prices are in NZD. If your store 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 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 their weight and length classes to kg and cm (mm for international requests). 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 store default currency, tax excluded.

Country prices: one row per destination country. Click Add country to add a row and the × button 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 method in that case.

Fixed price per: Order (default) 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 (default).

Max cart weight (kg): hide the method 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 for addresses outside the Geo zone.

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

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

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

Availability

Normally the method is offered in the geo zone selected below, or everywhere if none is selected.

Geo zone: offer NZ Post only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: also offer NZ Post outside the geo zone, for the countries below. When on, only these countries get the method, inside the geo zone as well. Default: off.

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

Advanced

Debug log: writes rate calculations to storage/logs/vfd_nzpt_debug.log.php (on OpenCart 4 system/storage/logs/vfd_nzpt_debug.log.php). The file cannot be read from the web. API errors are always logged, even with the debug log off. Credentials, tokens, the account number and customer addresses are not logged. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_nzpt_debug.old.log.php and a new log is started.

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 extension deletes the settings and the log. When off (default), they are kept for a re-install. Cached rates are always deleted. The NZ Post details of orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The Client Secret and the auth code are not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved Client Secret and auth code are kept while their Client ID and account number stay filled in.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the NZ Post price. If a Geo zone is set and the address is outside it, NZ Post is offered only when Ignore shipping zones is on and the country is allowed. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. 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 method is hidden.

With live rates set up, the extension 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. OpenCart has no suburb field: the extension uses Address 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 store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class. 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. The access token is kept until it expires, and a rejected 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks an NZ Post option in the window Shipping method options. The rates are the same as on OpenCart 3.

The extension 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 NZ Post is placed, the extension saves what the shipping price was based on. Open the order in Sales > Orders: the order page shows an NZ Post panel with NZ Post service (the priced NZ Post service of a live rate, with its code) and Price source: Live rate (NZ Post ShippingOptions API), Fixed price or Free shipping. The panel shows the values from the moment of the order, even if rates or settings change later, and also while the method is switched off. The customer does not see the service name.

On OpenCart 4 the NZ Post panel is shown above History. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the saved service and price source are updated with it. If the customer switches that order to another shipping method, the NZ Post data of the order is removed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox NZ Post is the first block on Extensions > Extensions > Shipping > VibeFox NZ Post > Edit, 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 store. Below them are the line Product: opencart-shipping-nz-post and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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 and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum order amount. If NZ Post gives no rate, the method is shown only with a country price or a Fallback cost. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: look at the warnings at the top of the extension 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.

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

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

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

The page says "Warning: You do not have permission to modify VibeFox NZ Post!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_nz_post (OpenCart 3) or extension/vfd_nz_post/shipping/vfd_nz_post (OpenCart 4) in System > Users > User Groups.

For developers: the suburb sent for a New Zealand delivery address can be changed with the OpenCart event vfd_nz_post/delivery_suburb (trigger catalog/vfd_nz_post/delivery_suburb). The NZ Post API address can be replaced with the setting vfd_nzpt_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox NZ Post. The license key and license status of this extension are always removed. OpenCart always resets Enable NZ Post, Sort order, Tax class and Geo zone. The cached rates and tokens are always removed, and the NZ Post panel is no longer shown on the order page. If Remove data on uninstall is on, the NZ Post settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The saved NZ Post details of orders are never deleted and appear again after a re-install. Existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox NZ Post in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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