VibeFox Ninja Van for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_ninja_van folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Ninja Van, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter your Ninja Van prices in the price table. For Indonesia, optionally turn on Live rates (see Configuration).

6. Add VibeFox Ninja Van to a shipping zone (for example "Singapore") in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Ninja Van. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name customers see for this zone. Leave it empty to use the global Method title.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. A zone can override it. Default: Ninja Van.

Prices (in your store currency)

Enter the prices of your Ninja Van rate card in your store currency. If your rate card is in SGD, MYR, IDR, PHP, THB or VND, 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 cross 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.

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.

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. 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 this section show the ship-from zone, a missing conversion rate and the last Tariff API answer.

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) linked on the settings page. Enter both, or leave both empty to detect them from the store address in WooCommerce > Settings > General: Indonesia, 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 an error.

IDR conversion rate: the Tariff API returns the fee in Indonesian rupiah (IDR). If your store currency is IDR, leave it empty. Otherwise enter how much 1 IDR is in your store currency, for example 0.000058. Without it live prices are not used and the price table is.

Conditions

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: 30. 0 means no limit.

Minimum order amount: show the method only when the cart subtotal (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 Ninja Van delivery is free. Leave empty for no free shipping.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. Choose None if the prices in the table already include tax (GST, SST, VAT).

Availability without shipping zones

Ignore shipping zones: offer Ninja Van for the countries below even if the method is not added to any shipping zone.

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 WooCommerce > Status > Logs (source vfd_ninja_van). No customer addresses are logged. Failed Tariff API requests are logged even when this is off. Turn it off when you are done.

Remove data on uninstall: when on, deleting the plugin removes all Ninja Van settings and zone methods. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. If free shipping applies, the customer sees the method at no cost 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. Product weights are converted from your store weight unit to kilograms. If there is no price, the method is hidden.

With Live rates on, a delivery within Indonesia is priced by Ninja Van first. The plugin turns the ship-from and delivery addresses into Ninja Van zone codes: 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 store currency. With Per item, one request is sent per distinct item weight, up to 5 per cart.

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 plugin 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.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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. Live prices are not available outside Indonesia.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Ninja Van. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Ninja Van does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes, and that the country, the * row or Price for countries not in the table has a price.

The live price is not used for some addresses: the destination must be matched to a Ninja Van zone: Indonesia, 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 to see why, and check the status lines under Live rates (API) — Indonesia.

Live prices are not requested at all: the status lines show the reason: the store address is not in Indonesia or the ship-from zone could not be detected (enter both zone codes), 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 is in your store currency. Live prices are in rupiah (IDR), converted with IDR conversion rate unless your store currency is IDR.

Developers: a site with its own district (Kecamatan) checkout field can supply the zone codes with the filter vfd_njvn_tariff_zone.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods, the last Tariff API status and cached live prices are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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