VibeFox DPD Pickup 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.

DPD Baltic credentials (Lithuania, Latvia, Estonia): the pickup point list comes from the DPD Baltic web service. You need the API username and password that DPD gives to its business customers. Ask your DPD account manager or the DPD customer service of your country. One account lists the pickup points of Lithuania, Latvia and Estonia.

DPD Slovakia: the public DPD Slovakia parcelshop search needs no credentials.

Weight class: product weights are converted to kg. Your store needs a weight class with the unit kg in System > Localisation > Weight Classes (OpenCart has one by default).

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_dpd_pickup-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_dpd_pickup.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_dpd_pickup-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 DPD Pickup 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 your DPD API. For DPD Lithuania, Latvia or Estonia enter the API username and password. Check the prices per country, turn on Enable/Disable and click Save. Then click Refresh pickup points to check the connection (see Configuration).

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_dpd_pickup.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 DPD Pickup, 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. 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 DPD Pickup > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached pickup point lists. Only admin users with the modify permission for this extension can save the settings, refresh the pickup points or clear the log.

Warnings at the top of the page tell you when the DPD Baltic username or password is empty, or when no prices are set (both mean the method is not shown at checkout), and when the store has no weight class with the unit kg (product weights are then read by their unit name, unknown units as kg). Some values stop the save, and nothing is saved: an empty Name or one longer than 64 characters, a Sort order that is not a whole number, and a Min weight (kg) greater than the Max weight (kg). A value that is not a number, or a negative number, in an amount or weight field is not saved: the field becomes empty and a warning names it, while the other settings are saved. Lines of Country prices that are not in CC:PRICE format are listed in a warning and ignored.

General

The method is offered in the geo zone set in Availability (all zones if none), or with Ignore shipping zones in the countries chosen there.

Enable/Disable: shows or hides DPD Pickup at checkout. Default: off.

Name: the shipping method name shown to the customer at checkout. Default: DPD Pickup Point. Required, at most 64 characters.

Tax class: the tax class applied to the shipping price, or None (default) for no tax.

Sort order: the position of the method in the list of shipping methods. A whole number.

DPD pickup point list

Pickup points are loaded from DPD and cached (see How it works at checkout).

DPD API: the DPD company your account is with. Baltic accounts use the web service of their own country.

API username (Baltic): your DPD Baltic web service username. Not needed for DPD Slovakia. Clearing it also clears the saved password.

API password (Baltic): your DPD Baltic web service password. Not needed for DPD Slovakia. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it.

Pickup points: the Refresh pickup points button clears the cache and loads the pickup points from DPD now: Lithuania, Latvia and Estonia for the Baltic API, a test search in Bratislava for DPD Slovakia. It shows the number of pickup points or the error per country. Save the settings first.

Prices

Shipping prices are fixed per country, in your store default currency, tax excluded. DPD prices are not requested from the API.

Country prices: one line per country: CC:price, for example EE:3.50. A decimal comma is accepted. Default: SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost: the price for countries that are not in Country prices. Default: 5.00. Leave it empty to offer the method only in the listed countries.

Calculation type: 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: shipping is free when the order subtotal (after discounts, before tax) reaches this amount. Leave it empty to turn it off.

Availability

The method is also hidden when DPD returns no pickup points for the customer's address or the DPD API cannot be reached, because an order cannot be delivered without a pickup point.

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

Max weight (kg): heavier carts do not see the method. Default: 31.5. Empty or 0 means no limit. Check the parcel limits of DPD Pickup points and lockers in your country.

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

Geo zone: offer the method only for addresses 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 geo zone is not checked and the method is offered for the countries below. When off (default), only the geo zone above is used.

Countries: the destination countries for that mode. Leave it empty for all countries. Only used with Ignore shipping zones.

Pickup point selector

City order: show major cities first (Tallinn, Riga, Vilnius, Bratislava and others). On by default.

City list width: the CSS width of the city list, for example 100% or 300px. Default: 100%.

Pickup point list width: the CSS width of the pickup point list, for example 100% or 400px. Default: 100%.

Advanced

Debug log: writes API requests and checkout steps to storage/logs/vfd_dpd_debug.log.php (on OpenCart 4 system/storage/logs/vfd_dpd_debug.log.php). The file cannot be read from the web. API errors are always logged, even when this is off. Credentials are never logged. When the file reaches 5 MB, it is moved to vfd_dpd_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 extension settings, the log and the choices of unfinished checkouts. The pickup point saved in orders is always kept.

Import / Export

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

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the DPD Pickup 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 the countries (with Ignore shipping zones), the cart weight and the minimum subtotal, takes the price for the country (or the fallback cost) 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.

Then it loads the DPD pickup points for the address. If DPD returns none, cannot be reached or the Baltic credentials are missing, the method is hidden. With DPD Slovakia the method is shown while the city or postcode is still missing, and the points appear once the address is complete. The price is calculated in your default currency and shown to the customer in their currency with the tax of the selected Tax class.

A pickup point list is cached for up to 24 hours, an empty list for up to 1 hour, but not longer than the OpenCart cache lifetime (1 hour by default). A failed request is remembered for 5 minutes, so a DPD outage never slows down the checkout. The API timeout is 15 seconds.

The extension does not request DPD prices, create DPD shipments, print labels, create manifests, order courier pickups, track parcels or show a map. Only the DPD Baltic web service and the DPD Slovakia parcelshop search are supported.

Pickup points

When the customer selects DPD Pickup, a city list and a pickup point list appear under the method. The city of the customer's address is pre-selected. The choice is saved as soon as the customer selects it. With DPD Slovakia, the customer sees Enter your city and postcode to see the DPD pickup points nearby. until the address is complete, then the points nearby. If DPD has no points for the address, the customer sees No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.

A pickup point is required. Without one the customer cannot continue and sees Please select a DPD pickup point. When the customer clicks Continue, the server checks that the point belongs to the DPD list for the customer's address. A forged or outdated choice is refused with The selected DPD pickup point is not available for this address. Please choose another one. If the DPD list cannot be loaded at that moment, the point the customer already chose is accepted, and the order shows its ID instead of the name.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks DPD Pickup in the window Shipping method options. The city list and the pickup point list appear in that window under the method and work as described above. The Continue button of the window does not go on without a pickup point, with the same messages.

The chosen point is added to the shipping method of the order, for example DPD Pickup Point: name, street, postcode city with the default title, or My title - DPD pickup point: name, street, postcode city with your own title (at most 128 characters). So it appears in the admin order, the customer's order history, the order e-mails and the invoice. The name saved in the order comes from DPD, not from the browser.

On OpenCart 4 the text of the shipping method can have up to 255 characters. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the pickup point of the order is updated with it.

On the admin order page (Sales > Orders), the DPD pickup point panel above the history shows the point name, its ID and country. Click Edit, choose a city and another point and click Save. The point is checked against the DPD list for the order address, and the panel shows Pickup point updated. or Pickup point not found for the order address. The shipping method text of the order is updated, and a note is added to the order history (not sent to the customer) with the old point, the new point and the admin user. Changing the point needs the modify permission for orders, not access to the extension settings. With DPD Slovakia the order needs a shipping city and postcode, otherwise the panel shows Add the shipping city and postcode to change the pickup point. An order placed without a point shows No pickup point was selected for this order., and the debug log has an error for it. The panel and Edit also work after the extension is switched off.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox DPD Pickup is the first block on Extensions > Extensions > Shipping > VibeFox DPD Pickup > 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-dpd-pickup 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 DPD Pickup 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

DPD Pickup does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo zone (or Ignore shipping zones and Countries), the weight and subtotal limits and that the country has a price (or a fallback cost). Check the warnings at the top of the extension page and click Refresh pickup points. Check that the products have Requires Shipping set to Yes.

An error after Refresh pickup points: the result shows the DPD error per country. For example, "Login failed" means DPD rejected the Baltic credentials, so no pickup point can be loaded. Check the API username and password with DPD.

DPD Slovakia shows no points: the points appear once the customer has entered the city and postcode. DPD lists only the points within 50 km of that address.

Finding the reason: turn on Debug log, reload the checkout and look at the Log field on the extension page. API errors are always logged. API usernames and passwords are never written to the log.

Pickup points look outdated after a change: click Save or Refresh pickup points on the extension page. Both clear the cached lists.

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

For developers: the DPD Slovakia search radius can be changed by another extension with the OpenCart event vfd_dpd_pickup/sk_search_radius.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox DPD Pickup. 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 extension always removes its events and the cached pickup point lists. If Remove data on uninstall is on, the other settings, the debug log and the choices of unfinished checkouts are deleted as well. If it is off, the settings are kept and are used again when you install the extension again. The pickup point stored in orders is never deleted, and 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 DPD Pickup in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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