Free Shipping Bar (dffreeshipbar): complete guide

Complete guide to the dffreeshipbar 2.3.0 module for PrestaShop 8 and 9: installation, per-country and per-state thresholds, display positions (including the product page and the Creative Elements cart drawer), messages, appearance, carriers, multi-currency and troubleshooting.

Overview

dffreeshipbar displays a progress bar telling customers how much more they need to spend to qualify for free shipping. Once the threshold is reached, the message switches to a confirmation.

The module works from its own thresholds, stored in its own tables. It never reads the native PS_SHIPPING_FREE_PRICE setting: you can leave it at 0 and drive free shipping through carrier ranges without any conflict.

What sets it apart is its two-level territorial resolution: a threshold can be set per country and per PrestaShop state. Territories attached to the same country, such as the overseas departments attached to France, can therefore be handled differently.

Requirements

• PrestaShop 8.0 to 9.x
• PHP 7.4 minimum (8.0 to 8.3 supported)
• Classic, Hummingbird or a custom theme calling the standard hooks
• Creative Elements (optional) for the cart drawer position

Installation

1. In the back office, go to Modules → Module Manager → Upload a module.
2. Upload the dffreeshipbar-2.3.0.zip file.
3. Click Install then Configure.

The module creates two tables (PREFIX_dffreeshipbar_country and PREFIX_dffreeshipbar_state, each with an id_shop column) and registers the hooks displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter and actionCarrierUpdate.

The configuration screen

The screen sits under Modules → DataFirefly – Free Shipping Bar → Configure. At the top, a summary strip shows the module status, the number of territories with a threshold and of excluded territories, the fallback, carrier filtering and active positions. Each tile opens the matching tab.

Configuration is split into five tabs: General, Territories, Carriers, Messages and Appearance. The active tab is kept after saving.

General tab

Global fallback threshold

• Use a global fallback threshold: on No, the bar only appears in configured territories. On Yes, every unconfigured territory receives the amount entered.
• Global fallback threshold: the amount applied as a last resort.

Multi-currency

Every amount in the module is entered in the default currency of the shop. For a visitor paying in another currency, the threshold is converted at the PrestaShop exchange rate before being compared with their cart, and displayed amounts are formatted in their currency.

Require a delivery address

Before an address is entered, the destination is only a guess and the state is unknown. Three modes:

• Never: the bar shows while browsing, based on the guessed country.
• For countries with states (recommended): the bar stays visible everywhere except in countries whose states may carry different terms, where it waits for the address.
• Always: nothing until an address exists on the cart.

Calculation basis

• Compare tax included totals: must match the basis of your carrier ranges, otherwise the bar and the checkout disagree.
• Count cart rules in the total: a 70 € cart with a 10 € voucher is then evaluated at 60 €.

Shipping costs never count towards progress.

Customer groups

With no box ticked, every customer sees the bar. Tick groups to reserve it for them, for instance retail customers when professionals have other shipping terms. A visitor who is not logged in belongs to the “Visitor” group.

Hide while the cart is empty

The bar appears with the first product added. The product page keeps it in every case, since that is where the customer decides to add.

Display positions

• Top of page: site-wide banner.
• Product page: see the dedicated section below.
• Cart and checkout: block on the cart page and in the checkout.
• Creative Elements cart drawer: see the dedicated section below.

For free placement, the module implements WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

The bar on the product page

The bar appears under the add to cart button (hook displayProductAdditionalInfo). On top of the current progress, a line tells the effect of adding the displayed product:

• if the product is enough to reach the threshold: “Add this product and your order ships free”;
• otherwise: “With this product, only 2.50 € left for free shipping”.

The calculation uses the price of the selected combination times the quantity entered, on the same tax basis as the cart, with the customer’s specific prices. It runs again when the customer picks another combination or quantity.

The Creative Elements cart drawer

On a shop whose header is built with Creative Elements, the bar fits into the side cart of the Shopping Cart widget in the Sidebar skin, through the displayCEShoppingCartFooter hook that the widget executes. The Classic skin does not open a drawer.

The Position in the cart drawer setting offers three spots: under the drawer title, above the cart summary or above the checkout buttons.

The bar updates via Ajax on every add to cart and every removal from the drawer, without a reload, and the gauge slides from its previous value. Creative Elements only rebuilds the product list and the summary, so the bar stays in place between updates.

Territories tab

The table lists every active country of the shop and, beneath each country that has states, its states, indented. A search field and a “configured territories only” filter help on large shops. Amounts are in the default currency.

Resolution order

For a delivery address, the module looks in this order and stops at the first match: the address state, then the country, then the global fallback if enabled. With no match, the bar is not displayed.

Checkbox and amount: two different effects

• Checkbox cleared: the bar is hidden for that territory, with no inheritance from the country or the fallback.
• Checkbox ticked, amount empty: the rule is deleted, the territory inherits from the level above.
• Checkbox ticked, amount filled: that amount applies.

Example: mainland only

• France: ticked, amount 65.
• Corsica: ticked, amount empty; it inherits the 65 €.
• Guadeloupe, Martinique, French Guiana, Réunion, Mayotte: cleared.
• Global fallback: disabled.

Carriers tab

Three modes: all carriers, display restricted to ticked carriers, or hidden for ticked carriers. Rules are stored against the carrier’s id_reference: PrestaShop recreates a carrier on every edit, but its reference stays stable.

The Before carrier selection setting decides whether the bar shows on catalogue and cart while no carrier has been chosen.

Messages tab

Five messages can be customised for each active language:

• Empty cart (default: “Free shipping from {threshold}.”)
• Cart in progress (default: “Only {amount} away from free shipping!”)
• Threshold reached
• Product page: this product unlocks free shipping
• Product page: amount left after adding this product

Two tokens are available: {amount} for the amount left and {threshold} for the threshold. They are replaced by the amount formatted in the visitor’s currency, in bold. The text is displayed as is: HTML typed in is not interpreted. An empty field keeps the translated text bundled with the module.

Appearance tab

• Colours: background, bar, text and success message, with a colour picker and a hexadecimal field kept in sync.
• Icon: truck, parcel, gift or none. Icons are SVG, and a check mark replaces the icon once the threshold is reached.
• Animation: moving stripes while progress runs, automatically off for visitors who asked their system to reduce motion.
• Closable banner: adds a close button to the top of page banner. Once closed, it stays hidden until the browser is closed. Other positions are not affected.

A live preview shows the banner, the product page and the reached threshold, and updates on every change before saving.

Real-time updates

Every position prints a container, even when the bar has nothing to show. After a cart, address, checkout step, combination or quantity event, a single request fetches the bar for every position on the page, and each container is filled or emptied in place. A bar hidden on load can therefore appear without a reload, and the reverse.

The script listens to the PrestaShop events updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm and updatedProduct. To trigger a refresh from your own code:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

Multistore and translations

Thresholds carry an id_shop: each shop has its own rules. Select the shop context at the top of the back office before opening the configuration.

The module ships translated into English, French, German, Spanish, Italian and Polish. For customer-facing texts, the Messages tab covers most needs.

Upgrading from an earlier version

Replacing the ZIP runs the migration scripts automatically. Your thresholds are kept. New options start disabled on an existing shop: product page, hiding on empty cart, closable banner, group restriction. Colours stored by earlier versions are normalised to #rrggbb, and the Smarty and opcache caches are cleared.

Troubleshooting

The bar shows nowhere

1. Does the summary strip say that no territory has a threshold?
2. Is the module enabled, and are the wanted positions enabled?
3. Is the address requirement set to Always while you test without an address?
4. Are customer groups ticked while your test account belongs to none of them?
5. Is “Hide while the cart is empty” on with an empty cart?

The bar shows where it should not

Check that the territory’s checkbox is actually cleared, and not merely that its amount was emptied.

Nothing in the Creative Elements drawer

• The Shopping Cart widget must use the Sidebar skin.
• “Show in the Creative Elements cart drawer” must be enabled.
• After upgrading from 2.1.0 or earlier, clear the cache under Advanced Parameters → Performance.

The amount does not match the checkout

• The tax setting must match the basis of your carrier ranges.
• A voucher can bring the cart back below the threshold.
• The module does not read your ranges: carry any range change over to the module.

The bar does not update after an add to cart

Refreshing relies on PrestaShop’s JavaScript events. If a third-party cart module does not emit them, dispatch dffreeshipbar:refresh from its code. Also check the console: a JavaScript error upstream prevents the listener from being installed.

Uninstalling

Uninstalling drops both threshold tables and every configuration key prefixed DFFREESHIPBAR_, messages included. Export both tables if you plan to reinstall.

Quick FAQ

• Does the module read PS_SHIPPING_FREE_PRICE? Never.
• Does the module read my carrier ranges? No, thresholds are entered manually. Automatic synchronisation is possible as custom development.
• My free shipping also depends on weight. Is that handled? No, the module only measures an amount.
• Can I use bold or a link in a message? No, the text is escaped. Token amounts are bolded automatically.
• Does a closed banner come back? The next time the browser is opened.

Support and updates

The module includes 12 months of updates and support. Email support in French or English, answered within 24 business hours. Contact DataFirefly support with your PrestaShop, PHP and module versions, the theme in use, and the territory and carrier involved.