VibeFox iMile 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.

iMile tariff: the prices you agreed with the iMile sales team. You enter them in the price table in your store default 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

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_imile-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_imile.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_imile-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 iMile 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 iMile prices in the Price table. Optionally fill in the Live rates (API) section and turn on Live estimate (see Configuration). Turn on Enable iMile and click Save.

OpenCart 4

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox iMile > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached iMile estimates and access tokens. Only admin users with the modify permission for this extension can save the settings.

When you save, the extension checks that Method title is valid (64 characters max, without < > ; = # { }), that the price, amount and weight fields are numbers of 0 or more, that Minimum weight (kg) is not greater than Maximum weight (kg), that Sort order is a whole number and that the tax class and geo zone exist. Otherwise it shows an error and saves nothing.

Warnings appear above the settings (and again after a save) when Live estimate is on but cannot work: the Customer ID or Secret key is empty, the ship-from city or country is missing (or the country is not an iMile market), there are no exchange rates, or the price table is empty and there is no price for other countries. A warning also appears when the store has no weight class with the unit kg and the unit of the default weight class is not known to the extension: product weights are then taken as kilograms, so add a kg weight class in System > Localisation > Weight Classes.

General

The settings apply to every geo zone. You can limit the method to a geo zone in Conditions, or switch on Ignore shipping zones in Countries to limit it to a list of countries instead.

Enable iMile: shows or hides iMile at checkout. Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout. Default: iMile. Required.

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

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. Clearing it also clears the saved Secret key.

Secret key: the secret key (API key) issued by iMile together with the Customer ID. It signs the requests. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Signature: how requests are signed.

Ship-from country: the country you ship from. The first option, Store country, uses the country of your store. The list contains only the countries the extension 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). Required for live estimates: OpenCart has no store city, so without this field only the price table is used.

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 default currency, for example "AED = 0.25" or "SAR = 0.24". 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.

Prices (used when the live estimate is off, and as the fallback when iMile returns no estimate)

Enter your iMile tariff in the store default currency, tax excluded. 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 × button 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.

Price for countries not in the table: a price in the store default 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 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 their OpenCart weight class to kilograms, and dimensions from their length class to centimetres.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default).

Maximum weight (kg): hide the method above this cart weight. Default: 30. 0 means no limit. If you leave the field empty, 30 kg is used.

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 iMile delivery is free. Leave it empty to never offer free shipping.

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

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

Countries

Ignore shipping zones: when on, the Geo zone is not checked and iMile is offered for the countries below. When off (default), only the Geo zone applies.

Countries: the allowed destination countries. Leave it empty to allow all countries enabled in the store. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations to storage/logs/vfd_imle_debug.log.php (on OpenCart 4 system/storage/logs/vfd_imle_debug.log.php). The file cannot be read from the web. 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. When the file reaches 5 MB, it is moved to vfd_imle_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 iMile settings and the log. When off (default), the settings are kept for a re-install. Cached estimates and access tokens are always deleted.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The Secret key is not 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. The saved Secret key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the iMile price. If a Geo zone is set, Ignore shipping zones is off and the address is outside the geo zone, iMile 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: allowed countries (when Ignore shipping zones 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 iMile.

With the live estimate on, the extension sends iMile the ship-from country, province and city, the destination country, region, 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 delivery address with a city, and only when every product in the cart 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 default 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 price is calculated in your default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.

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

The extension 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. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method. Use the iMile portal for shipments.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox iMile is the first block on Extensions > Extensions > Shipping > VibeFox iMile > 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-imile 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, the iMile shipping method 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

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

The table price is shown instead of the iMile estimate: turn on Debug log, reload the checkout and look at the Log field on the extension page. Common reasons: Live estimate is off, the keys are missing, Ship-from city is empty, 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 change the request with the OpenCart event vfd_imile/live_request, and country codes with the event vfd_imile/live_country_code.

Prices are in the wrong currency: the price table is in the store default currency. 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 class to No tax.

Estimates look outdated after a change: click Save on the extension page. This clears the cached iMile estimates.

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

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox iMile. The license key and license status of this extension are always removed. OpenCart always resets Enable iMile, Sort order, Tax class and Geo zone. The cached estimates and access tokens are always removed. If Remove data on uninstall is on, the iMile settings 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 iMile in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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