VibeFox iMile 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.
iMile tariff: the prices you agreed with the iMile sales team. You enter them in the price table in your store currency.
iMile API account (for the live estimate only): the live estimate uses the iMile OpenAPI "Estimated order delivery costs". You need a Customer ID and a Secret key (the API key iMile issues with your Customer ID). For a test client, register on the iMile developer portal (developer.imile.com). Production keys come from your iMile account manager. If you only use the price table, you do not need API keys.
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_imile folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox iMile, 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 iMile prices in the Price table. Optionally fill in the Live rates (API) section and turn on Live estimate (see Configuration).
6. Add VibeFox iMile to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones (for example "United Arab Emirates"), or turn on Ignore shipping zones and choose countries.
Configuration
All settings are on one page: WooCommerce > Settings > Shipping > VibeFox iMile. 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.
Every time you save the settings, the cached iMile estimates and access tokens are cleared. When the live estimate is on but cannot work (no keys, no ship-from city or country, no exchange rates, empty price table), warnings appear above the settings.
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: iMile.
Live rates (API) (optional)
If iMile returns no estimate (no keys, no city entered yet, error, timeout, no exchange rate), the price table is used.
Live estimate: turn it on to get the shipping cost from iMile. Default: off. With the live estimate off, nothing is sent to iMile during checkout.
Environment: Production (openapi.imile.com) (default) or Test (test-openapi.52imile.cn). Test keys work only with the test server and give test prices.
Customer ID: the client code (customerId) issued by iMile, for example C2102192601.
Secret key: the secret key (API key) issued by iMile together with the Customer ID. It signs the requests.
Signature: how requests are signed.
Ship-from country: the country you ship from. By default it is your store country. The list contains the countries the plugin has iMile country codes for.
Ship-from city: the city your parcels are sent from, spelled as in the iMile city list (for example Dubai, Riyadh). Leave it empty to use the store city from WooCommerce > Settings > General.
Ship-from province: optional, for example Dubai or Riyadh Province.
iMile service: the order type sent to iMile: Delivery order (100) (default) or Express order (1100). Express must be enabled for your account and country.
Goods category: the type of goods sent to iMile: Normal goods (default), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents or Parcel.
Exchange rates: iMile estimates in the currency of the destination country. Enter one line per currency with the price of 1 unit in your store currency, for example "AED = 0.25" or "SAR = 0.24". A point or a comma is accepted as the decimal separator. A rate is not needed for the store currency itself. Without a rate, estimates in that currency are not used and the price table is used instead. The same rate converts the cart value declared to iMile. Invalid lines are removed when you save.
Prices (used when the live estimate is off, and as the fallback when iMile returns no estimate)
Enter your iMile tariff in the store currency. If it is in AED, SAR or another currency, convert it first.
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 a row that covers every country without its own row. Each row has a Base price and optional weight columns: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg and XL >5 kg. An empty (or 0) weight column uses the base price. A base price of 0 means free shipping to that country. Both "9.99" and "9,99" are accepted. Rows without any price, invalid country codes and negative prices are removed when you save. Only one row per country is kept.
Price for countries not in the table: a price in the store currency. It is 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: how the table price is charged.
The same choice applies to the live estimate: per order sends one parcel with the whole cart, per item asks for each different parcel and multiplies by the number of units. If the cart has more than 5 different parcels, the price table is used.
Product weights are converted from your store weight unit to kilograms.
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 iMile delivery is free. Leave empty to never offer 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 and the iMile estimates already include VAT.
Availability without shipping zones
Ignore shipping zones: offer iMile 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: writes rate calculations to WooCommerce > Status > Logs (source "vfd_imile"). No keys and no customer addresses are logged. Failed iMile requests are always logged, even with the debug log off. Turn the log off when you are done.
Remove data on uninstall: when on, deleting the plugin removes all iMile settings, zone methods and cached estimates. 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 iMile.
With the live estimate on, the plugin sends iMile the ship-from country, province and city, the destination country, state, city and postcode, the cart weight in kg, the size in cm³ (from product dimensions), the cart value, the iMile service and the goods category. The estimate is always requested as prepaid, so cash-on-delivery fees are not included. A live estimate is requested only after the customer has entered a city, and only when every parcel has a weight. Each answer is cached for 1 hour. A failed request is cached for 5 minutes. After a timeout or a server error iMile is not asked for 2 minutes, after rejected keys for 5 minutes, so the checkout does not wait for iMile on every refresh. The API timeout is 12 seconds. An expired access token is renewed automatically.
The estimate is converted to the store currency with your exchange rates. If iMile gives no usable estimate (keys not set, city not entered yet, unknown city, error, timeout, no exchange rate), the customer sees no error and the price from the table is used. If the table also has no price, the method is hidden. The reason is written to the log.
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 rates only. It does not create iMile shipments, print AWB labels, request pickups, track parcels, reconcile cash on delivery or offer pickup points and lockers. Use the iMile portal for shipments.
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 iMile. 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, iMile 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
iMile 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. Check that the country or * has a row in the Price table, or that Price for countries not in the table is set.
The table price is shown instead of the iMile estimate: open WooCommerce > Status > Logs, source "vfd_imile", and turn on Debug log for details. Common reasons: Live estimate is off, the keys are missing, the customer has not entered a city yet, iMile does not know the city spelling, products have no weight, there is no exchange rate for the destination currency, or an API error. Also check the warnings above the settings.
"sign is invalid" in the log: check the Secret key, then try Signature = SimpleKey.
Keys are rejected: check the Customer ID, Secret key and Environment. Test keys work only with the test server.
City names do not match: city names must match the iMile city list. Developers can map them with the vfd_imile_live_request filter, and country codes with the vfd_imile_live_country_code filter.
Prices are in the wrong currency: the price table is in the store currency (WooCommerce > Settings > General). Convert an AED, SAR or MXN tariff when you enter it. Live estimates are converted with Exchange rates.
Tax is charged twice on shipping: if your prices already include VAT, set Tax status to None.
Estimates look outdated after a change: save the settings page. This clears the cached iMile estimates.
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 and cached estimates are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.
iMile is a trademark of its respective owner. This plugin is not affiliated with or endorsed by iMile.