VibeFox DHL Africa for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later with the cURL extension. The module refuses to install on older PHP versions or without cURL. 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

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox DHL Africa in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page 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 while you use test credentials. Enter the Ship from address. If your DHL account is not billed in your shop default currency, set DHL quote currency and Exchange rate. Optionally set country prices and a fallback cost (see Configuration). Click Save.

On install the module creates the DHL Express carrier with the delivery time text DHL Express courier. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox DHL Africa > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached DHL quotes. Prices and weights accept a decimal comma or point.

Warnings at the top of the page tell you when live rates are off because the API key, API secret or 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), when a quote currency is set without an exchange rate, and when the shop weight or dimension unit in International > Localization (Local units) is not known to the module (it is then read as kg or cm). If a value is not valid when you save (an empty name or one longer than 64 characters, a number that is not valid or negative, an exchange rate of 0, a minimum weight above the maximum weight, the quote currency, the origin country or the tax rule), an error names the field, the previous value of that field is kept, and the other settings are saved.

General

Enable DHL Express Africa: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the carrier name shown to the customer at checkout. Default: DHL Express. Required, up to 64 characters.

Tax: the tax rule of the carrier, or No tax. With a tax rule (and taxes enabled in the shop) the DHL rate is taken without the tax DHL quotes, and PrestaShop adds its own tax. With No tax the DHL rate is charged as quoted, tax included.

DHL Express account (needed for live rates only)

DHL API: which DHL interface is used. Only the fields of the chosen API are shown.

API key: your MyDHL API username (API key).

API secret: your MyDHL API password (API secret). After saving, the API key and API secret fields stay empty and show Saved — leave empty to keep it. Type a new value only to change it.

Remove the saved API key and API secret: shown only when a key or secret is saved. Turn it on and click Save to delete both.

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). Like the API secret, it is not shown again after saving.

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.

Test mode: use the DHL test environment. On by default. Test credentials only work in the test environment and production credentials only in production. Turn it off 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 your shop default currency, 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 carrier 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 your shop default 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 your shop default 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 carrier 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.

Fallback price basis: Per order 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 cart subtotal (products that need shipping, after discounts, before tax) from which this carrier is free. DHL is not asked. Leave it empty for never free.

Conditions

Minimum weight: hide the carrier below this cart weight, in kg. 0 means no limit. It cannot be greater than Maximum weight.

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

Minimum subtotal: show the carrier only if the cart subtotal (after discounts, before tax) is at least this amount. Leave it empty to always show it.

Availability without shipping zones

Ignore shipping zones: offer the carrier without assigning zones to it yourself. The carrier gets every zone, including zones you create later, and the countries below decide. Switching it off gives the carrier its own zones back.

Countries: the destination countries for that mode. Leave it empty to allow all countries you ship to. Used only with Ignore shipping zones.

Advanced

Debug log: writes rate calculations to logs/vfd_dhla_debug.log.php in the module 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 debug log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the module deletes the settings, the carrier, the saved DHL products of orders and the log. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the DHL Express price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: the countries of Ignore shipping zones, the cart weight and the minimum subtotal. If free shipping 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 built from the product dimensions in cm: the longest length, the widest width and the stacked heights. Products without dimensions add nothing. If no product has dimensions, a 10 x 10 x 10 cm box is used. 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, 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 carrier name. The customer does not see the DHL product. The price is calculated in your default currency, rounded and then shown in the customer's cart currency.

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 carrier is hidden. The reason is written to the debug log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

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 the order is placed, the module keeps the rate calculated for its cart. The order page in the back office then shows a DHL Express Africa block, so you know 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.

Calculated price (excl. tax): the price in your shop default currency.

Later recalculations of the cart, for example when the order is edited in the back office, do not change these values. Rates of carts that never became an order are removed after 30 days.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Africa is the first block on Modules > Module Manager > VibeFox DHL Africa > Configure, 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 shop. Below them are the line Product: presta-shipping-dhl-africa and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the DHL Express carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or turn on Ignore shipping zones and check Countries). Check the weight limits and Minimum subtotal. Without a live rate the carrier appears only if a country price or a fallback cost is set. Products can also be limited to certain carriers in the product page.

Live rates do not appear: check the warnings at the top of the module page (missing credentials or origin). Turn on Debug log, reload the checkout and look at the Log field on the module page. 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 shop uses another 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 rule in Tax so the DHL rate is taken without DHL's VAT, or choose No tax to charge the DHL amount as quoted.

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

The page says the DHL Express carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

For developers, the module provides the hooks actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest and actionVfdDhlaXmlRequest to change the API address, the customs declaration, the box and the DHL requests.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox DHL Africa and choose Uninstall. The license key, the license status and the cached DHL quotes are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, the saved DHL products of orders and the log are removed. If it is off, the carrier is only disabled and the settings and the DHL products of placed orders are kept. Installing the module again restores the carrier status it had before.

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