VibeFox DHL Africa for Adobe Commerce — Hilfe

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. DHL XML Services also need the PHP SimpleXML extension.

DHL Express account (for live rates only): live rates use the MyDHL API. You need your DHL Express account number and MyDHL API credentials: an API key and an API secret. Request them on the DHL Developer Portal (MyDHL API, "Get access") or from your DHL Express account manager. Accounts that still have DHL XML Services credentials (Site ID and password) can use them instead. If you only use fallback prices, you do not need DHL credentials.

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

2. Run bin/magento module:enable Vibefox_DhlAfricaShipping 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 DHL Africa. 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 the DHL API, enter the API key, API secret and your DHL account number. Keep Test mode on Yes while you use test credentials. Enter the Ship from address. If DHL does not quote in the base currency of your store, set DHL quote currency and Exchange rate. Optionally set country prices and a fallback cost (see Configuration). Set Enable DHL Express Africa to Yes and click Save Config.

The module adds the DHL Express shipping method to Magento. Customers see it as DHL Express - Courier (method title and method name). It is off after installation (Enable DHL Express Africa = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox DHL Africa, 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 only from the Default Config scope, so set it there. Save Config saves the whole page and clears the cached DHL quotes. Prices and weights accept "9.99" and "9,99".

If Sort order is not a whole number, or Method name is empty or longer than 64 characters, Magento shows an error and nothing on the page is saved. Other invalid values are reported with a warning that names the field; the previous value of that field is kept, and the other settings are saved: a Method title that is empty, longer than 64 characters or contains one of the characters < > ; = # { }; a number field that does not contain a number of 0 or more; an Exchange rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg) (both keep their previous values); an unknown quote currency or origin country.

While Enable DHL Express Africa is Yes, warnings after saving tell you when live rates are off because the MyDHL API key, API secret or DHL account number is missing (or, with XML Services, the Site ID or password), when the origin country or city is missing, when XML Services are selected (DHL is retiring them), and when a DHL quote currency is set without an exchange rate. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable DHL Express Africa: shows or hides DHL Express at checkout. Default: No.

Method title: the shipping method name shown to the customer in the cart and at checkout (the carrier title in Magento). Default: DHL Express. Required, at most 64 characters, without < > ; = # { }.

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

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

DHL Express account (needed for live rates only)

Without credentials the method uses the fallback prices.

DHL API: which DHL interface is used.

API key: your MyDHL API username (API key). It is never shown to customers or written to the log.

API secret: your MyDHL API password (API secret).

Magento stores the API key, the API secret and the XML password encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved value, clear the field and click Save Config.

XML Site ID: your DHL XML Services Site ID (legacy API only). Clearing it also removes the saved XML password.

XML password: your DHL XML Services password (legacy API only).

DHL account number: your DHL Express account number (9 digits). The MyDHL API requires it. With XML Services it returns your account rates instead of published rates. Spaces are removed.

Test mode: use the DHL test environment. Default: Yes. Test credentials only work in the test environment and production credentials only in production. Set it to No when you go live.

Ship from

The address DHL collects the parcels from. The rate depends on it.

Origin country: the country you ship from.

Origin city: the city you ship from, for example Johannesburg. The MyDHL API requires it.

Origin postcode: leave it empty for countries without postcodes (for example Kenya, Nigeria, Ghana).

Rates

All prices are in the base currency of the website, tax excluded. The live rate is the cheapest DHL Express product for the parcel. If DHL is not configured, fails or has no service for the route, the country price is used, then the fallback cost. With neither, the method is hidden.

DHL quote currency: DHL quotes in the currency of your DHL account country (for example ZAR, NGN or KES). If DHL returns no amount in the base currency, the live rate is converted from this currency with the exchange rate below. Otherwise it is not used. Default: — None —.

Exchange rate: how much 1 unit of the DHL quote currency is in the base currency, for example 1 ZAR = 0.05. It must be greater than 0. Leave it empty for no conversion. The rate is a manual setting.

Fallback cost: a flat cost when there is no live rate and no country price. Leave it empty to hide the method in that case.

Country prices: a fallback price per destination country, one per line: CC:Price, for example ZA:25.00. Used when there is no live rate. Lines in another format are ignored, and a warning on save lists them. If a country appears twice, the last line is used.

Fallback price basis: Per order (default) charges the price once. Per item (multiplied by the cart quantity) multiplies it by the number of items. Applies to the country price and the fallback cost only. The live DHL rate is always for the whole parcel.

Free shipping from: the subtotal of the products that need shipping (after discounts, before tax, in the base currency) from which this method is free. DHL is not asked. Leave it empty for never free.

The module has no tax field. Tax on shipping is set in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. When a tax class for shipping is set and shipping prices are entered without tax, the DHL rate is taken without the tax DHL quotes, and Magento adds its own tax. Without a tax class for shipping, or when shipping prices include tax, the DHL amount is charged as quoted.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit. It cannot be greater than Maximum weight (kg).

Maximum weight (kg): hide the method above this cart weight. Default: 70 (also used when the field is empty). 0 means no limit.

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

Ship to Applicable Countries: All Allowed Countries offers DHL Express for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

Advanced

Debug log: writes every rate calculation to var/log/vfd_dhla_debug.log.php in the Magento folder. The file cannot be opened from the web. DHL errors are always logged, even when this is off. Credentials and customer addresses are never logged.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes in the Default Config scope, uninstalling the module with its data deletes the DHL settings and the log (see Uninstall). The license key and the cached quotes are always removed. The DHL products saved with orders are order history and are never deleted.

How it works at checkout

At the shipping step Magento asks the module for the DHL Express price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. Magento first checks the countries, then the module checks the cart weight and the minimum subtotal. If Free shipping from applies, the price is 0 and no request goes to DHL.

Otherwise the module sends DHL the origin and destination (country, city, postcode), the cart weight converted to kg (at least 0.5 kg) and one box of 10 x 10 x 10 cm: Magento products have no standard dimensions, so volumetric weight is not calculated. Shipments to another country are declared for customs, with the cart subtotal as the declared value. Domestic shipments are not declared. The pickup date is today in the time zone of the store, or Monday at weekends. A live rate is requested only after the customer has entered a city (with XML Services, a city or a postcode). Before that, the fallback prices apply.

The cheapest DHL Express product is shown as one price with your method title and method name. The customer does not see the DHL product. The price is calculated in the base currency, rounded to 2 decimals; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

A Magento cart price rule with free shipping makes the price 0. The method still needs a live rate or a fallback price to appear.

Each quote is cached for 1 hour per parcel and route. A failed request is cached for 10 minutes, so the checkout does not wait for DHL on every refresh. The API timeout is 12 seconds. If DHL returns an error, has no service or answers in an unusable currency, the customer sees no error: the fallback price is used or the method is hidden. The reason is written to the log.

The module calculates rates only. It does not create DHL shipments, print labels or commercial invoices, book pickups, track parcels, offer DHL service points, let the customer choose between DHL products, pack several boxes, add insurance or quote duties and taxes. The quote is for the shipping only. Duties and import taxes are paid by the receiver.

Orders

When an order is placed with DHL Express (at the storefront checkout or with Create New Order in the Admin), the module stores the rate calculated for its cart with the order. On the admin order page (Sales > Orders > View, Information tab) the DHL Express Africa block shows what to book with DHL:

DHL product: the DHL Express product of the live rate, for example "EXPRESS WORLDWIDE (P)". Shown only for live rates.

Price source: Live DHL rate, Fallback price (no live rate) or Free shipping threshold. An order with free shipping by a cart price rule also shows Free shipping threshold.

Calculated price (excl. tax): the price in the base currency.

The block also works for older orders and when the module is switched off.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Africa is the first row of the VibeFox DHL Africa group in Stores > Configuration > Sales > Delivery Methods, above the settings, in the Default Config scope. 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-dhl-africa 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 DHL Express 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

DHL Express does not appear at checkout: check that the license is active and Enable DHL Express Africa is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum subtotal. Without a live rate the method appears only if a country price or a Fallback cost is set.

Live rates do not appear: check the warnings shown after Save Config (missing credentials or origin). Turn on Debug log, reload the checkout and look at the Log field in the Advanced section. DHL errors such as an HTTP error from the MyDHL API, no products for the route or a currency problem are always logged. Check that Test mode matches your credentials, and that the customer address has a city.

DHL returns the rate in ZAR, NGN or KES but my store uses another base currency: the log says DHL quote not usable. Set DHL quote currency to that currency and enter the Exchange rate. Without it the live rate is not used and the fallback prices apply.

I have old DHL XML Services credentials: choose XML Services (legacy) in DHL API. Switch to the MyDHL API when you receive MyDHL credentials.

Tax is charged twice on shipping: set a Tax Class for Shipping with shipping prices entered without tax, so the DHL rate is taken without DHL's VAT, or do not tax shipping to charge the DHL amount as quoted.

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

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

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

The license key, the license status and the cached DHL quotes are always removed. If Remove data on uninstall is Yes in the Default Config scope, the DHL settings and the log are removed too. If it is No, the settings are kept for a re-install. The DHL products, price sources and prices saved with orders stay with the orders.

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