Cart Goals for WooCommerce shows your customers a single progress bar that tracks every reward waiting for them further up the cart: free shipping, a free gift, and any goal you define yourself. This document covers what the extension does, how to set it up, and how to adapt it to your store.
Overview
↑ Back to topCart Goals for WooCommerce adds a progress bar to your cart, mini cart, checkout, and product pages. The bar tracks the customer’s cart total against a list of goals, shows how much is missing before the next one, and marks each goal as it is reached.
The free shipping goal is detected automatically from the Free Shipping method already configured in your shipping zones, so you do not enter the amount twice. If you also run the Cart Free Gift extension, its gift threshold is added to the bar on its own. Beyond those, you can add your own goals, each with a label and a cart amount.
The bar updates as the cart changes, on both the classic cart and checkout and the WooCommerce Cart and Checkout blocks.
Requirements
↑ Back to top- WordPress 6.4 or higher
- PHP 7.4 or higher
- WooCommerce 9.0 or higher, tested up to WooCommerce 11.0
WooCommerce must be active. The extension declares WooCommerce as a required plugin and does nothing without it.
The free shipping goal needs a Free Shipping method in at least one shipping zone, set to require a minimum order amount. If you do not have one, you can enter a fixed amount instead, or rely only on your own goals.
Cart Free Gift is optional. When it is active and configured, its threshold joins the bar automatically. Nothing breaks when it is absent.
Installation
↑ Back to topThere are no extra installation steps. After activating the extension, go to WooCommerce > Settings > Shipping > Cart Goals and turn it on. It ships switched off, so nothing appears on your storefront until you enable it.
Usage
↑ Back to topAll settings live in one place: WooCommerce > Settings > Shipping > Cart Goals. The screen has two tabs, General and Display.
General tab
↑ Back to topDetected threshold
A read-only card at the top of the tab, showing the free shipping threshold the bar is currently using and where it came from. It reads one of three ways:
- The amount, plus the name of the shipping method and zone it was read from, when the threshold comes from your shipping zones.
- The amount, noted as coming from the manual setting, when you have chosen the manual mode.
- A message saying no threshold was found, when no Free Shipping method with a minimum order amount exists in your zones.
If the shipping method is set to ignore coupon discounts, the card says so, because that changes how progress is measured.
The card refreshes when you save, so it is the quickest way to confirm the extension is reading the right amount after you change a shipping zone.
Enable Cart Goals
The master switch. While it is off, no bar appears anywhere on your store and your configuration is left untouched. Default: off.
Threshold mode
Where the free shipping goal gets its amount.
- Automatic reads the minimum order amount from the Free Shipping method in the shipping zone that matches the customer. Change the amount on the shipping method and the bar follows, with nothing to update here. This is the default.
- Manual amount uses a fixed figure you enter, independent of your shipping zones. Choose this when your free shipping rules are handled elsewhere, or when you want the bar to show a target that differs from the shipping method.
Manual threshold amount
Only visible when Threshold mode is set to Manual. The cart amount required to unlock free shipping, in your store currency. Default: 50.
Cart goals
Your own goals, each one a label and a cart amount. Use them for anything you fulfill yourself: gift wrapping, a sample, priority handling, or a loyalty perk. You can add up to ten.
These are additional to the automatic goals. Free shipping is always a goal when a threshold can be resolved, and the Cart Free Gift threshold joins the list on its own when that extension is active. Goals are sorted by amount, lowest first, and two goals set to the same amount are collapsed into one.
A goal is a promise shown to the customer. The extension displays it and tracks progress toward it, but it does not add anything to the cart or apply a discount. Fulfilling the promise is up to you and your order workflow.
Apply coupon discounts
Measures progress against the cart subtotal after coupon discounts rather than before. Turn it off to measure the subtotal before discounts, so a coupon does not push a customer back below a goal they had already reached. This setting is ignored when the Free Shipping method is set to ignore discounts, because the shipping rule wins. Default: on.
Include tax
Includes tax in the measured amount when your store displays cart prices including tax. Turn it off to always measure excluding tax. Default: on.
Display tab
↑ Back to topLocations
Where the bar appears. Each location is independent.
- Cart page, above the cart, on both the classic cart and the Cart block. Default: on.
- Mini cart, inside the mini cart widget, refreshed when a product is added by AJAX. Default: on.
- Checkout, above the checkout form, on both the classic checkout and the Checkout block. Default: on.
- Product pages, above single product pages. The bar shows even when the cart is still empty, with the full amount remaining, so it works as an incentive before the customer has added anything. Default: off.
Progress message
The text shown while goals remain. Three placeholders are available:
{remaining}is the amount still missing before the next goal.{goal}is the label of the next goal, for example “Free shipping” or “Free gift wrap”.{threshold}is the amount of that next goal.
The default is “Add {remaining} more to unlock {goal}!”. Because the message always describes the next goal rather than the final one, it keeps making sense as the customer moves up the bar.
Achieved message
The text shown once every goal has been reached. Default: “Congratulations! You unlocked all the goals!”.
Show truck icon
Displays a small truck icon before the message. Default: on.
Appearance
- Bar color, the fill of the progress bar. Default:
#16a34a. - Bar background, the empty part of the track. Default:
#e0e0e0. - Text color, the message text. Default:
#1d2327. - Bar height, the thickness of the track in pixels, between 6 and 32. Default: 12.
Live preview
A preview of the bar using your current settings, shown both mid-progress and in the achieved state, so you can judge colors and wording without saving and reloading your storefront.
How the bar behaves
↑ Back to topThe bar spans from zero to your highest goal. Each goal appears as a labeled marker on the track and fills in as it is reached. When only one goal exists, the markers are hidden and the bar reads as a plain progress bar.
A few behaviors are worth knowing:
- On the cart, mini cart, and checkout, the bar hides itself while the cart is empty. On product pages it always shows.
- A coupon that grants free shipping marks the free shipping goal as reached immediately, whatever the cart total.
- If no goal at all can be resolved, meaning no threshold, no gift, and no custom goals, the bar does not render.
- The bar refreshes on cart changes without a page reload, including quantity changes, coupons, and AJAX add-to-cart.
Use cases
↑ Back to topA store that only wants a free shipping bar
Leave Threshold mode on Automatic, add no custom goals, and do not run Cart Free Gift. The bar shows a single goal and behaves as a classic free shipping progress bar, reading its amount from your shipping zone.
A store running a free gift promotion
Install Cart Free Gift and set its threshold, for example 30, then set your Free Shipping method to 60. The bar shows both goals in order: the gift first, then free shipping. A customer at 25 is told what is missing before the gift, and a customer at 35 is told what is missing before free shipping.
Adding a perk you fulfill by hand
Add a custom goal labeled “Free gift wrap” at 90, above your free shipping threshold. Customers who have already earned free shipping now have a reason to keep going. You watch for orders above 90 and wrap them, since the extension tracks the goal but does not act on it.
A tiered loyalty ladder
Add three custom goals, for example “Sample sachet” at 40, “Priority handling” at 120, and “VIP gift” at 250, alongside your free shipping goal. The bar becomes a ladder, and the progress message always points at the next rung rather than the top.
Free shipping handled outside your shipping zones
If a third-party extension or custom code grants free shipping, switch Threshold mode to Manual and enter the amount your rule uses. The bar then advertises the correct figure without you having to create a matching shipping method.
FAQ
↑ Back to topDo I have to enter my free shipping amount twice?
No. In Automatic mode the extension reads the minimum order amount straight from the Free Shipping method in the shipping zone matching the customer. Change it on the shipping method and the bar follows.
Does the extension add the free gift to the cart?
No. Cart Goals displays goals and tracks progress. Adding a gift to the cart is what the Cart Free Gift extension does. When both are active, Cart Goals reads the gift threshold from Cart Free Gift so the two always agree, and Cart Free Gift adds the product.
What happens with my own goals? Does anything get added automatically?
Nothing. A custom goal is a promise displayed to the customer. You fulfill it in your own workflow, which is what makes custom goals useful for things no extension can do for you, such as gift wrapping or a handwritten note.
Does it work with the Cart and Checkout blocks?
Yes. The bar renders above both the classic shortcodes and the Cart and Checkout blocks, and refreshes on block cart events.
Why is the bar not showing?
Check three things, in order. First the master switch on the General tab, since the extension ships switched off. Then the location, on the Display tab, since product pages are off by default. Then the detected threshold card, since the bar does not render when no goal at all can be resolved. Note also that the bar stays hidden on the cart and checkout while the cart is empty.
A customer applied a coupon and went backwards. Can I stop that?
Yes. Turn off Apply coupon discounts on the General tab, and progress is measured on the subtotal before discounts. If your Free Shipping method is itself set to ignore discounts, that setting already wins and the bar follows it.
Can the bar be wider or narrower on product pages?
It follows your theme’s content width. If your product template uses a different measure, a developer can set the --fsb-product-max-width CSS variable to match.
Developer documentation
↑ Back to topSettings are stored in a single option, fsb_settings. The extension creates no database tables and writes no logs.
Filters
↑ Back to topfsb_milestones
Filters the assembled list of goals before they are sorted and de-duplicated. It fires on every calculation of the bar.
Each goal is an array with id, label, amount, and source. The source is one of free_shipping, cart_free_gift, or custom.
add_filter(
'fsb_milestones',
function ( $milestones ) {
$milestones[] = array(
'id' => 'wholesale_tier',
'label' => 'Wholesale pricing',
'amount' => 500.0,
'source' => 'custom',
);
return $milestones;
}
);Goals are sorted by amount after this filter runs, and two goals with the same amount are collapsed, with the earlier source winning in the order free shipping, gift, custom.
REST API
↑ Back to topNamespace: fsb/v1.
| Route | Methods | Permission | Description |
|---|---|---|---|
/settings | GET, POST | manage_woocommerce | Read and write the extension settings |
/status | GET | manage_woocommerce | Resolved threshold, its source, the zone and method names, and the ignore-discounts flag |
/bar | GET | Public | Rendered bar markup for the current cart session |
The /bar route is public because it serves the storefront. It accepts a context argument, one of cart, mini_cart, checkout, or product, returns markup only, contains no personal data, and is never cached. Requests from the storefront send the wp_rest nonce, without which WooCommerce does not resolve the logged-in cart session.
Front end integration
↑ Back to topThe bar is rendered server side and refreshed two ways: as a registered woocommerce_add_to_cart_fragments fragment for the mini cart, and by re-fetching /bar from the front-end script on cart and checkout events, both classic jQuery events and Cart and Checkout block events.
Output hooks used, for reference when adjusting placement:
woocommerce_before_cartwoocommerce_before_checkout_formwoocommerce_before_mini_cartwoocommerce_before_single_productrender_block, to prepend the bar to thewoocommerce/cartandwoocommerce/checkoutblocks
CSS custom properties
↑ Back to topThe bar exposes its configured appearance as custom properties on the .fsb-bar element, so a theme can restyle it without touching the extension:
--fsb-bar-color--fsb-bar-background--fsb-text-color--fsb-bar-height
One further property is read from the page rather than written by the extension:
--fsb-product-max-widthconstrains the bar on single product pages. It defaults to the theme’s--wp--style--global--wide-size, and falls back to no constraint on themes that do not define one.
Compatibility
↑ Back to topThe extension declares compatibility with High Performance Order Storage (HPOS) and with the Cart and Checkout blocks.