# 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,…
- Page:
- Language: en
- Last updated: 2026-09-28
- Other languages: [fr](https://www.datafirefly.com/documentation/dffreeshipbar/index.md), [es](https://www.datafirefly.com/es/documentation/dffreeshipbar/index.md), [de](https://www.datafirefly.com/de/documentation/dffreeshipbar/index.md), [it](https://www.datafirefly.com/it/documentation/dffreeshipbar/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreeshipbar/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreeshipbar/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreeshipbar/index.md)
- Index:
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`.
**Note.** The global fallback threshold is off by default. Until a territory has a threshold, the bar appears nowhere, and the summary strip of the back office says so. No bar is better than a bar promising free shipping you do not offer.
## 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.
**Upgrading from an earlier version.** This position starts disabled on an existing shop, so the upgrade does not change what your customers see. Enable it in the General tab.
## 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.
**Careful.** To exclude a territory, clear the checkbox. Emptying the amount does the opposite: the territory inherits its country's threshold.
### 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](https://www.datafirefly.com/contact/) with your PrestaShop, PHP and module versions, the theme in use, and the territory and carrier involved.