Free Gift

Free gifts for Magento 2 stores on Hyvä: a gift per product — one free item for every item bought — and a gift above a cart value, with campaign dates, caps, announcements on both product pages and in the cart, and correct invoicing of every gift as a line with a 100% discount.

What it does

One free with every item bought. Set a gift on any product (simple, downloadable or virtual gift). Three bags in the cart → three gifts. The gift’s quantity follows the product’s — more, fewer, removed — on every cart change.
The copy already in the cart becomes the free one. A customer who put the gift product in the cart (paid) and then adds the product that gives it gets that copy free, with a note, instead of an extra one; anything above the free quantity stays paid. If the product later leaves the cart, their copy goes back to paid instead of disappearing. Can be turned off.
A gift above a cart value. One extra product for every order whose paid value reaches a threshold, with a progress bar in the mini-cart and on the cart page (“Spend €15.00 more and get X free”).
Campaigns that behave. Start and end dates (store time), a cap on the number of gifts (counted on placed orders, shown live on the product page as “Only 7 left”), a switch per product, and a store-wide switch. Gifts already in a customer’s cart are delivered even if the campaign ends in the meantime.
Announced where customers decide. A gift card under Add to Cart on the product page, and the reverse on the gift’s own page: “Get it free — free when you buy X”, with a link to X (never adds anything to the cart by itself).
In the cart, the gift sits under its product. In the cart page and in Hyvä’s mini-cart drawer, a product’s gift is a sub-line right under it — picture, quantity, its value struck through, “Free” — whatever order the lines were added in. No quantity field and no remove button on gifts.
Your theme’s look. Every card and badge is built on the theme’s CSS variables (--color-primary, --color-fg, --radius-*…): on any Hyvä theme it takes the theme’s colors and shapes, with an optional accent color. No Tailwind build needed.
Correct money. Gifts are invoiced at their value with a 100% line discount (stock leaves at value, the customer pays nothing). Coupons and cart price rules never touch gift lines, and none of their conditions count the gifts — subtotal, total quantity, “buy 3 of category X”, “if an item is found in the cart”; neither does the free shipping threshold.
Orders that say it. Admin order, invoice and credit memo, order e-mails and the customer account show “Gift: Free with X” on gift lines, and the gifts as their own totals row. Nothing of Magento’s templates is replaced.
Admin overview. A Free Gift column in the product grid with each gift’s real state (Active, Off, Expired, Not Started Yet, No Gift) and a filter on it.
Every text editable per store view; English and Romanian included.

Requirements


Magento Open Source / Adobe Commerce	2.4.8 (tested on 2.4.8-p5)
Hyvä Theme	1.3 or newer (tested on 1.5.3)
PHP	8.3 – 8.4 (as required by Magento 2.4.8)

The storefront uses Hyvä’s view models and CSP integration; Luma storefronts are not supported. hyva-themes/magento2-theme-module comes from Hyvä’s own Composer repository, which every Hyvä store already has configured.

Installation

Add the repository you received with your license to composer.json (once), then:

composer require slova/module-free-gift:^1.0
bin/magento module:enable Slova_FreeGift
bin/magento setup:upgrade
bin/magento setup:di:compile          # production mode
bin/magento cache:flush

Without Composer, unpack the zip into app/code/Slova/FreeGift (so that app/code/Slova/FreeGift/registration.php exists) and run the same bin/magento commands.

setup:upgrade creates two tables (slova_free_gift, slova_freegift_campaign_claim) and the has_gift product attribute. If the store already has a has_gift attribute, it is kept with its values.

Upgrading

composer update slova/module-free-gift
bin/magento setup:upgrade
bin/magento setup:di:compile          # production mode
bin/magento cache:flush

Read CHANGELOG.md first; settings and campaigns are kept across versions.

Uninstalling

Installed with Composer:

bin/magento module:uninstall Slova_FreeGift --remove-data

--remove-data drops the two tables, the has_gift attribute and the module’s settings (slova_freegift/*).

Installed from the zip (app/code):

bin/magento module:uninstall Slova_FreeGift --non-composer
rm -rf app/code/Slova/FreeGift
bin/magento setup:upgrade

Here Magento removes only the has_gift attribute. To also drop the gift data:

DROP TABLE slova_free_gift, slova_freegift_campaign_claim;
DELETE FROM core_config_data WHERE path LIKE 'slova_freegift/%';

Either way, uploaded gift artwork stays in pub/media/slova/freegift, and past orders keep their gift lines (a normal line with a 100% discount).

Setting up a gift per product

On the product’s edit page, section Free Gift:

Field
Gift Enabled	The campaign’s switch. Off: no gift is given or announced; the setup is kept.
Gift SKU	The product given for free. It may be hidden from the catalog. Empty: no gift.
Current Gift	Read-only: the gift and its real state — ACTIVE, OFF, NOT STARTED YET, EXPIRED.
Gift Artwork, Alt Text	For a gift with no price (a free download): shown on the product page instead of the gift’s name and price.
Maximum Gifts	Total gifts for this campaign, counted on placed orders. Empty: unlimited. Changing the gift SKU restarts the count.
Given So Far	Read-only counter.
Valid From / Valid To	Campaign dates, store time, inclusive. Empty: no start / no end.

The gift is given when the switch is on, today is within the dates, the cap is not reached and the gift is in stock — and the announcements follow exactly the same rule, so the store never promises a gift it would not add. Bundles give no gift: only the product bought on its own does.

Configuration

Stores → Configuration → Slova → Free Gift

General

Setting	Default
Enable Gifts per Product	Yes	Store-wide switch, without touching the campaigns. Gifts already in carts stay.
Paid Copies in the Cart Become Free	Yes	No: the gift is always an extra copy.
Gift Value	Regular price	The value gift lines are invoiced at (with a 100% discount): the regular price, or the current price after special prices and catalog rules.
Gifts Don’t Count Towards Free Shipping	Yes	The free shipping threshold compares only what the customer pays.
Show Gifts as a Separate Totals Row	Yes	On orders, invoices, credit memos and their e-mails.

Product Page

Setting	Default
Show Under Add to Cart	Yes	The gift card in the product info area (and the reverse card on the gift’s page).
Also Show as Product Section	No	The same card among the product sections (Description, More Information…).
Cart: Show Gifts Under Their Product	Yes	Turn off only for a theme that draws gift lines itself (see Themes).
Accent Color	empty	Empty: the theme’s primary color. Any CSS color.

Cart Threshold Gift — Enable, Cart Value Threshold (paid value: after special prices and catalog rules, before coupons), Gift SKU, Valid From / To, Campaign ID (anchors the counter; a new ID starts from zero), Maximum Gifts, Given So Far.

Texts — every text customers see, per store view. An empty field shows the default text in the store’s language. Placeholders: {count}, {product}, {amount}, {gift}.

Themes

The module adds to the theme; it does not replace any of its templates.

Product page: blocks in product.info.additional (under Add to Cart) and, optionally, in the detailed_info section group.
Cart page: plugins on Magento’s cart item renderer (Magento\Checkout\Block\Cart\Item\Renderer) and on the cart block’s getItems() / getItemHtml().
Mini-cart: Hyvä’s drawer (#cart-drawer), through the cart section data: the gift’s price, an option row (“Gift: Free with X”) and, for sub-lines, the gift shown under its product. The progress bar goes in cart-drawer.items.before.
Styles: one <style> block scoped to .slova-fg, using only the theme’s CSS variables (--color-primary, --color-on-primary, --color-fg, --color-fg-secondary, --color-surface, --radius-*, --text-sm), with fallbacks. Gift lines hide their quantity field and edit/remove buttons with :has() on Hyvä’s markup (.cart.item, input[data-role="cart-item-qty"], .item-actions, #cart-drawer li .btn).

Themes that draw gifts themselves get, in the cart section: is_free_gift, gift_for_product_id and gift_absorbed on gift lines, and free_gifts on the product line; free_gift_threshold on the cart (message, progress, availability, …). For product listings and custom product page markup: Slova\FreeGift\Model\GiftOffer::getActiveGift($productId) and getOfferingParents($giftId); for order pages: Slova\FreeGift\ViewModel\OrderGifts.

Orders and invoicing

A gift line is a normal order line at the gift’s value with a 100% discount, written to Magento’s native discount total: tax, invoices and credit memos work as for any discounted line, and invoicing tools that read line discounts see the gift for what it is. The order line also records what it was (product_options.slova_free_gift: per-product or cart gift, the product that gave it), so orders keep saying “Free with X” if the campaign changes later.

The cap counts gifts when the order is placed (soft cap): abandoned carts use nothing up. Under heavy concurrency the last few gifts of a campaign can go slightly over the cap.

Known limitations

One display currency. Gift values are computed in the store’s base currency; a store showing prices in several currencies needs a later version.
Customers cannot decline a gift: removing the gift line adds it back on the next cart update.
Checkout: gift lines go through any checkout that uses Magento’s quote; how a third-party checkout’s own order summary shows them depends on that checkout.

Translations

English (built in) and Romanian (i18n/ro_RO.csv). Other languages: translate the phrases of i18n/ro_RO.csv into a language pack, or set the texts per store view in Texts.

Support

Slova — https://slova.tech