dffreegift — Cart-threshold free gift — Complete guide

Complete guide for the dffreegift module for PrestaShop 8 and 9: installation, configuration, internal mechanics (native CartRule), customization, troubleshooting and uninstall. Every step is accompanied by conceptual walkthroughs and the exact parameters to use in production.

Overview

dffreegift automatically adds a gift product to the cart as soon as a configured threshold is reached, and removes it if the cart drops back below. The mechanic relies entirely on PrestaShop’s native CartRule system (gift_product field): the module never manipulates product prices directly, does not create temporary SpecificPrice rows, and injects nothing into pricing hooks. Consequence: full compatibility with your other promotions, voucher codes, taxes and multi-currency setups.

The module also displays a progress block on the cart page with an “Add €X to receive your gift” message, a colored bar that fills as the threshold approaches, and a crossing animation.

Requirements

• PrestaShop 8.0 to 9.x (tested on 8.0, 8.1, 8.2, 9.0)
• PHP 8.1 minimum (8.2 and 8.3 supported)
• An active product in your catalog to use as the gift (simple product or with combinations)
• Administrator access to the PrestaShop back office

Installation

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

On install, the module performs the following operations in the background:

• Registers 5 hooks: actionCartSave, actionObjectCartRuleDeleteBefore, displayShoppingCart, displayCartExtraProductActions, displayHeader.
• Writes default configuration values (threshold €50, tax-inclusive calculation, no shipping, stock check enabled).
• Creates a “ghost” CartRule with a unique code like DFFREEGIFT_A7B3F2D9, visible in Catalog → Discounts → Cart rules.

Configuration

The configuration screen is at Modules → DataFirefly Free Gift → Configure. All parameters live in a single form.

Enable the module

The Enable the module switch acts as a master toggle. Set to No, the module stays installed but does nothing: no auto-add, no frontend block, no threshold calculation. Handy for temporarily disabling the offer (end of a seasonal campaign for example) without losing the configuration.

Gift product and combination

Two fields, filled in order:

1. Gift product ID: enter the PrestaShop ID of the product to give away. The ID is visible in Catalog → Products (ID column). After the first save, the product name is shown as a hint below the field for confirmation.
2. Combination: dropdown listing the available combinations for the product. Auto-populated after you save the product ID. Pick a specific combination (e.g. “Size M, color black”) or leave it on — Without combination — for a simple product.

Trigger threshold

The Trigger threshold field sets the cart amount above which the gift is added. Two associated parameters define the calculation base:

• Tax-inclusive calculation: if enabled, the total includes all taxes applied to the cart. If disabled, the threshold is compared to the tax-exclusive total. Most B2C stores work tax-inclusive; B2B stores often think tax-exclusive.
• Include shipping costs: if enabled, estimated shipping is added to the total before comparison. In practice, rarely enabled since shipping isn’t always calculated at the time the customer looks at their cart (no carrier selected yet = €0).

Under the hood, the evaluated total is a native PrestaShop call:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

This guarantees the value used for comparison is strictly identical to the one displayed in PrestaShop’s cart summary.

Stock check

The Check gift stock switch (enabled by default) suspends auto-add if the gift product is unavailable. The check respects the out-of-stock strategy configured globally in PrestaShop:

• If the product is marked “allow orders when out of stock”, auto-add stays active even at quantity 0.
• If the product refuses orders when out of stock, auto-add is suspended when the quantity hits 0.

Customer group restriction

The Eligible customer groups grid lists every group in the shop with a checkbox per group. Two behaviors:

• No checkbox ticked: all customers are eligible, including unidentified visitors (provided the default group PS_UNIDENTIFIED_GROUP is not excluded, which is the default behavior).
• One or more checkboxes ticked: only customers who are members of at least one ticked group see the progress block and benefit from auto-add.

Typical use cases:

• Gift reserved for the “Professionals” group for a B2B audience.
• Gift reserved for the “VIP” group for a loyalty program.
• Gift offered to everyone except resellers (tick all groups except the reseller group).

Display options

Two independent switches control the frontend block appearance:

• Show progress message: enables or fully disables the block on the cart page. Set to No, auto-add still works but no message appears on the customer side (useful if you want to drive the display from your own theme).
• Show progress bar: enables or disables the colored bar below the message. The text message remains visible.

How it works technically

The ghost CartRule

Instead of manipulating product prices, dffreegift uses PrestaShop’s native gift mechanism via CartRule. At install time, a rule with the following properties is created:

• code = DFFREEGIFT_A7B3F2D9 (suffix randomly generated at install)
• gift_product = 0 (updated on each configuration save)
• gift_product_attribute = 0 (updated on each configuration save)
• quantity = 999,999 and quantity_per_user = 999,999 (practically unlimited)
• date_from = now, date_to = +50 years
• active = 1, no code, no discount, no product or category restriction

When the threshold is reached, the module attaches this rule to the cart via Cart::addCartRule($id). PrestaShop takes care of the rest:

• Inserts a cart line with gift = 1 and price = 0.
• Displays it in the cart summary with a “Gift” badge.
• Includes it at order conversion time.
• Snapshots it in the order history (the gift remains visible even if you change the gift product later).

When the cart drops below the threshold, the module detaches the rule via Cart::removeCartRule($id). The gift line is removed in the same request.

Hooks used

• actionCartSave: main hook. Called on every cart save (add, modify, remove, customer login with cart merge). The module computes the total and decides to attach or detach the rule. A static self::$syncing flag prevents recursion if attaching the rule triggers another save in turn.
• actionObjectCartRuleDeleteBefore: self-healing. If an admin manually deletes the ghost rule from Catalog → Discounts, this hook detects the deletion and resets the ID in configuration. The next sync will recreate a clean rule.
• displayHeader: registers the frontend CSS and JS (views/css/dffreegift.css and views/js/dffreegift.js).
• displayShoppingCart: renders the progress block on the cart page.
• displayCartExtraProductActions: reserved for future enhancements (badge on the gift line).

Threshold calculation

On every call to syncCartGift(), the module checks in order:

1. Is the module enabled? (otherwise exit)
2. Is the customer eligible per configured groups? (otherwise detach if attached)
3. Is the gift product valid (exists, active, in stock if check enabled)? (otherwise detach)
4. Total calculation based on tax-incl./excl. and shipping inclusion.
5. Comparison to the threshold with a rounding tolerance of €0.001.
6. Attach the rule if threshold reached and not yet attached. Detach if below the threshold and currently attached.

Frontend progress block

The block is shown automatically on the cart page, between the products summary and the total. Two visual states:

• Pending (threshold not reached): light gray background, “Add €X.XX to receive your gift” message, orange bar that fills as the threshold approaches.
• Goal reached (threshold crossed): light green background, “Your gift was added to the cart!” message, bar fully filled in green. A pulse animation triggers on the transition from pending to reached.

Customize the colors

Colors are defined in views/css/dffreegift.css. To customize without modifying the module (which would overwrite your changes on updates), override the classes in your theme’s CSS:

.dffreegift-progress {
    border-color: #your-color;
    background: #your-bg;
}
.dffreegift-progress--reached {
    background: #your-light-green;
    border-color: #your-green;
}
.dffreegift-progress__bar-fill {
    background: linear-gradient(90deg, #color1, #color2);
}

Customize the texts

Client-facing texts are translatable via the standard PrestaShop mechanism. Go to International → Translations, select “Module translations”, choose dffreegift and the language, then look for the Modules.Dffreegift.Shop domain. Available strings:

• “Add %amount% to receive your gift” — pending message (%amount% is automatically replaced by the remaining amount formatted per currency and locale).
• “Your gift was added to the cart!” — goal-reached message.
• “Progress toward the gift” — ARIA label of the bar (read by screen readers).

Coexistence with other promotions

Since the gift is added through a native CartRule, it coexists normally with any other CartRule. Expected behaviors:

• Other customer voucher codes (percentage discount, fixed amount, free shipping): apply normally alongside the gift. The gift does not consume the discount, and vice versa.
• Another rule with gift_product configured elsewhere: PrestaShop treats them as independent rules and adds both gifts. Watch out if you stack multiple gift modules.
• Rule with product_restriction excluding the gift product: the restricting rule wins. The gift is not added if another active rule explicitly excludes it.
• Rule with cart_rule_restriction: if another rule forbids the use of ours by cross-restriction, auto-add is blocked (native PrestaShop behavior).

Multi-shop

The module works with PrestaShop’s multi-shop setup on the default shop context. Configurations (threshold, gift product, options) are stored via Configuration::updateValue, which respects the current shop context. The CartRule created at install is attached to the active shop at install time.

For a multi-shop deployment with different gifts per shop, you currently need to install and configure the module in each shop context separately. Contact support for a variant with explicit per-id_shop scoping.

Troubleshooting

The gift doesn’t get added to the cart

Check in order:

1. Is the module properly enabled? (Modules → Configure → Enable the module switch).
2. Is the gift product valid? (correct ID, active product, in stock if stock check enabled).
3. Is the customer in an allowed group? (if you restrict by groups, an unidentified visitor not in any allowed group will see nothing).
4. Is the threshold actually reached? Manually recompute the total according to your parameters (tax incl./excl., with/without shipping).
5. Does the ghost CartRule exist and is it active? Go to Catalog → Discounts → Cart rules and search for DFFREEGIFT_.

The progress block doesn’t appear on the cart page

Common causes:

• The Show progress message switch is set to No.
• The customer is not eligible per configured customer groups.
• The gift product is invalid (does not exist, inactive, or out of stock with stock check enabled).
• Your custom theme does not call the displayShoppingCart hook. Verify with the command grep -r "displayShoppingCart" themes/your-theme/ or in Modules → Positions.

The CartRule has disappeared from the back office

If someone deleted the rule from Catalog → Discounts, the actionObjectCartRuleDeleteBefore hook detected the deletion and reset the configuration. At the next cart sync (so at the next product add by a customer), a new rule is created automatically with a new DFFREEGIFT_xxxxxxxx code.

To force regeneration immediately without waiting for a customer:

1. Go to Modules → DataFirefly Free Gift → Disable.
2. Then Enable again. This recreates a clean rule.

Errors in PrestaShop logs

The module logs exceptions in Advanced Parameters → Logs with the [dffreegift] prefix. A typical message in case of an issue:

[dffreegift] actionCartSave error: <error description>

These errors never interrupt the cart flow — they are purely informative. In case of recurring logs, forward the full message to support.

The threshold seems miscalculated

The calculation depends strictly on your Tax-inclusive calculation and Include shipping costs parameters. To verify what PrestaShop returns:

• Tax incl. + no shipping: matches the Products subtotal (tax incl.) shown in the cart summary.
• Tax incl. + with shipping: matches the Total (tax incl.) (products + shipping if a carrier is selected).
• Tax excl. + no shipping: matches the Products subtotal (tax excl.).
• Tax excl. + with shipping: matches the Total (tax excl.) (products + shipping tax excl.).

If you spot a discrepancy, compare with the exact line in the cart summary — most of the time the gap comes from shipping that hasn’t been computed yet (the customer hasn’t picked a carrier, so shipping is €0).

Uninstall

Go to Modules → Module Manager → DataFirefly Free Gift → Uninstall. Uninstalling removes:

• The ghost CartRule and all its cart associations (carts in progress will lose their gift automatically).
• All configuration keys with the DFFREEGIFT_ prefix.

Quick FAQ

• Does the gift show up in the header mini-cart? No, only on the cart page (displayShoppingCart hook). The mini-cart is handled differently by each theme and a theme-by-theme integration would be needed. On request from support.
• Can I offer multiple gifts with multiple thresholds (e.g. gift A at €50, gift B at €100)? No, version 1.0.0 handles one gift with one threshold. For multiple tiers, contact support.
• Is the gift included in refunds? Like any native PrestaShop gift product, the gift appears in the order at price 0. In case of partial refund, the gift stays in the order with no financial impact.
• Can I modify the dffreegift.php file directly? Technically yes (source code is not obfuscated), but official updates will overwrite your changes. Create an override module for any deep customization.

Support and updates

The module includes 12 months of updates and support from the purchase date. Support by email in French or English, response within 24 business hours.

For any question or issue, contact DataFirefly support mentioning:

• PrestaShop version (visible in Advanced Parameters → Information)
• PHP version
• Installed dffreegift version
• Description of observed behavior vs. expected behavior
• Excerpt of PrestaShop logs if applicable ([dffreegift])