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

Aramex account (for live rates only): live rates use the Aramex Rate Calculator API. Aramex gives API access to its account holders. Ask your Aramex account manager or see the Aramex Developers Solution Center on the Aramex website. You need six values: API username (usually an e-mail address), password, account number, account PIN, account entity (for example DXB) and account country code (for example AE). If you only use fixed prices per country, you do not need an Aramex account.

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-aramex-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/AramexShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_AramexShipping 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 Aramex. 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. Choose how the shipping cost is calculated and fill in the matching sections: prices per country, or the Aramex API account and the ship-from address (see Configuration). Set Enable Aramex to Yes and click Save Config.

The module adds the Aramex shipping method to Magento. Customers see it as Aramex - Express (method title and method name). It is off after installation (Enable Aramex = No), and the default pricing mode is fixed prices per country.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Aramex, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached Aramex rates. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, or one longer than 64 characters; a Sort order that is not a whole number; an Account country code that does not have 2 letters; a weight or amount field that does not contain a number of 0 or more; a Currency conversion rate that is not greater than 0.

General

Enable Aramex: shows or hides Aramex at checkout. Default: No.

Method title: the carrier name shown to the customer in the cart and at checkout. Default: Aramex. Required, at most 64 characters.

Method name: shown after the method title, as "Method title - Method name". Default: Express. Required, at most 64 characters.

Shipping cost: how the price is calculated.

The reason for a missing live rate is written to the debug log. It is never shown to the customer.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

Aramex API account (needed for live rates only; all six fields are required)

Username: your Aramex API user name, usually an e-mail address. Clearing it also clears the saved password.

Password: your Aramex API password. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete it, clear the field (or the Username) and click Save Config.

Account number: your Aramex customer account number. Clearing it also clears the saved PIN.

Account PIN: the PIN of your Aramex account. Stored encrypted and masked like the password.

Account entity: the Aramex entity (office) code of your account, for example DXB, AMM or RUH.

Account country code: the 2-letter country code of your Aramex account, for example AE.

Aramex service (used for live rates)

If the delivery address is in the origin country, the shipment is quoted as Domestic. All other shipments are quoted as International express.

International service: the Aramex product for shipments abroad: PPX Priority Parcel Express (default), PDX Priority Document Express, PLX Priority Letter Express, DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express or GDX Ground Document Express.

Domestic service: the Aramex product for shipments within the origin country: ONP Overnight Parcel (default), OND Overnight Document, SMP Same Day Parcel, SMD Same Day Document, SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express or HVY Heavy (20 kg and more).

Payment type: who pays Aramex for the shipment: Prepaid (shipper pays) (default), Collect (receiver pays) or Third party. Usually Prepaid.

API weight unit: the unit sent to Aramex, Kilograms (KG) (default) or Pounds (LB). Product weights are converted 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 volumetric weight is not calculated: the chargeable weight is the actual cart weight. The minimum is 0.5 kg, which also covers products without a weight.

Currency conversion rate: Aramex is asked to quote in the base currency of the website. If it still answers in another currency, the rate is multiplied by this number (1 unit of the Aramex currency = X units of your base currency). Leave it empty to reject such quotes, so a customer is never charged in the wrong currency.

Ship from (used for live rates)

Aramex needs the city of the shipper. Empty fields are taken from Stores > Configuration > Sales > Shipping Settings > Origin when the origin country is the same.

Origin country: the country you ship from. The first option, Shipping Settings › Origin country (default), uses the country of the Magento shipping origin.

Origin city: the city you ship from. Aramex requires it for live rates. Empty means the city of the shipping origin.

Origin state / emirate: optional.

Origin postcode: optional.

Fixed prices (used when Shipping cost is fixed prices, and as the fallback for live rates)

Price per country: a table of countries and prices in the base currency of your store, tax excluded. Click Add country to add a row and Delete to remove one. Choose * All other countries for the price of every country without its own row. Countries without a price (when there is no * row) get no fixed rate, so the method is hidden for them. Rows without a country or with a price that is not a number of 0 or more are dropped on save. If a country is listed twice, the last row is kept.

Fixed price applies: Per order (default) charges the price once. Per item (price × quantity) multiplies it by the number of items in the cart. Live Aramex rates are always per shipment.

Conditions

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

Maximum weight (kg): hide the method above this cart weight. Default: 100. 0 means no limit, an empty field means 100 kg.

Minimum order amount: show the method only when the subtotal of the products that need shipping (after discounts, before tax, in the base currency) is at least this amount. Leave empty to always show it.

Free shipping: Yes turns on free Aramex delivery from the amount below. Default: No.

Free shipping from: the subtotal of the products that need shipping (after discounts, before tax, in the base currency) from which delivery is free. Used only when Free shipping is Yes.

Ship to Applicable Countries: All Allowed Countries offers Aramex 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, it uses the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Advanced

Debug log: writes rate calculations and API errors to var/log/vfd_armx_debug.log.php in the Magento folder. The file cannot be opened from the web. Passwords, PIN and customer addresses are never logged. Turn it off when you are done. Default: No.

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 Aramex settings and the log (see Uninstall). When No, they are kept for a re-install. The license key and the cached rates are always removed.

How it works at checkout

At the shipping step Magento asks the module for the Aramex price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. The module first checks the conditions: countries, cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Aramex. A Magento cart price rule with free shipping also makes the price 0.

In the fixed mode the price is taken from the table. In the live modes the module sends Aramex the origin and delivery addresses, the cart weight, the service and the base currency of your store, and uses the returned total. A live rate is requested only when the delivery address has a city or postcode. The price is calculated in the base currency and rounded to 2 decimals; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

Each answer is cached for 1 hour, so the same cart does not trigger a new request. A failed request is cached for 10 minutes, so the checkout does not wait for Aramex on every refresh. The API timeout is 10 seconds.

If Aramex returns an error, a zero amount or a quote in another currency without a conversion rate, the customer sees no error. The method is hidden, or the fixed price is used in the fallback mode. The reason is written to the debug log. An unexpected error is also written to var/log/system.log.

The module calculates rates only. It does not create Aramex shipments, print labels, book pickups, track parcels or let customers choose an Aramex office. The parcel is always sent to Aramex as one piece.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Aramex is the first row of the VibeFox Aramex 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-aramex 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 Aramex 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

Aramex does not appear at checkout: check that the license is active and Enable Aramex 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. In the fixed mode, check that the country or * All other countries has a price.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. It shows the reason: missing API credentials, the Aramex error code, no origin city, no delivery city or postcode, a weight or amount limit, or a quote in another currency. With Aramex live rates, fixed prices if the API fails customers still get the fixed price while you fix the problem.

Error ERR75 in the log: Aramex rejected the login. Check the username, password, account number, PIN, entity and country code with your Aramex account manager.

Quote in another currency is rejected: Aramex answered in a currency other than the base currency of your store. Enter Currency conversion rate, or ask Aramex to quote in your currency.

Tax is charged twice on shipping: Aramex totals may already include VAT. Do not tax shipping in Tax Class for Shipping.

Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached Aramex rates.

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_AramexShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_AramexShipping to remove the data, then bin/magento module:disable Vibefox_AramexShipping, delete the folder app/code/Vibefox/AramexShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached rates are always removed. If Remove data on uninstall is Yes, the Aramex settings and the log are removed too. If it is No, the settings are kept for a re-install. Orders placed with Aramex are not changed.

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