VibeFox iMile for Adobe Commerce — المساعدة
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4, with the cURL and JSON extensions.
iMile tariff: the prices you agreed with the iMile sales team. You enter them in the price table in the base currency of your store.
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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-imile-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/ImileShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_ImileShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox iMile. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).
4. Enter your iMile prices in Country prices. Optionally fill in the Live rates (API) section and set Live estimate to Yes (see Configuration). Set Enable iMile to Yes and click Save Config.
The module adds the iMile shipping method to Magento. Customers see it as iMile - Courier delivery (carrier title and method name). It is off after installation (Enable iMile = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox iMile, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached iMile estimates and access tokens. Amounts and weights accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Carrier title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; an amount or weight field that does not contain a number of 0 or more; a Minimum weight (kg) greater than the Maximum weight (kg).
While Enable iMile is Yes and Live estimate is Yes, warnings at the top of the group show settings that keep the live estimate from working: the Customer ID or Secret key is empty (with no price table and no fallback price the method is hidden), the ship-from city or country is missing or is not an iMile market, there are no exchange rates, or the price table and the fallback price are empty, so an API failure hides the method. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable iMile: shows or hides iMile at checkout. Default: No.
Carrier title: the carrier name shown in the cart and at checkout. Default: iMile. Required, at most 64 characters.
Method name: shown after the carrier title, as "Carrier title - Method name". Default: Courier delivery. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
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: set it to Yes to get the shipping cost from iMile. Default: No. With the live estimate off, nothing is sent to iMile during checkout.
Environment: Production (openapi.imile.com, the 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 and clicking Save Config also deletes the saved Secret key.
Secret key: the secret key (API key) issued by iMile together with the Customer ID. It signs the requests. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.
Signature: how requests are signed.
Ship-from country: the country you ship from. The default, Shipping origin country, uses the country in Stores > Configuration > Sales > Shipping Settings > Origin. The list contains only the countries the module has iMile country codes for, with the iMile code in brackets.
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 city of the shipping origin.
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 (default), Sensitive (cosmetics, liquids and similar), Battery (goods with a battery), PureBattery (batteries, power banks), File (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 the base currency of your store, for example "SAR = 0.25" or "AED = 0.25". A point or a comma is accepted as the decimal separator. A rate is not needed for the base currency itself. Without a rate, estimates in that currency are not used and the price table is used instead. If your base currency is not USD, 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 base currency of your store, tax excluded. If it is in AED, SAR or another currency, convert it first.
Country prices: one row per destination country. Click Add country to add a row and Delete 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 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. A base price of 0 means free shipping to that country. Invalid and negative prices are cleared and rows without any price are removed when you save. Only the first row per country is kept.
Price for countries not in the table: a price in the base 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 to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so no parcel size is sent to iMile and volumetric weight is not calculated. The price may differ from an iMile tariff that uses volumetric weight.
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 or an empty field means no limit.
Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to always show it.
Free shipping from: the cart subtotal from which iMile delivery is free. No request goes to iMile. Leave empty to never offer free shipping.
Ship to Applicable Countries: All Allowed Countries offers iMile for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries.
The module has no tax field. If your store charges tax on shipping, the tax class is set in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. If the prices in the table and the iMile estimates already include VAT, do not tax shipping there.
Advanced
Debug log: writes rate calculations to var/log/vfd_imle_debug.log.php in the Magento folder. The file cannot be opened from the web. Failed iMile requests are always logged, even when this is off. The Secret key and the customer's city and postcode are never written to the log. Turn the log off when you are done.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the iMile settings and the log (see Uninstall). The license key and the cached estimates are always removed.
How it works at checkout
At the shipping step Magento asks the module for the iMile price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum order amount. If Free shipping from applies, the price is 0 and no request goes to iMile. A Magento cart price rule with free shipping also makes the price 0.
With the live estimate on, the module sends iMile the ship-from country, province and city, the destination country, region, city and postcode, the cart weight in kg, 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 base currency of your store 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. Magento then shows the price in the customer's currency and adds tax on shipping if your store charges it.
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. Orders keep the standard Magento shipping description and amount. 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 row of the VibeFox iMile group in Stores > Configuration > Sales > Delivery Methods, 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: magento-shipping-imile and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.
One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data 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 Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Check that the country or * has a row in Country prices, or that Price for countries not in the table is set.
The table price is shown instead of the iMile estimate: set Debug log to Yes, reload the checkout and look at the Log field in the Advanced section. Common reasons: Live estimate is No, 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 at the top of the group.
"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: the customer's city and your Ship-from city must match the iMile city list.
Prices are in the wrong currency: the price table is in the base currency of your store. 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 and the iMile estimates already include VAT, do not tax shipping in Tax Class for Shipping.
Estimates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached iMile estimates.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_ImileShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_ImileShipping to remove the data, then bin/magento module:disable Vibefox_ImileShipping, delete the folder app/code/Vibefox/ImileShipping and run bin/magento setup:upgrade.
The license key, the license status, the cached estimates and access tokens are always removed. If Remove data on uninstall is Yes, the iMile settings and the log are removed too. If it is No, the settings are kept for a re-install. Existing orders are not affected.
iMile is a trademark of its respective owner. This module is not affiliated with or endorsed by iMile.