One rule shapes the whole plugin: your store's own configuration is the only source of truth. The bar never asks you for a threshold. It reads the Free shipping method WooCommerce itself would apply to the shopper's cart, and measures the cart the way WooCommerce does when it decides whether free shipping is available. If the bar says "unlocked", the checkout offers free shipping; if the store has no rule the bar can count towards, there is no bar at all rather than a made-up number.
Step 1: is there anything to show?
On each page with a placement, the plugin checks, in order:
- WooCommerce shipping is enabled.
- The cart holds something that needs shipping. A cart of downloads only gets no bar. (The free edition also shows no bar on an empty cart.)
- A Free shipping method exists in the zone that matches this cart.
If any check fails, nothing is printed.
Step 2: which zone, which rule
The plugin takes the cart's shipping package and asks WooCommerce's own WC_Shipping_Zones::get_zone_matching_package() for the zone. It does not re-implement zone matching, so postcode ranges, states and the "Locations not covered by your other zones" fallback behave exactly as at checkout.
Inside that zone, it looks at the enabled Free shipping methods and their Free shipping requires… setting:
| Requires | Free edition | Full edition |
|---|---|---|
| N/A (always free) | no bar — nothing to count towards | no bar |
| A minimum order amount | the bar | the bar |
| A valid free shipping coupon | no bar | no bar until a free-shipping coupon is applied, then the congratulations message |
| A minimum order amount OR a coupon | no bar | no progress bar; the congratulations message once the amount is reached or a free-shipping coupon is applied |
| A minimum order amount AND a coupon | no bar | the bar; unlocked only with both |
The free edition uses the first enabled minimum-amount method it finds. The full edition evaluates every Free shipping method in the zone, as WooCommerce offers each one, and shows the one already unlocked or, if none is, the one nearest to unlocking.
A minimum of 0 counts as no minimum, so it shows no bar.
Step 3: measure the cart the way WooCommerce does
The bar uses the same arithmetic as WC_Shipping_Free_Shipping::is_available():
- Start from the displayed cart subtotal — including tax if your store shows prices including tax.
- Unless the method's Apply minimum order rule before coupon discount box is ticked, subtract the cart's discounts (and the discount tax, when prices are shown including tax).
- Round to your store's number of decimals.
Example: minimum 50.00, prices shown including tax, a cart subtotal of 55.00 and a 10% coupon. The coupon takes 5.50 off, so the cart measures 49.50 and the bar says "Add 0.50 more". If Apply minimum order rule before coupon discount is ticked, the cart measures 55.00 and the bar says free shipping is unlocked — exactly what the checkout will then offer.
The amount still missing is the minimum minus that figure, never below zero. The fill is that figure as a share of the minimum.
Step 4: where the bar appears
Free edition. The bar is printed on the server when the page is built:
- Shop and category pages — on
woocommerce_before_shop_loop. - Cart page — on
woocommerce_before_cartfor a classic cart, and directly above the Cart block on a block-based cart page. The block page never runs the classic template, so without the second route a new store (whose cart page is the block) would show nothing.
The free edition has no JavaScript. The bar reflects the cart as the page loaded; after the shopper changes quantities on the cart, it updates on the next page load.
Full edition. The same placements plus the mini-cart and the checkout (classic hook, or above the Checkout block). The bar is also re-rendered through WooCommerce's own cart fragments and the classic checkout's order-review refresh, so on the classic cart, the mini-cart and the classic checkout it follows the cart without a reload — after an add-to-cart, a quantity change, a removal or a coupon. The Cart and Checkout blocks update their totals over the Store API and fire none of those fragment events, so there the script watches the block cart's data store (wc/store/cart) and, when the totals move, fetches the same bar from WooCommerce's own get_refreshed_fragments endpoint — the same server render as every other refresh.
A small script mirrors the message into one hidden live region, so screen readers announce the change once rather than every time the bar is replaced.
Manual placement — Full edition
- The Free Shipping Bar block (
gatemi-free-shipping-bar/bar) and the[gatemi_free_shipping_bar]shortcode print the same bar anywhere. - A singular page that holds either one is skipped by the automatic placements. Manual placement always wins, so a page never shows two bars.
- The block can be added once per page.
When both editions are active
The free edition checks for the full edition when it loads. If it is active, the free edition registers nothing and shows a line under its own entry on the Plugins screen explaining why. Only one bar is ever painted.
