VibeFox DHL Packstation for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x. The Classic and Hummingbird themes are supported.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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

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 Packstation 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. Paste the DHL API key, click Save, then click Test API key. Choose the location types and enter the country prices (see Configuration).

On install the module creates the DHL Packstation carrier with the delivery time text Delivery to a DHL Packstation or post office. The carrier is enabled, assigned to all customer groups and to the zones of Germany and Austria (the countries of the default price list). 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 Packstation > Configure. Each section has its own Save button, which saves the whole page. If a field has an error (a number that is not valid or negative, Min weight (kg) greater than Max weight (kg), a name longer than 64 characters), nothing is saved and the error is shown at the top. Every save clears the location cache.

Warnings above the settings tell you when the carrier was not found, when the shop weight unit (International > Localization, Local units) is not known to the module (weights are then read as kg; use kg, g, lb or oz), when the DHL API key is empty, when no location type is enabled and when country price entries are not in the CC:PRICE format (these entries are ignored).

General

Customer groups, zones and size limits of the carrier are set in Shipping > Carriers. The settings below apply to every zone.

Enable/Disable: 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. Default: DHL Packstation. Required, at most 64 characters.

Tax: the tax rule of the carrier, or No tax. PrestaShop adds this tax on top of the prices below. With No tax the prices are final.

DHL Location Finder API

DHL API key: the "API Key" of your app on developer.dhl.com. Without it the carrier 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: 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, 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 delivery 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 carrier 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 delivery 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 new address is used only by the order and does not appear in the customer's address book.

Prices (the section title shows your shop default currency)

Country prices: the price per destination country in the shop 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 carrier for such countries.

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

Free shipping from: the cart subtotal (products that need shipping, after discounts, 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 your shop weight unit. 0 means no limit.

Max weight (kg): the carrier 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 carrier only if the cart subtotal (products that need shipping, after discounts, before tax) is at least this value. Leave empty to always show it.

Ignore shipping zones: when on, the carrier is linked to every active zone (also zones created later) and is offered for the countries below, or for all countries if the list is empty. When you switch it off again, the carrier gets back the zones it had before.

Countries (ignore zones): the destination countries for that mode. Ctrl/Cmd + click to select several countries. Used only with Ignore shipping zones.

Advanced

Debug log: writes API requests and checkout steps to logs/vfd_dhlp_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this is off. The API key, the Postnummer and customer addresses are never written.

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, cached searches and logs. The chosen locations stay in the orders. When off, everything is kept for a re-install.

How it works at checkout

At the delivery step PrestaShop asks the module for the DHL Packstation price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module 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 price is calculated in your default currency and shown in the customer's cart currency.

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 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 module 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, a picker appears under the carrier. The DHL locations near the delivery postcode and city are loaded. DHL is asked only for the selected carrier. 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 to the cart 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 or invalid Postnummer is reported the same way.

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

When the order is placed, the location (ID, type, number, name, address) and the Postnummer are saved with the order. If Shipping address is on, the order's delivery address is replaced by the address of the location. The location is shown on the order confirmation page, in Order history and details of the customer account, and in the order confirmation e-mail and the new order e-mail of the Mail alerts module, added to the carrier name as DHL pickup location and DHL Postnummer.

On the admin order page the DHL pickup location block shows the location, its type and ID, and the Postnummer. Click Change, search by postcode or city, choose another location, change the Postnummer and click Save location. You can also change only the Postnummer. Each change adds a private order message DHL pickup location changed to: …. If Shipping address is on, the delivery address of the order is updated too. Changing the location needs permission to edit orders; access to the Modules pages is not needed. If several orders were created from one cart, the location belongs to the first order only; Change on another order of that cart shows The DHL location of this cart belongs to another order of the same cart - nothing was changed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DHL Packstation is the first block on Modules > Module Manager > VibeFox DHL Packstation > 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-packstation 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 Packstation 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 the module always removes the license key and license status. Reset of this module does not delete data, so the key and the status are kept.

Troubleshooting

DHL Packstation does not appear at checkout: check that the license is active and Enable/Disable 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 (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. Products can also be limited to certain carriers in the product page.

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 module 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 page says the DHL Packstation carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps the on/off status of an existing carrier.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox DHL Packstation and choose Uninstall. The license key, the license status and the location cache are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and the locations of carts without an order are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again restores the carrier status it had before. The chosen locations always stay in the orders.

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