VibeFox DHL Packstation 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). The location picker works with the standard OpenCart checkout.

PHP: 8.0 or later.

DHL API key: the list of locations comes from the free DHL Location Finder API. Register on the DHL developer portal (developer.dhl.com), create an app, add the "Location Finder - Unified" API and copy the app's API key. No DHL business contract is needed for this API. Without the key the method is hidden at checkout. Mind the request limit of your DHL app: every new postcode or city search is one API request.

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_packstation-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_dhl_packstation.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_packstation-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 Packstation 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. Paste the DHL API key, click Save, then click Test API key. Choose the location types and enter the country prices (see Configuration). Turn on Enable/Disable and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_dhl_packstation.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 Packstation, 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/Disable and save. The default price list has prices for Germany and Austria and a price for other countries. If you install the extension again after an uninstall, the settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save clears the location cache. If a field has an error (an invalid name or one longer than 64 characters, a radius or number of results that is not a whole number, a number that is not valid or negative, Min weight (kg) greater than Max weight (kg), a sort order that is not a whole number, an unknown tax class or geo zone), nothing is saved and the error is shown. Only admin users with the modify permission for this extension can save the settings.

Warnings at the top of the page tell you when the DHL API key is empty, when no location type is enabled (in both cases the method is not shown at checkout), when country price entries are not in the CC:PRICE format (these entries are ignored), and when there is no weight class with the unit kg in System > Localisation > Weight Classes (product weights are then read by the unit name of their class: kg, g, lb or oz, unknown units as kg).

General

The settings apply to every geo zone.

Enable/Disable: enables DHL Packstation at checkout. Default: off.

Name: the shipping method name shown to the customer. Default: DHL Packstation. Required, at most 64 characters, without the characters < > ; = # { }.

Tax Class: the tax class of the shipping cost, or --- None --- (default). OpenCart adds this tax on top of the prices below. With --- None --- the prices are final.

Sort Order: the position of DHL Packstation among the shipping methods. A whole number.

DHL Location Finder API

DHL API key: the "API Key" of your app on developer.dhl.com. Without it the method is hidden at checkout. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it.

Remove the saved API key: shown when a key is saved. Tick this box and save to delete the stored key.

Connection test: the Test API key button searches the locations near 53113 Bonn with the saved key and clears the location cache. Save the settings first. It shows how many locations were found (Connected: … DHL locations found near 53113 Bonn.), that DHL rejected the key (401/403), or that the API did not answer correctly (details in the debug log).

Pickup locations

At checkout the customer sees the locations near their shipping postcode and can search another postcode or city.

Location types: which DHL locations the customer can choose: Packstation (parcel locker), Post Office (Postfiliale) and DHL Parcel Shop (Paketshop). All three by default. If none is selected, the method is hidden. For a Packstation the customer must enter their DHL Postnummer.

Search radius (meters): the radius around the searched postcode or city. Default: 5000. A whole number; values below 100 or above 25000 m (the DHL maximum) are moved to that limit.

Max results: the maximum number of locations shown per search. Default: 20. A whole number; DHL allows up to 50, larger values are reduced to 50.

Shipping address: use the chosen location as the order's shipping address. On by default. Address line 1 becomes for example "Packstation 105" (or "Postfiliale 502" for a post office or parcel shop), line 2 "Postnummer" with the number, plus the postcode, city and country of the location, so labels printed from the order go to the right place. Name, company and phone come from the customer's address. The region is emptied. The customer's address book is not changed.

Prices (the section title shows your store default currency)

Country prices: the price per destination country in the store default currency, tax excluded, format CC:PRICE, separated by commas or new lines. Default: DE:4.99, AT:5.99. A decimal comma also works (DE:4,99).

Other countries: the price for a destination country that is not in Country prices. Default: 5.99. Leave it empty to hide the method for such countries.

Calculation: Per order (default) charges the price once. Per item (price x quantity) multiplies it by the number of items in the cart.

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which this shipping is free. Leave empty for never free.

Availability

Min weight (kg): the minimum cart weight. Product weights are converted from their weight class. 0 means no limit (default).

Max weight (kg): the method is hidden above this cart weight. Default: 31.5, because a Packstation takes parcels up to 31.5 kg. 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 value. Leave empty to always show it.

Geo Zone: offer the method only in this geo zone. All Zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used with Ignore shipping zones.

Ignore shipping zones: when on, the method is offered for the countries below (all countries if the list is empty), whatever the geo zone of the address.

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

Advanced

Debug log: writes API requests and checkout steps to storage/logs/vfd_dhlp_debug.log.php (on OpenCart 4 system/storage/logs/vfd_dhlp_debug.log.php). The file cannot be read from the web. API errors are always logged, even when this is off. The API key, the Postnummer and customer addresses are never written. When the file reaches 5 MB, it is moved to vfd_dhlp_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 searches, the log and the locations of unfinished checkouts. The chosen locations stay in the orders. When off (default), everything is kept for a re-install.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key is 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 API key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the DHL Packstation price. If a Geo Zone is set (and Ignore shipping zones is off) and the address is outside it, the method 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 checks that an API key and at least one location type are set, the allowed countries (with Ignore shipping zones), the cart weight and the minimum subtotal. It then takes the price for the destination country (or the price for other countries) and applies free shipping if the subtotal is high enough. The subtotal is the price of the products that need shipping, after the coupon discount and before tax. The price does not depend on the location, and no request goes to DHL for it. It is calculated in your default currency and shown to the customer in their currency with the tax of the selected Tax Class.

The extension does not create DHL shipments, print labels or track parcels. Use the DHL business customer portal or a label tool: with Shipping address on, the order already contains the Packstation address and Postnummer. The extension does not calculate live DHL rates and shows no map. There is no manual entry of a Packstation number.

Pickup points

When the customer selects DHL Packstation at the delivery method step, a picker appears under the method. The DHL locations near the delivery postcode and city are loaded. The customer can type another postcode or city and click Search. Locations are grouped by type (Packstation, Post Office, Parcel Shop) and sorted by distance. If nothing is found, the customer sees No DHL locations found near "…". Try another postcode or city.

For a Packstation the customer must enter the DHL Postnummer, their 6-12 digit DHL customer number from the DHL app or DHL account. For other locations it is optional. The choice is saved as soon as it is made. On Continue the server checks it again: the location must be one of the DHL search results in the delivery country. Without a location the customer sees Please choose a DHL Packstation or post office for delivery. and cannot continue. A missing Postnummer for a Packstation shows Please enter your DHL Postnummer - it is required for delivery to a Packstation., an invalid one The DHL Postnummer must consist of 6 to 12 digits.

Search results are cached for 12 hours. An empty or failed search is cached for 10 minutes, so the checkout does not wait for DHL on every refresh. With the default OpenCart file cache, entries live at most as long as the store cache lifetime (1 hour by default), so the list is then refreshed once an hour. The API timeout is 12 seconds. If the DHL API cannot be reached, the customer sees DHL locations cannot be loaded right now. Please try again later or choose another shipping method. A location the customer had already chosen is still accepted.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks DHL Packstation in the window Shipping method options. The picker appears in that window under the method and works as described above. The Continue button of the window does not go on without a valid location or, for a Packstation, without the Postnummer, with the same messages.

When the order is placed, the location (ID, type, number, name, address) and the Postnummer are saved with the order. The location is added to the shipping method of the order as DHL pickup location: and DHL Postnummer:, so it appears wherever OpenCart shows the shipping method: the customer's order page, the order e-mails and the invoice. If Shipping address is on, the order's shipping address is replaced by the address of the location.

OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The location, the shipping method text and the address of the order are updated with it.

Orders

Open the order in Sales > Orders. The DHL pickup location panel above the order history shows the location, its type and ID, and the Postnummer, also after the extension is switched off. An order without a location shows No DHL location was selected for this order.

Click Change, search by postcode or city, choose another location from the DHL list, change the Postnummer if needed and click Save location. You can also change only the Postnummer. The shipping method text of the order is updated. If Shipping address is on, the shipping address of the order is updated too, starting again from the customer's original address. Each change adds an entry DHL pickup location changed to: … to the order history, with the current order status and without notifying the customer. Changing the location needs the modify permission for orders; access to the extension settings is not needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Packstation is the first block on Extensions > Extensions > Shipping > VibeFox DHL Packstation > 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-packstation 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 Packstation 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 Packstation does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo Zone (or turn on Ignore shipping zones and check Countries (ignore zones)). Check that the DHL API key is filled in, at least one location type is selected, the destination country has a price (or Other countries is set), and the weight and subtotal rules do not hide it. Check that the products have Requires Shipping set to Yes.

No locations are shown: click Test API key. If DHL rejects the key (401/403), check the key and that your app has the "Location Finder - Unified" API. Turn on Debug log, reload the checkout and look at the Log field on the extension page. Check that the request limit of your DHL app is not reached.

No locations near an address: increase Search radius (meters) or Max results, or let the customer search another postcode or city. A Packstation without a number in the DHL data is not listed.

The customer sees "Enter your postcode or city to see DHL locations near you.": the delivery address has no postcode and no city. The customer can type one into the search field.

Change on the admin order page says "Please choose a DHL location of the search - nothing was changed.": search by postcode or city and choose a location from the results. If the order has no location yet, a location must be chosen before the Postnummer can be saved.

The DHL pickup location panel is missing on the order page: the panel is shown only for orders shipped with DHL Packstation (it stays when the extension is switched off).

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

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox DHL Packstation. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort Order, Tax Class and Geo Zone. The location cache and the extension's events are always removed. If Remove data on uninstall is on, the settings, the log and the locations of unfinished checkouts are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The chosen locations always stay in the orders, and existing orders keep their shipping method, cost and address.

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 Packstation in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

DHL and Packstation are trademarks of their respective owners. This extension is not affiliated with or endorsed by DHL.