Overview
↑ Back to topCart Free Gift rewards customers with a free product once their cart subtotal reaches a spending threshold you define. The gift is added to the cart automatically, priced at zero, locked to a quantity of one, and labelled with a customizable badge. When the cart drops back below the threshold, the gift is removed automatically (optional), and if a customer removes the gift themselves, the plugin respects that choice for the rest of the session. The engine works with the classic cart and checkout shortcodes, AJAX cart updates, and the Cart and Checkout blocks.
Installation
↑ Back to top- Upload the
cart-free-giftfolder to the/wp-content/plugins/directory - Activate the plugin through the ‘Plugins’ menu in WordPress
- Navigate to WooCommerce > Settings > Products > Cart Free Gift, pick a gift product, set the threshold, toggle Enable free gift on, and save (the plugin ships disabled by default)
Requirements
↑ Back to top- WordPress 6.4 or higher
- WooCommerce 9.0 or higher
- PHP 7.4 or higher
Settings
↑ Back to topAccess settings at WooCommerce > Settings > Products > Cart Free Gift. Settings are organized into two tabs.
General
↑ Back to top| Setting | Description | Default |
|---|---|---|
| Enable free gift | Master switch. When off, the plugin does not touch the cart at all. | Disabled |
| Cart subtotal threshold | Minimum cart subtotal required to unlock the free gift. | 50 |
| Gift product | Searchable picker for a published, purchasable simple product to offer as the free gift. | None selected |
| Include coupon discounts | Subtract coupon discounts from the cart subtotal before comparing it to the threshold. | Enabled |
| Remove the gift when the cart drops below the threshold | When off, the gift stays in the cart once it has been unlocked for the session. | Enabled |
The General tab also shows a Status card: READY with the configured gift name, price, and threshold, or NOT CONFIGURED when no gift product is selected (in that case nothing is ever added to the cart).
Messages
↑ Back to top| Setting | Description | Default |
|---|---|---|
| Gift label | Displayed as a badge on the gift line in the cart and stored on the order. | FREE GIFT |
| Show unlock notice | Display a success notice when the gift is added to the cart. | Enabled |
| Unlock notice text | Shown once per unlock, as a WooCommerce success notice. | Congratulations! A free gift has been added to your cart. |
How It Works
↑ Back to topQualifying subtotal
↑ Back to topOn every totals calculation, the plugin computes the qualifying subtotal from all cart lines except flagged gift lines. The calculation is tax-aware: prices are taken including or excluding tax to match how your store displays cart totals. When Include coupon discounts is enabled, the cart’s coupon discount total (and discount tax, when prices include tax) is subtracted. The result is compared to the threshold.
Add and remove engine
↑ Back to top- Threshold reached: if no gift line is in the cart and the customer has not declined the gift this session, the configured gift product is added automatically with a gift flag, at quantity one and a price of zero, provided it is a published, purchasable, in-stock simple product. The unlock notice is shown once per unlock.
- Every calculation: flagged gift lines are normalized, quantity forced back to one and price forced back to zero, so the gift line cannot be tampered with.
- Threshold no longer met: with auto-remove enabled (the default), the gift line is removed automatically. With auto-remove disabled, the gift stays for the session once earned.
Decline handling
↑ Back to topIf the customer removes the gift line via the cart’s remove link, the plugin records a decline in the WooCommerce session and stops re-adding the gift while the cart still qualifies. Restoring the line with the standard “Undo?” link cancels the decline. Once the cart drops below the threshold, the decline is reset, so the gift is offered again the next time the threshold is crossed. Automatic removals performed by the engine never count as a decline. All state (decline, notice shown) lives in session flags; nothing is stored per customer in the database.
Checkout guard
↑ Back to topA second validation pass runs on the cart and checkout pages: it removes flagged lines whose product no longer matches the configured gift, removes the gift when the threshold is no longer met (with auto-remove on), re-normalizes remaining gift lines, and ensures the cart never consists of free gift lines only.
Order item meta
↑ Back to topWhen an order is placed with the gift in the cart, the gift line item receives:
_cfg_free_gift=yes(hidden meta, for programmatic access)- A visible meta row using the configured gift label (e.g.
FREE GIFT: Yes) so admins can identify gifted lines on the order screen
REST API
↑ Back to topNamespace: cfg/v1. All routes require the manage_woocommerce capability.
| Route | Methods | Description |
|---|---|---|
/settings | GET, POST | Read and update plugin settings (threshold and gift product are validated server-side) |
/products | GET | Search published simple products for the gift picker (search parameter) |
/status | GET | Configured gift status (gift product details and threshold) shown on the settings page |
HPOS Compatibility
↑ Back to topCart Free Gift is fully compatible with WooCommerce High-Performance Order Storage (HPOS) and Cart/Checkout Blocks.
Uninstall
↑ Back to topDeactivation changes nothing in the database. Uninstalling (deleting) the plugin removes its single cfg_settings option. The plugin creates no custom tables and makes no external requests.