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

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 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_aramex-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_aramex.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_aramex-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 Aramex 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. Choose how the shipping cost is calculated, fill in the matching sections (see Configuration), turn on Enable Aramex and click Save.

OpenCart 4

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached Aramex rates. If a value is wrong, nothing is saved and the page shows the reason, for example Enter a method title (1 to 64 characters)., a message that a field must be a number, or The account country code must have 2 letters, e.g. AE. Only admin users with the modify permission for this extension can save the settings.

General

The settings apply to every geo zone. You can limit the method to a geo zone and to countries in Conditions.

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

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

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 of Aramex among the shipping methods at checkout. A whole number.

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. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

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

Account PIN: the PIN of your Aramex account. Like the password, it is not shown again after saving.

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 (documents under 0.5 kg), 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 their weight class, and dimensions from their length class. 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 default 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 default currency). Leave it empty to reject such quotes, so a customer is never charged in the wrong currency.

Ship from (used for live rates)

Origin country: the country you ship from. The first option, Store country, uses the country of your store.

Origin city: the city you ship from. Aramex requires it. The OpenCart store address is free text, so the city is never taken from it: enter it here.

Origin state / emirate: optional.

Origin postcode: optional.

If the origin country is your store country, an empty state is taken from the region of your store in System > Settings > Store > Local.

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

Price per country: a list of countries and prices in your store default currency, tax excluded. Click Add country to add a row and the × button to remove one. Choose * All other countries for a price used for 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.

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 (default).

Maximum weight (kg): hide the method above this cart weight. Default: 100. 0 means no limit. If you leave the field empty, 100 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: turn on free Aramex delivery from the amount below.

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which delivery is free. Used only when Free shipping is on.

Tax class: the tax class of the shipping cost, or No tax (default). Aramex live rates may already include VAT. In that case choose No tax so tax is not charged on shipping twice.

Geo zone: offer Aramex only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones.

Countries: offer Aramex only for these destination countries. Leave it empty to allow all countries. This limit applies together with Geo zone.

Advanced

Debug log: writes rate calculations and API errors to storage/logs/vfd_armx_debug.log.php. The file cannot be read from the web. Passwords, PIN and customer addresses are never logged. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_armx_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 Aramex settings, cached rates and the log. When off (default), they are kept for a re-install.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The password and PIN are 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 password and PIN are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Aramex price. If a Geo zone is set and the address is outside it, Aramex 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, 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 Aramex.

In the fixed mode the price is taken from the table. In the live modes the extension sends Aramex the origin and delivery addresses, the chargeable weight, the service and your default currency, 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 your default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.

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 extension calculates rates only. It does not create Aramex shipments, print labels, book pickups, track parcels or let customers choose an Aramex office. It adds nothing to orders: the order shows the method title and the shipping cost like any other OpenCart shipping method. The parcel is always sent to Aramex as one piece.

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

License key

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

Aramex does not appear at checkout: check that the license is active and Enable Aramex is on. Check Geo zone, Countries, the weight limits and Minimum order amount. In the fixed mode, check that the country or * All other countries has a price. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension page. 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 your default 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 class to No tax.

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

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

For developers: the Aramex API address can be replaced with the setting vfd_armx_api_url (for tests); it has no field on the settings page.

Uninstall

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

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