VibeFox NZ Post for Adobe Commerce — Yardım

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL, JSON and mbstring extensions.

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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-nz-post-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/NzPostShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_NzPostShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox NZ Post. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. For live rates fill in the NZ Post API section. Optionally enter fixed prices, which are used without live rates and as the fallback (see Configuration). Set Enable NZ Post to Yes and click Save Config.

The module adds the NZ Post shipping method to Magento. With a fixed price customers see it as NZ Post - Shipping (method title and method name); with a live rate the method name is replaced by the NZ Post service, for example NZ Post - followed by the service name and code. It is off after installation (Enable NZ Post = No). The module adds its own table for the NZ Post service of orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox NZ Post, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached NZ Post rates and access tokens. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, a title with one of the characters < > ; = # { }, a Method title or Method name that is empty or longer than 64 characters; a Sort order that is not a whole number; a number field that does not contain 0 or a positive number; an NZD conversion rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg); a changed Client ID or Account number while the saved secret is kept (Enter the secret again when changing its account.).

While Enable NZ Post is Yes and a Client ID or Client Secret is saved, warnings after saving remind you of settings that stop live rates: only one of Client ID and Client Secret, no NZD conversion rate when the base currency of your store is not NZD, or incomplete data for domestic rates (account, auth code or site code, ship-from suburb, city and four-digit postcode). The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable NZ Post: shows or hides NZ Post at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: NZ Post. Required, at most 64 characters, without < > ; = # { }.

Method name: shown after the method title, as "Method title - Method name", for fixed prices and free shipping. A live rate shows the NZ Post service instead. Default: Shipping. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

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

Environment: Production (default, api.nzpost.co.nz) or UAT (the NZ Post testing environment, 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 deletes the saved Client Secret.

Client Secret: the OAuth2 client secret. It is exchanged for an access token, which is cached until it expires. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved secret, type a new value to change it. To delete the saved secret, clear the field and click Save Config. If you change the Client ID, enter the Client Secret again.

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 deletes the saved auth code.

Auth code: the account auth code for domestic rates. Not needed if you enter a site code. Stored encrypted like the Client Secret: leave the mask to keep it, clear the field and click Save Config to delete it. If you change the Account number, enter the auth code again.

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. Spaces are removed. Needed for domestic rates.

The ship-from fields belong to the module only. The Magento origin settings are not used or changed.

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 if your store charges tax on shipping (a tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping), so GST is not charged twice.

NZD conversion rate: NZ Post prices are in NZD. If the base currency of your store is not NZD, enter how many units of the base currency one NZD is worth, for example 0.55. Without it live rates are not used and the fixed prices apply. The same rate converts the order value sent with international requests. The rate must be greater than 0. If your base currency is NZD, leave it empty.

Parcel for live rates

The cart is sent to NZ Post as one parcel. Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so the parcel size below is always used and volumetric weight is not calculated from the products.

Default product weight (kg): used for each product that has no weight, for live rates only. Default: 0.5.

Default parcel length (cm): the parcel length sent to NZ Post. Default: 30.

Default parcel width (cm): the parcel width sent to NZ Post. Default: 20.

Default parcel height (cm): the parcel height sent to NZ Post. Default: 10.

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

Prices are in the base currency of your store, tax excluded.

Country prices: one row per destination country. Click Add country to add a row and Delete to remove one. Choose * All other countries for a row that covers all other countries. Each row has a Price for any weight and optional weight columns by cart weight: XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (over 5 kg). A filled weight column overrides Price; an empty or 0 column uses Price. A Price of 0 means free shipping to that country. Rows without any price are removed when you save. If a country has several rows, the last one is kept. Invalid or negative prices are cleared, the rest of the page is saved, and a warning lists the columns (NZ Post: invalid country prices were cleared).

Fixed price per: Per order charges the price once. Per item multiplies the price for the cart weight 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.

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

Availability

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

Maximum 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 kg. 0 means no limit.

Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) 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.

Ship to Applicable Countries: All Allowed Countries offers NZ Post for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Advanced

Debug log: writes rate calculations to var/log/vfd_nzpt_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. The Client Secret, the auth code, access tokens and full 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 Yes, uninstalling the module with its data deletes the NZ Post settings and the log (see Uninstall). The license key and the cached rates are always removed. The NZ Post services saved with orders are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the NZ Post price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to NZ Post. A Magento cart price rule with free shipping also makes the price 0 without a request to NZ Post; the countries and the weight limits still apply. Otherwise the module 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 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. Magento has no suburb field: the module uses the second street line 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 base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. 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 conversion 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 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

The shipping description and price stay in the order as usual in Magento, also in the order e-mails. When an order is placed with a live NZ Post rate, the module also saves the priced service with the order, without a new request to NZ Post. On the admin order page (Sales > Orders > View, Information tab) the NZ Post shipping block shows Service, Price in base currency and Base currency. The customer sees NZ Post service in the order in their account (or on the Orders and Returns page for guests). Orders with a fixed price or free shipping have no such block. The block shows the values from the moment of the order, also for older orders and when the module is switched off.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox NZ Post is the first row of the VibeFox NZ Post group in Stores > Configuration > Sales > Delivery Methods, 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: magento-shipping-nz-post and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the NZ Post method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data 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 Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific 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.

Live rates do not appear: look at the warnings after Save Config. Then turn on Debug log, reload the checkout and look at the Log field in the Advanced section. 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 conversion 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 base currency is not NZD: enter the NZD conversion rate. Fixed prices are always in the base currency.

GST is charged twice on shipping: domestic NZ Post prices include 15% GST. If your store taxes shipping in Tax Class for Shipping, set API prices to Excluding GST.

Saving fails with "Enter the secret again when changing its account.": you changed the Client ID or the Account number. Type the Client Secret or the auth code of the new account as well and click Save Config.

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

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_NzPostShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_NzPostShipping to remove the data, then bin/magento module:disable Vibefox_NzPostShipping, delete the folder app/code/Vibefox/NzPostShipping and run bin/magento setup:upgrade.

The license key, the license status, the cached rates and access tokens are always removed. If Remove data on uninstall is Yes, the NZ Post settings and the log are removed too. If it is No, the settings are kept for a re-install. The NZ Post services saved with orders stay with the orders.

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