Free Gift

Give something away without giving away control. A campaign decides for itself when a basket qualifies, adds the gift at no charge, advertises itself only on the surfaces you allow, and lets the shopper say no thank you and mean it. You see what every campaign cost you, in a report that remembers the gift's value on the day the order was placed.

Latest version: 1.0.0 — changelog

Who it's for

Stores running gift-with-purchase promotions next to their discounts. Campaigns have their own screen and their own tables, so they never compete with Cart Price Rules or another extension over the salesrule form.
Stores that let the customer choose. Offer a pool and an allowance; the cart shows a card with the choices and how many picks are left.
Stores that run buy-X-get-Y, same-SKU BOGO or spend tiers. Four gift modes on one form: add automatically, let the customer choose, tiered by spend, one per N bought.
Headless and PWA storefronts. REST in three authorisation families and GraphQL, over the same engine the cart page uses, so the API and the storefront never disagree.
Stores on Hyvä. Templates for every storefront surface, and gift controls inside licensed Hyvä Checkout.

Why it matters

A promotion that runs itself. Gifts are reconciled when the quote collects its totals, so a basket that qualifies gets its gift whether the change came from the storefront, the REST API, GraphQL or an administrator building the order.
A refusal that sticks. A shopper who removes a gift does not get it pushed back on the next page view, and can change their mind later from the same panel.
No surprise tax bills. Each campaign decides whether its gift is taxed on the promotional price the customer pays or on the original catalog price, and the choice carries through cart, order, invoice and refund.
Nothing promised that cannot be delivered. A gift that runs out of stock is withdrawn without disturbing the rest of the basket, and backorderable gifts are off by default.
Launch day needs no reindex. A campaign with a start date is prepared in advance and begins on the day; stopping it drops the cached pages that advertised it.
You know what it cost. The campaign report records each gift's catalog value when the order is placed, so a later price change never rewrites history.

See it in action

You set a campaign's Badge Label to Free tote with this bag → you get that sentence on the trigger product's page and on its category tile, in your words rather than anything derived from the product description.
You offer a pool of three gifts with Number of Gifts set to 2 → you get a card in the cart headed "Choose 2 free gifts", showing each gift, what was taken, and how many picks are left, which stops offering once the allowance is spent.
You pick the Spend tiers starter template with a threshold of 50 and a quantity of 1 → you get a disabled draft with two tiers ready to review, 50 unlocking one gift and 100 unlocking two, and a progress bar in the cart that tells the shopper how much more to spend.

Features

Every feature has a walkthrough in the usage guide, one page per row.

Feature	Benefit
Campaigns	Campaigns on their own screen, apart from your discounts, with Magento's familiar condition builder, wording per store view, start and end dates, and a duplicate-as-draft to build the next one from the last
Gifts and gift modes	Add the gift automatically, let the customer choose from a pool, tier by spend, or give one per N bought, including same-SKU BOGO, under a store-wide and a per-campaign cap on gift units
Conditions, coupons and limits	Qualify a basket by product or by merchandise value, unlock a gift with a code that is advertised nowhere until it is entered, cap redemptions per customer and in total, and decide the gift's tax basis per campaign
Starter templates	Five ready-made drafts: spend threshold, customer choice, spend tiers, buy X get Y and BOGO, each disabled until you switch it on
Preview a campaign	Evaluate a saved campaign against a sample cart and read, in words, why it qualifies or not, without touching a real cart
Campaign report	Orders, gross and net gift units, frozen catalog value and influenced revenue per campaign and store, with a CSV export
Where campaigns advertise	Each campaign picks its surfaces: server-rendered product and category badges, an add-to-cart popup, and a widget placed from Content → Widgets with no layout XML
In the cart and at checkout	Earned gifts at zero, choices still open, spend-tier progress, a refusal that sticks with a way back, and the same controls inside licensed Hyvä Checkout
Scheduling, indexing and caching	Campaigns start and stop on their dates with no reindex on launch day, and the cached pages that advertised a campaign are dropped when it changes
REST and GraphQL	The same gift state for integrations, signed-in shoppers, guests and headless storefronts
Multi-Source Inventory	An optional package answers gift stock per sales channel
Out-of-stock behaviour	Hide an unavailable gift, or show it greyed out so customers know it exists; backorderable gifts are off by default

The campaign preview explaining why a sample cart qualifies

Competing solutions

The right-hand column describes common practice on the extension market, not any particular vendor.

	Qoliber	Typical marketplace extension
Packagist installation	Installed and updated with Composer from our private Packagist (`qoliber.repo.packagist.com`)	Varies by vendor
Slack access to the development team	A shared Slack channel with the developers who build and maintain the module	Usually ticket-based
Unit tests	414 PHPUnit unit tests (72 classes) in the repository	Not typically published
Integration tests	385 Magento integration tests (89 classes), run before every release	Not typically published
E2E Playwright tests	127 Playwright end-to-end tests on Luma and Hyvä (37 spec files), run before every release	Not typically published
Documentation	Full docs portal: install, configuration, usage, API reference and a developer guide	Varies by vendor
Hyvä support	Storefront surfaces as Hyvä templates, and gift controls inside licensed Hyvä Checkout	Varies by vendor
PHP / Magento range	PHP 8.1 to 8.5 on Magento Open Source 2.4.6 to 2.4.9	Varies by vendor

What makes it different

Hyvä-native. qoliber/free-gift-hyva ships the storefront surfaces as Hyvä templates with Tailwind built for both the v3 and v4 compilers, and qoliber/free-gift-hyva-checkout adds gift controls to licensed Hyvä Checkout as a Magewire component.
API-first. Six gift actions over REST for integrations, signed-in shoppers and guests, and four GraphQL mutations, all over the same service contracts the storefront uses.
Runs inside your store. The rule engine, the indexer, the report and the cron jobs are Magento code against your database. There is no third-party service to call and no data leaves the store.

Good to know

Release 1 gives away simple, virtual and downloadable products. A configurable gift is refused at save time, with the release that will support it named, and so is a product with required custom options.
Basket-earned and coupon-gated campaigns show no product badge, by design: there is no single product to badge, and a coupon gift is not advertised before the code is entered.
Multi-Source Inventory is a separate package. The core answers stock through Magento_CatalogInventory; install qoliber/free-gift-msi only if you run multiple sources.
Gift controls inside Hyvä Checkout need a Hyvä Checkout licence. The theme package and the suite work without one.
Native single-address checkout is supported; native multishipping is outside the supported paths.

Supported versions

PHP 8.1 through 8.5 on Magento Open Source 2.4.6 through 2.4.9, using the PHP version each release supports (magento/framework >=103.0.6 <103.0.10). Adobe Commerce and Mage-OS need their own validation.