VibeFox DHL Africa 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 with the cURL extension. 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 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_dhl_africa-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_dhl_africa.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_dhl_africa-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 DHL Africa 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 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 default currency, set DHL quote currency and Exchange rate. Optionally set country prices and a fallback cost (see Configuration). Turn on Enable DHL Express Africa and click Save.

OpenCart 4

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached DHL quotes. Prices and weights accept a decimal comma or point. Only admin users with the modify permission for this extension can save the settings.

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 store weight or length unit is not known to the extension (product weights are then read as kg and dimensions as cm; add a weight class with the unit kg in System > Localisation > Weight Classes or a length class with the unit cm in System > Localisation > Length Classes).

If a value is not valid when you save (an empty method title 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, an unknown quote currency, origin country, tax class or geo zone, a sort order that is not a whole number), a warning above the settings names the field, for example Select a valid origin country. It was not saved. The previous value of that field is kept, and the other settings are saved.

General

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

Method title: the shipping method name shown to the customer at checkout. Default: DHL Express. Required, at most 64 characters.

Tax class: the tax class of the shipping cost, or No tax (default). With a tax class (and taxes enabled in the store) the DHL rate is taken without the tax DHL quotes, and OpenCart adds its own tax. With No tax the DHL rate is charged as quoted, tax included.

Sort order: the position of DHL Express among the shipping methods at checkout. A whole number.

DHL Express account (needed for live rates only)

DHL API: which DHL interface is used.

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 for the MyDHL API 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. OpenCart keeps the store address as free text, so the origin is always entered here. The note in this section shows your store country.

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

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 the coupon, before tax) from which this method is free. DHL is not asked. Leave it empty for never free.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default). 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 the coupon, before tax) is at least this amount. Leave it empty to always show it.

Availability

Geo zone: offer DHL Express only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not checked with Ignore shipping zones.

Ignore shipping zones: offer the method for the countries below (or every country, if the list is empty), whatever geo zone is selected.

Countries: the destination countries for that mode. Used only with Ignore shipping zones.

Advanced

Debug log: writes rate calculations to storage/logs/vfd_dhla_debug.log.php (on OpenCart 4 system/storage/logs/vfd_dhla_debug.log.php). The file cannot be read from the web. DHL errors are always logged, even when this is off. Credentials, the account number and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_dhla_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 settings, cached DHL quotes and the log. When off (default), everything is kept for a re-install. The DHL products of placed orders are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key, API secret and XML password 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. Saved credentials are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the DHL Express price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, DHL Express is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension then checks the conditions: the countries of Ignore shipping zones, the cart weight and the minimum subtotal. The subtotal 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 DHL.

Otherwise the extension sends DHL the origin and destination (country, city, postcode), the cart weight converted to kg from the product weight classes (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 in the store time zone, 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. The customer does not see the DHL product. 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 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 debug log.

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

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

Orders

When the order is placed, the extension keeps the rate calculated for its cart. Open the order in Sales > Orders: the DHL Express Africa panel above the order history 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.

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

The DHL product is not shown to the customer in e-mails or on the customer's order page. The order shows the method title and the shipping cost like any other OpenCart shipping method.

On OpenCart 4 the checkout keeps one order and updates it each time the customer confirms again. The panel then shows the latest rate of the checkout. If the customer switches to another shipping method, the panel is no longer shown for that order.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Africa is the first block on Extensions > Extensions > Shipping > VibeFox DHL Africa > 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-dhl-africa 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, the DHL Express shipping method 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

DHL Express does not appear at checkout: check that the license is active and Enable DHL Express Africa is on. Check Geo zone (or turn on Ignore shipping zones and check 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. Check that the products have Requires Shipping set to Yes.

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

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

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

For developers: the extension triggers the OpenCart events catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request and xml_request (same prefix), which can change the API address, the customs declaration, the box and the DHL requests.

Uninstall

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

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