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

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

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_aramex folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Aramex, 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. Choose how the shipping cost is calculated and fill in the matching sections (see Configuration).

6. Add VibeFox Aramex to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Aramex. 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 Aramex rates are cleared.

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. Default: Aramex.

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.

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

Username: your Aramex API user name, usually an e-mail address.

Password: your Aramex API password.

Account number: your Aramex customer account number.

Account PIN: the PIN of your Aramex account.

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), Collect (receiver pays) or Third party. Usually Prepaid.

API weight unit: the unit sent to Aramex, KG or LB. Product weights are converted from your store weight unit. The chargeable weight is the larger of the actual weight and the volumetric weight (length × width × height in cm / 5000). The minimum is 0.5 kg, which also covers products without a weight.

Currency conversion rate: Aramex is asked to quote in your store currency. If it still answers in another currency, the rate is multiplied by this number (1 unit of the Aramex currency = X units of your store currency). Leave it empty to reject such quotes, so a customer is never charged in the wrong currency. Both a point and a comma are accepted as the decimal separator.

Ship from (origin address) (used for live rates)

Origin country: the country you ship from. By default it is your store country.

Origin city: the city you ship from. Aramex requires it.

Origin state / emirate: optional.

Origin postcode: optional.

If the origin country is your store country, empty fields are taken from the store address in WooCommerce > Settings > General.

Fixed prices (used in the fixed mode and as the fallback for live rates)

Price per country: a table of 2-letter country codes and prices in your store currency. Click Add row to add a country and the cross to remove one. Use * as the country code for all other countries. Countries without a price (when there is no * row) get no fixed rate, so the method is hidden for them.

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

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: 100. 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.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Free shipping: turn on free Aramex delivery from the amount below.

Free shipping from: the cart subtotal (after discounts, before tax) from which delivery is free. Used only when Free shipping is on.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. Aramex live rates may already include VAT. In that case choose None so tax is not charged twice.

Availability without shipping zones

Ignore shipping zones: offer Aramex 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 and API errors to logs/vfd_armx_debug.log.php in the plugin folder. The file cannot be opened from the web. Passwords, PIN, account number and customer addresses are masked. Turn the log off when you are done.

Remove data on uninstall: when on, deleting the plugin removes all its settings, zone methods, cached rates and logs. 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 as Aramex (free) and no request goes to Aramex.

In the fixed mode the price is taken from the table. In the live modes the plugin sends Aramex the origin and delivery addresses, the chargeable weight, the service and your store currency, and shows the returned total. A live rate is requested only after the customer has entered a city or postcode. 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.

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 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 plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Aramex. 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, Aramex 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

Aramex 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. In the fixed mode, check that the country or * has a price.

Live rates do not appear: turn on Debug log, reload the checkout and open logs/vfd_armx_debug.log.php in the plugin folder. It shows the reason: missing API credentials, the Aramex error code, no origin city, no delivery city or postcode yet, 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 your store currency. Enter Currency conversion rate, or ask Aramex to quote in your currency.

Tax is charged twice on shipping: Aramex totals may already include VAT. Set Tax status to None.

Rates look outdated after a change: save the settings page. This clears the cached Aramex rates.

Aramex sandbox: the plugin uses the production Aramex Rate Calculator. Developers can change the endpoint with the vfd_armx_api_url filter. The filters vfd_armx_rate_request, vfd_armx_number_of_pieces and vfd_armx_volumetric_divisor adjust the request, the number of pieces and the volumetric divisor.

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, cached rates and logs are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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