VibeFox Ninja Van 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.

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

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_ninja_van-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_ninja_van.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_ninja_van-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 Ninja Van 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. Enter your Ninja Van prices in the price table. For Indonesia, optionally turn on Live rates (see Configuration). Turn on Enable Ninja Van and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_ninja_van.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 Ninja Van, 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 Ninja Van and save. If you install the extension again after an uninstall, the Ninja Van settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. 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, IDR conversion rate is 0, Minimum weight (kg) is greater than Maximum weight (kg), or Sort order is not a whole number. If your store has no weight class with the unit kg and the unit of the default weight class is not known to the extension, a warning says that product weights are taken as kilograms: add a kg weight class in System > Localisation > Weight Classes. Only admin users with the modify permission for this extension can save the settings.

General

The settings apply to every geo zone. You can limit the method to a geo zone in Conditions, or use Ignore shipping zones.

Enable Ninja Van: shows or hides Ninja Van at checkout. Default: off.

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

Tax class: the tax class of the shipping cost, or No tax (default). Choose No tax if the prices in the table already include tax (GST, SST, VAT).

Sort order: the position of Ninja Van among the shipping methods at checkout. A whole number.

Prices (in your store default currency, tax excluded)

Enter the prices of your Ninja Van rate card in your store 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 × button 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 method in that case. 0 means free shipping.

Price applies: the way prices are counted. This also applies to live prices.

Per order (one parcel, tier by total cart weight): one price for the cart, with the weight column chosen by the total cart weight. This is the default.

Per item (every item is a separate parcel, tier by its own weight): every item is priced by its own weight and the prices are added up, so 3 units of a product cost 3 times its price. With live prices, every item is priced by Ninja Van as a separate parcel.

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). They are updated after every save.

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: the OpenCart store address has no separate city or street, so the ship-from zone cannot be detected from it. Codes are converted to capital letters. 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. A status line also warns when the two codes are not a pair in the zone code mapping.

IDR conversion rate: the Tariff API returns the fee in Indonesian rupiah (IDR). If your store default currency is IDR, leave it empty. Otherwise enter how much 1 IDR is in your store 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 method when the cart weighs less. Product weights are converted from their OpenCart weight class to kilograms. 0 means no limit (default).

Maximum weight (kg): hide the method when the cart weighs more. Default: 30. 0 or an empty field means no limit. It cannot be lower than Minimum weight (kg).

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 of the products that need shipping (after the coupon, before tax) from which Ninja Van shipping is free. Leave it empty for no free shipping.

Geo zone: offer Ninja Van only for addresses in this geo zone. All zones (default) means no limit. It is not checked when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.

Availability without shipping zones

Ignore shipping zones: offer Ninja Van for the countries below whatever the Geo zone. When off (default), the geo zone decides and the country list is not used.

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

Advanced

Debug log: writes rate calculations to storage/logs/vfd_njvn_debug.log.php (on OpenCart 4 system/storage/logs/vfd_njvn_debug.log.php). The file cannot be read from the web. No customer addresses or zone codes are logged. Failed Tariff API requests are logged even when this is off. Turn it off when you are done. When the file reaches 5 MB, it is moved to vfd_njvn_debug.old.log.php and a new log is started.

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 extension deletes the Ninja Van settings and the log. When off (default), they are kept for a re-install. Cached prices are always deleted.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The extension has no secret keys, so everything is 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.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Ninja Van price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Ninja Van is not offered. 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: the country list of Ignore shipping zones (if it is on), 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 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 method is hidden for that cart. The price is calculated in your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.

With Live rates on, a delivery within Indonesia is priced by Ninja Van first. The extension turns the delivery address into Ninja Van zone codes: the region (province) of the address, the City field (city or regency) and, for cities with several zones, the district (Kecamatan) written in Address 1 or Address 2. It sends your ship-from codes, the delivery codes, the weight and the service level, and converts the fee from IDR to your store 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 in a table of the extension: prices for 6 hours, "no price for this route" for 1 hour and failures for 5 minutes. Saving the settings does not clear this cache. The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Ninja Van in the window Shipping method options. The method works the same way as on OpenCart 3.

The extension 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 method is door-to-door delivery. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method. Live prices are not available outside Indonesia.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Ninja Van is the first block on Extensions > Extensions > Shipping > VibeFox Ninja Van > 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-ninja-van 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, Ninja Van 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

Ninja Van does not appear at checkout: check that the license is active and Enable Ninja Van is on. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum order amount, and that the country, the * row or Price for countries not in the table has a price. Check that the products have Requires Shipping set to Yes.

The live price is not used for some addresses: the destination must be matched to a Ninja Van zone: Indonesia, region (province), city or regency in City 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 extension page.

Live prices are not requested at all: the status lines under Live rates (API) — Indonesia show the reason: the ship-from zone codes are missing, 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. Saving the settings does not end the pause.

Which currency are the prices in: the table and the conditions are in your store default currency. Live prices are in rupiah (IDR), converted with IDR conversion rate unless your store currency is IDR.

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

For developers: a store with its own district (Kecamatan) field can supply the zone codes with the OpenCart event vfd_ninja_van/tariff_zone (trigger catalog/vfd_ninja_van/tariff_zone), also for the ship-from zone. The Tariff API address can be replaced with the setting vfd_njvn_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 Ninja Van. The license key and license status of this extension are always removed. OpenCart always resets Enable Ninja Van, Sort order, Tax class and Geo zone. The cached prices are always removed. If Remove data on uninstall is on, the Ninja Van settings, the last Tariff API status 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. 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 Ninja Van in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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