VibeFox Ninja Van for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Ninja Van rate card: the prices of your Ninja Van shipper account or from the Ninja Van sales team, entered in the price table. No API keys are needed. The optional live prices within Indonesia use the Ninja Van Tariff API, which is public and needs no authentication.
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 Ninja Van 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. Enter your Ninja Van prices in the price table. For Indonesia, optionally turn on Live rates (see Configuration). Click Save.
On install the module creates the Ninja Van carrier with the delivery time text Courier delivery. The carrier is switched on, assigned to all zones and all customer groups, and has no tax rule. 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 Ninja Van > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Nothing is saved and an error is shown when a number field holds text or a negative number, IDR conversion rate is 0, Minimum weight (kg) is greater than Maximum weight (kg), or Method title is longer than 64 characters. If your shop weight unit is not one the module knows, a warning after saving says that product weights are taken as kilograms.
General
Enable Ninja Van: switches the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Method title: the carrier name shown to the customer in the cart and at checkout. Default: Ninja Van. Required, at most 64 characters.
Tax: the tax rule of the carrier, or No tax (default). Choose No tax if the prices in the table already include tax (GST, SST, VAT).
Prices (in your shop default currency, tax excluded)
Enter the prices of your Ninja Van rate card in your shop default currency. If your rate card is in SGD, MYR, IDR or another currency, convert it first. This table is used for every destination outside Indonesia, and whenever a live price is not available.
Price table: one row per destination country. Click Add country to add a row and the trash icon to remove one. Choose * All other countries for every country without its own row. Each row has a Base price and weight columns: 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. An empty (or 0) weight column uses the base price. Base price 0 means free shipping to that country. Both "9.99" and "9,99" are accepted. Rows without prices are dropped when you save, and only the first row of a country is kept.
Price for countries not in the table: used when the table has no row for the destination country (and no * row), or the row has no price for this weight. Leave it empty to hide the carrier in that case. 0 means free shipping.
Price applies: the way prices are counted. This also applies to live prices.
Live rates (API) — Indonesia
The Ninja Van Tariff API returns the standard delivery fee, without surcharges and discounts, for parcels sent within Indonesia. Ninja Van offers it for Indonesia only. When Live rates is on, status lines under the section title show the ship-from zone, a missing conversion rate and the last Tariff API answer (environment, time and result).
Live rates: get live Ninja Van prices for deliveries within Indonesia. Default: off. Without it nothing is sent to Ninja Van during checkout.
Environment: Production (api.ninjavan.co) (default) or Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: the service the price is requested for: Standard (default), Express, Same day or Next day. If Ninja Van has no price for the route and service, the price table is used.
Ship-from zone code L1 and Ship-from zone code L2: the L1 and L2 tier codes of the district you ship from, for example ID_A00007_01 and ID_B00069_01, from the Ninja Van zone code mapping (CSV) whose address is shown under the field. Enter both, or leave both empty to detect them from the shop address in Shop Parameters > Contact > Stores: Indonesia, state (province), city and, if the city has several zones, the district (Kecamatan) in the address line. A code in the wrong format is cleared with a warning. If only one code is entered, a warning asks you to enter both, and a status line shows that live prices are not requested.
IDR conversion rate: the Tariff API returns the fee in Indonesian rupiah (IDR). If your shop default currency is IDR, leave it empty. Otherwise enter how much 1 IDR is in your shop currency, for example 0.000058. It must be greater than 0. Without it live prices are not used and the price table is.
Conditions
Minimum weight (kg): hide the carrier when the cart weighs less. Product weights are converted from your shop weight unit to kilograms. 0 means no limit.
Maximum weight (kg): hide the carrier when the cart weighs more. Default: 30. 0 means no limit. It cannot be lower than Minimum weight (kg).
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 (products that need shipping, after discounts, before tax) from which Ninja Van shipping is free. Leave empty for no free shipping.
Availability without shipping zones
Ignore shipping zones: offer Ninja Van for the countries below even if the carrier is not linked to their zone. When on, the carrier is linked to all active zones, including zones you create later. When you switch it off, the carrier gets back the zones it had before.
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: logs rate calculations to logs/vfd_njvn_debug.log.php in the module folder. The file cannot be opened from the web. No customer addresses are logged. Failed Tariff API requests are logged even when this is off. Turn it off when you are done.
Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.
Remove data on uninstall: when on, uninstalling the module deletes the module settings, the carrier, cached prices and the log. When off, everything is kept for a re-install.
How it works at checkout
At the shipping step PrestaShop asks the module for the Ninja Van price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: the country list of Ignore shipping zones (if it is on), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to Ninja Van.
The price comes from the row of the country (or the * row): the weight column, else the base price, else Price for countries not in the table. If there is no price, the carrier is hidden for that cart. The price is calculated in your shop default currency and then shown in the customer's cart currency.
With Live rates on, a delivery within Indonesia is priced by Ninja Van first. The module turns the ship-from and delivery addresses into Ninja Van zone codes: state (province), city or regency and, for cities with several zones, the district (Kecamatan) written in an address line. It sends the codes, the weight and the service level, and converts the fee from IDR to your shop currency. With Per item, one request is sent per distinct item weight, up to 5 per cart. With more different weights the price table is used.
The Tariff API allows 20 requests a minute, so answers are cached for 6 hours, failures for 5 minutes and "no price for this route" for 1 hour. The module never sends more than 18 requests a minute, and after an HTTP 429 answer it pauses for an hour. The API timeout is 12 seconds. If Ninja Van does not answer, answers with an error, has no price for the route, or the address cannot be matched, the table price is used. Errors go to the log, never to the customer.
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 prices only. It does not create Ninja Van orders, print airway bills (AWB), book pickups, track parcels or handle COD. Use the Ninja Van Dashboard for that. There is no pickup point (Ninja Points) selector: the carrier is door-to-door delivery. Live prices are not available outside Indonesia.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Ninja Van is the first block on Modules > Module Manager > VibeFox Ninja Van > 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-ninja-van 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 Ninja Van 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
Ninja Van does not appear at checkout: check that the license is active and Enable Ninja Van is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or turn on Ignore shipping zones and check Countries). Check the weight limits and Minimum order amount, and that the country, the * row or Price for countries not in the table has a price. Products can also be limited to certain carriers in the product page.
The live price is not used for some addresses: the destination must be matched to a Ninja Van zone: Indonesia, state (province), city or regency and, for cities with several zones, the district (Kecamatan) in an address line. Otherwise the table price is used. Turn on Debug log, reload the checkout and look at the Log field on the module page.
Live prices are not requested at all: the status lines under Live rates (API) — Indonesia show the reason: the shop address is not in Indonesia or the ship-from zone could not be detected (enter both zone codes), only one of the two codes is entered, the entered codes are not a pair in the zone code mapping, or IDR conversion rate is missing.
Rate limit reached (HTTP 429): live requests are paused for an hour and the price table is used meanwhile.
Which currency are the prices in: the table and the conditions are in your shop default currency. Live prices are in rupiah (IDR), converted with IDR conversion rate unless your shop currency is IDR.
The page says the Ninja Van carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
Developers: a shop with its own district (Kecamatan) field can supply the zone codes with the hook actionVfdNjvnTariffZone.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Ninja Van and choose Uninstall. The license key and the license status are always removed. The cached prices are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, the last Tariff API status and the log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again gives the saved carrier back the status it had before the uninstall.
Ninja Van is a trademark of its respective owner. This module is not affiliated with or endorsed by Ninja Van.