VibeFox iMile for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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

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 iMile 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 iMile prices in the Price table. Optionally fill in the Live rates (API) section and turn on Live estimate (see Configuration). Click Save.

On install the module creates the iMile carrier with the delivery time text Courier delivery. The carrier is assigned to all zones and all customer groups. 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 iMile > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached iMile estimates and access tokens.

When Live estimate is on but cannot work, warnings appear above the settings: 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 shop weight unit is not known to the module: product weights are then taken as kilograms, so set the unit in International > Localization (Local units). When you save, the module checks that Method title is valid (64 characters max), that the amount and weight fields are numbers of 0 or more, that Minimum weight is not greater than Maximum weight and that the tax rule exists. Otherwise it shows an error and saves nothing.

General

Enable iMile: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Method title: the carrier name shown in the cart and at checkout. Default: iMile. Required.

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. By default it is your shop country (Shop country). The list contains only the countries the module 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 shop city from Shop Parameters > Contact > Stores.

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 shop default 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 shop 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 shop 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 trash icon 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 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 shop 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 carrier 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 and dimensions are converted from your shop units to kilograms and centimetres.

Conditions

Minimum weight: hide the carrier when the cart weighs less, in kg. 0 means no limit.

Maximum weight: hide the carrier when the cart weighs more, in kg. Default: 30. 0 means no limit.

Minimum order amount: show the carrier 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.

Tax: the tax rule of the carrier, or No tax. Choose No tax 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 whatever zone matches. On save the carrier is added to all zones, and zones created later get it too. Switching the option off removes those added zones again, so the carrier gets back the zones it had before.

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

Advanced

Debug log: writes rate calculations to logs/vfd_imle_debug.log.php in the module folder. The file cannot be opened 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.

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 iMile settings, the carrier, cached estimates and logs. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the iMile price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: allowed countries (when Ignore shipping zones is on), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to iMile.

With the live estimate on, the module 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 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 shop 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 carrier is hidden. The reason is written to the log. The price is calculated in your default currency and then shown in the customer's cart currency.

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 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 module works with a VibeFox license key from vibefox.net. The license block License — VibeFox iMile is the first block on Modules > Module Manager > VibeFox iMile > 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-imile 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 iMile 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

iMile does not appear at checkout: check that the license is active and Enable iMile 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. Check that the country or * has a row in the Price table, or that Price for countries not in the table is set. Products can also be limited to certain carriers in the product page.

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 module page. 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 actionVfdImileLiveRequest hook, and country codes with the actionVfdImileLiveCountryCode hook.

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

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

The page says the iMile carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox iMile and choose Uninstall. The license key and license status are always removed. The cached estimates and access tokens are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again restores the carrier status it had before.

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