VibeFox GLS ParcelShop 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), with the default theme and its one-page checkout.

PHP: 8.0 or later.

GLS: no GLS account or API key is used or needed by the extension. The ParcelShop map is public. You need a GLS contract to ship the parcels to the chosen ParcelShops.

Content security policy: if your store sends a content security policy, allow map.gls-croatia.com, where the GLS map script is loaded from.

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_gls_parcelshop-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_gls_parcelshop.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_gls_parcelshop-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 GLS ParcelShop 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. Set your prices: at least one Country prices row (for example * Default) or a Fallback cost (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_gls_parcelshop.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 GLS ParcelShop, 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 GLS ParcelShop > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Only admin users with the modify permission for this extension can save the settings.

Warnings at the top of the page, and again after each save, point out configuration problems: no price is set, some or all of the selected Countries (ignore zones mode) are not covered by the GLS map, or the store weight unit is not known to the extension and there is no weight class with the unit kg (add one in System > Localisation > Weight Classes). An invalid or negative number is refused with a message that names the field, for example Fallback cost: "abc" is not a valid number of 0 or more - the previous value was kept. The other fields are still saved. An invalid Name, sort order, tax class or geo zone is refused the same way.

General

The section lists the countries covered by the GLS map: Austria, Belgium, Bulgaria, Croatia, the Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Italy, Luxembourg, the Netherlands, Poland, Portugal, Romania, Serbia, Slovakia, Slovenia and Spain. The method is not offered for other destination countries.

Enable/Disable: shows or hides GLS ParcelShop at checkout. Default: off.

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

Tax status: None (shipping is not taxed), or the tax class to apply when shipping is taxable.

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

Prices

Prices are entered in your store default currency, tax excluded. Decimals may use a comma or a point (4,99 or 4.99). The price is shown to the customer in their currency.

Calculation type: how the price is applied.

Country prices: a table with one row per destination country. Click Add country to add a row. Each row has a Country, a Price and five weight columns: XS up to 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg and XL over 5 kg. The column for the cart weight is used. A weight column left at 0 uses the Price column. The * Default row is used for countries without their own row. A row where all prices are 0 gives free delivery, so choose the country and fill in the prices before you save. If a value in the table is not a valid number of 0 or more, the whole table is not saved and the message lists the wrong values.

Fallback cost: the price used when the table has no row for the destination country and no * Default row. Leave it empty to hide the method for such countries.

Free shipping from: the cart subtotal (after discounts, without tax) from which GLS ParcelShop delivery is free. Leave it empty if delivery is never free.

Availability

Minimum weight (kg): hide the method when the cart weighs less. The weight is converted from the product weight classes. Empty or 0 means no limit.

Maximum weight (kg): hide the method when the cart weighs more. Default: 20. GLS ParcelShops usually accept parcels up to 20 kg, so check your GLS contract. Empty or 0 means no limit. If the minimum is greater than the maximum, both weights are refused with a message and the previous values are kept.

Minimum cart subtotal: offer the method only when the cart subtotal (after discounts, without tax) reaches this amount. Leave it empty for no minimum.

Geo zone: offer the method only for addresses in this geo zone. All zones means no limit. Not used when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: when on, the method is offered for the countries selected below (all GLS map countries when the list is empty), whatever the geo zone. When off, it is offered only in the geo zone above. Default: off.

Countries (ignore zones mode): the destination countries for that mode. Leave it empty to use all GLS map countries. Countries not covered by the GLS map are skipped. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations and ParcelShop choices to storage/logs/vfd_glps_debug.log.php (on OpenCart 4 system/storage/logs/vfd_glps_debug.log.php). The file cannot be read from the web. Errors are always logged. No customer personal data is logged. Turn the log off when you are done. When the file reaches 5 MB, it is moved to vfd_glps_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 and the log. When off, everything is kept for a re-install. The ParcelShop saved in orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. Invalid values are reported and not imported.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the GLS ParcelShop 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 cart subtotal. The subtotal is the price of these products after the coupon discount, without tax. The extension then checks the conditions: delivery country covered by the GLS map (and selected in Countries (ignore zones mode) when that mode is on), cart weight and minimum cart subtotal. If the cart subtotal reaches Free shipping from, the delivery is free. Otherwise the price is taken from the row of the country (or the * Default row) and the weight column, or from Fallback cost. If no price is found, the method is hidden. The price is rounded to the decimals of your default currency and shown with the tax of the selected Tax status.

When the customer selects GLS ParcelShop, a GLS ParcelShop box with a Select GLS ParcelShop button appears under the method. It opens the official GLS ParcelShop map for the delivery country. A ParcelShop in another country is refused at once. After a ParcelShop is chosen, its name and address are shown and the button changes to Change ParcelShop. The choice is kept in the customer's session, so it stays when the shipping step is reloaded. If the delivery address changes to another country, the customer has to choose a ParcelShop again.

When the customer clicks Continue in the delivery method step, the extension checks that a ParcelShop was chosen and that it is in the delivery country. Otherwise the customer sees Please select a GLS ParcelShop. or The selected GLS ParcelShop is not in your shipping country. Please choose a ParcelShop again. and stays in that step. If the ParcelShop cannot be saved, the customer sees The ParcelShop could not be saved. Please try again. If the GLS map script cannot be loaded, the customer sees The GLS ParcelShop map could not be loaded. Please reload the page or choose another shipping method.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks GLS ParcelShop in the window Shipping method options. The GLS ParcelShop box with the Select GLS ParcelShop button appears in that window under the method, and the GLS map opens over the window. The Continue button of the window does not go on without a valid ParcelShop, with the same messages. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the ParcelShop of the order is updated with it.

The GLS map runs in the customer's browser. On the checkout page the extension loads the GLS map script from map.gls-croatia.com, and the map loads ParcelShop data and map tiles from GLS. GLS receives the usual request data of the visitor (IP address, browser). Nothing is sent from your server to GLS. An error in the extension never breaks the checkout of other shipping methods; it is written to the log.

The extension does not get live GLS rates, create GLS shipments, print labels or track parcels. It has no list of ParcelShops on your server, so it cannot verify the ParcelShop ID against GLS. Hand the ParcelShop ID from the order to GLS in your usual way (MyGLS, your GLS software or another extension).

Pickup points

When the order is placed, the ParcelShop chosen at checkout is saved with the order: its ID, its name with the address and its country. After the order is completed, the choice is cleared, so the next cart starts without a ParcelShop.

Shipping method name: the ParcelShop is added to the shipping method name of the order, for example GLS ParcelShop: name, address (the method name, then the ParcelShop) (OpenCart 3 keeps at most 128 characters of it, OpenCart 4 at most 255). So the ParcelShop appears in the order confirmation e-mail to the customer, on the order page in the customer's Order History and in Sales > Orders. OpenCart does not show the shipping method on the order success page.

Admin order page: in Sales > Orders, a GLS ParcelShop panel shows the ParcelShop name and address with the ParcelShop ID and country. If a GLS ParcelShop order has no ParcelShop, the panel shows No ParcelShop was selected for this order. The panel only shows the ParcelShop; it cannot be changed there.

Merchant e-mail: the new order alert e-mail to the store includes the ParcelShop with its ParcelShop ID in the comment block.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox GLS ParcelShop is the first block on Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > 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-gls-parcelshop 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, GLS ParcelShop 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

GLS ParcelShop 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 (ignore zones mode). Check that the destination country is one of the GLS map countries and has a price (a country row, the * Default row or Fallback cost). Check the weight limits and Minimum cart subtotal, and that the products have Requires Shipping set to Yes. Turn on Debug log and look at the Log field to see the reason.

The map does not open: the customer sees "The GLS ParcelShop map could not be loaded..." when the GLS script is blocked, for example by an ad or privacy blocker, a content security policy or a GLS outage. Allow map.gls-croatia.com in your content security policy.

The ParcelShop box does not appear under the method: the extension was tested with the default OpenCart theme and its checkout. A theme or a checkout extension that replaces the shipping method step may not show the box.

Delivery is free for a country by mistake: check the row of that country in Country prices. A row where the Price and all weight columns are 0 gives free delivery.

The table or a field was not saved: a value is not a valid number of 0 or more. The message at the top of the page names the value. Use digits with a comma or a point as the decimal separator.

An order shows No ParcelShop was selected for this order: the order was placed without a ParcelShop of the delivery country. The reason is written to the log. Ask the customer for the ParcelShop and hand it to GLS by hand.

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

For developers: the address of the GLS map script can be replaced with the setting vfd_glps_widget_url; it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox GLS ParcelShop. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax status and Geo zone. The extension always removes its events. If Remove data on uninstall is on, the other settings and the debug log are deleted as well. If it is off, they are kept and are used again when you install the extension again. A ParcelShop chosen in an open cart stays in the customer's session until it expires. The ParcelShop saved in orders is always kept, 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 GLS ParcelShop in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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