VibeFox DHL Africa 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.

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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_dhl_africa folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > DHL Express Africa, 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 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 store currency, set DHL quote currency and Exchange rate. Optionally set country prices and a fallback cost (see Configuration).

6. Add DHL Express Africa to your shipping zones 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 > DHL Express Africa. 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 of this option at checkout for this zone. Leave it empty to use the global Name.

Warnings above the settings tell you when live rates are off because credentials or the origin are missing, and when a quote currency is set without an exchange rate. Every time you save the settings, the cached DHL quotes are cleared. Prices and weights accept a decimal comma or point.

General

Enable/Disable: turns the method on or off in all zones at once.

Name: the shipping method name shown at checkout. Default: DHL Express.

Tax status: Taxable (with WooCommerce taxes enabled) takes the DHL rate without the tax DHL quotes, and WooCommerce adds its own tax. None charges the DHL rate 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).

XML Site ID: your DHL XML Services Site ID (legacy API only).

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.

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 store currency. 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 your store currency, the live rate is converted from this currency with the exchange rate below. Otherwise it is not used.

Exchange rate: how much 1 unit of the DHL quote currency is in your store currency, for example 1 ZAR = 0.05. 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.

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.

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 from which this method is free. DHL is not asked. Leave empty for never free.

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: 70. 0 means no limit.

Minimum subtotal: show the method only if the cart subtotal is at least this amount. Leave empty to always show it.

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

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below, even if the matched shipping zone does not contain it.

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

Advanced

Debug log: logs rate calculations in WooCommerce > Status > Logs, source vfd-dhl-africa. DHL errors are always logged, even when this is off. Credentials and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes its settings and zone methods. Deactivating the plugin never deletes data.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the cart weight, the minimum subtotal and the excluded shipping classes. If free shipping applies, the customer gets free delivery and no request goes to DHL.

Otherwise the plugin 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. International shipments are declared as goods, with the cart subtotal as the declared value, so DHL quotes parcel products. Domestic shipments are not declared. A live rate is requested only after the customer has entered a city (with XML Services, a city or a postcode).

The cheapest DHL Express product is shown as one rate with your title. The customer does not see the DHL product or a delivery time. The product name (for example "EXPRESS WORLDWIDE (P)") is saved as DHL product in the order's shipping line, so you know what to book.

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 or has no service, the customer sees no error: the fallback price is used or the method is hidden.

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

License key

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

DHL Express 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 subtotal and Excluded shipping classes. 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 at the top of the settings page (missing credentials or origin). Turn on Debug log and open WooCommerce > Status > Logs, source vfd-dhl-africa. DHL errors such as wrong credentials, no service for the route or a currency problem are always logged. Check that Test mode matches your credentials.

DHL returns the rate in ZAR, NGN or KES but my store uses another currency: 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 Tax status to Taxable so the DHL rate is taken without DHL's VAT, or to None to charge the DHL amount as quoted.

Rates look outdated after a change: save the settings page. This clears the cached DHL quotes.

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 settings. It only clears the cached DHL quotes. To remove the plugin, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, as are the cached quotes. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Orders are never changed, and existing orders keep their shipping lines.

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