Usage

Setting up a free shipping goal

Option A: Automatic (recommended)

Make shipping free from a certain amount in your shipping method. The bar then reads it automatically.

1. Open the shipping methods list (admin.php?dispatch=shippings.manage: Settings → Shipping & taxes → Shipping methods in 4.17, Administration → Shipping methods in 4.18; Multi-Vendor vendors edit their own methods in the vendor panel) and open a method with Rate calculation: Manual.

2. On the Shipping charges tab, for each rate area, add cost-based ranges, for example:

   Order cost from	to	Rate
   0	49.99	5.00
   50	(empty)	0.00

   Keep the base rate at 0. Otherwise shipping never becomes free.

3. In the add-on settings, check General → Detected goals: the method, the rate area and Free from $50.00 should be listed.

Alternatively, create a cart promotion with the condition Subtotal is greater than or equal to 50 and the bonus Free shipping. It also appears as the free-shipping goal.

Detection rules:

• Only manual rates can be read. Realtime carrier rates (UPS, FedEx, …) come from the carrier and have no fixed threshold.
• The threshold is the first cost range where the rate drops to 0 while the range before it is still charged. Methods that are always free, such as Store pickup, are ignored.
• The calculation uses the customer’s rate area, so different countries can show different thresholds.
• If several methods have a threshold, the bar shows the one the customer reaches first.
• Products marked Free shipping and downloadable products count the same way as in the core shipping calculation.

Option B: Manual threshold

Set Free shipping goal source = Manual threshold only and enter the Free shipping threshold, with optional amounts per currency. Use this mode when shipping is made free by a mechanism the add-on cannot read, such as a realtime carrier with a discount from a third-party add-on. You are responsible for making shipping actually free from that amount.

In Automatic mode, the manual threshold also works as a fallback when no rule is detected for the cart.

Promotion goals (gift, discount)

Any active cart promotion with a condition Subtotal is greater than or equal to X (or greater than) becomes a goal when the customer is below X. The promotion’s other conditions (customer group, products, country, …) are evaluated by the core promotion engine as if the subtotal were X, so the bar only promises bonuses the customer can actually get.

The goal type comes from the bonus:

Bonus	Goal type	Default message
Free products	gift	Add [amount] more to get a free gift: [goal]
Order discount, discount on products / categories	discount	Add [amount] more to unlock: [goal]
Free shipping	free_shipping	You are [amount] away from free shipping
Anything else (give coupon, user group, …)	reward	Add [amount] more to unlock: [goal]

[goal] is the promotion name in the visitor’s language, so give customer-facing names to promotions you want to advertise, for example “Free tote bag” or “10% off your order”. Promotions that need a coupon code and promotions with the Hidden status are never shown.

When several goals are active, they are drawn as tiers (markers) on one bar. The message names the nearest goal, and already unlocked goals are listed below the bar (“Unlocked: free shipping”). The number of upcoming tiers is set by Upcoming goals shown on the bar.

Placements

Placement	Layout	Updates after cart changes
Mini-cart (Cart content block dropdown)	compact	Re-rendered with the block (cart_status*)
Cart page (top of the totals box)	full	Cart form AJAX (cart*, checkout*)
Checkout (above shipping methods)	full	Inside the shipping methods section, re-rendered by the checkout
“Added to cart” popup	compact	Rendered with the notification
Product page	full	Loaded by AJAX, refreshed after add to cart
Sticky bar (top/bottom)	compact	Re-rendered on add to cart (cart_status*)
Block Manager block	full or compact	Re-rendered on add to cart (cart_status*)

Product page

The product page main content is block-cached by CS-Cart for guests. A cart-dependent bar inside it would show stale data, so this placement renders an empty, cache-safe container. The storefront script fills it with one small AJAX request after the page loads and refreshes it after every cart change.

Block Manager

1. Open Design → Layouts (4.17) or Website → Themes → Layouts (4.18).
2. Choose a location and a grid, click + → Add block, and pick Shipping goal progress bar.
3. Choose the Layout: Full (message, bar, unlocked goals, vendor rows) or Compact (message and bar).
4. Save. The block is never cached, so it always reflects the current cart.

Wrapper tip: use no wrapper or a simple wrapper. The block always outputs a small invisible container, even when the bar is hidden, so a boxed wrapper such as Sidebox may show an empty frame while the cart has no goal.

Customizing texts

All texts are language variables. Open Administration → Languages → Translations (in 4.18: Administration → Texts & languages), search for kv_free_shipping_progress_bar. and edit the values. Placeholders:

• [amount]: the remaining amount (or the full threshold for an empty cart), formatted in the visitor’s currency;
• [goal]: the goal name (promotion name, or the generic goal_* text);
• [vendor]: the vendor name (accessibility label only).

Variable	Default (English)
intro_free_shipping	Free shipping on orders over [amount]
intro_gift / intro_discount / intro_reward	Spend [amount] and get a free gift: [goal] / Spend [amount] and unlock: [goal]
remaining_free_shipping	You are [amount] away from free shipping
remaining_gift	Add [amount] more to get a free gift: [goal]
remaining_discount / remaining_reward	Add [amount] more to unlock: [goal]
reached_free_shipping	Congratulations! Your order ships for free.
reached_gift	Nice! You have unlocked a free gift: [goal]
reached_discount / reached_reward	Great! You have unlocked: [goal]
goal_free_shipping / goal_gift / goal_discount / goal_reward	free shipping / a free gift / a discount / a reward
unlocked	Unlocked: [goal]
vendors_intro	Free shipping is calculated separately for each seller:
vendors_all_reached	Congratulations! Everything in your cart ships for free.
vendor_remaining / vendor_reached	[amount] more for free shipping / Free shipping
progress_label, vendor_progress_label, close	Screen-reader labels

Simple HTML such as <strong> is allowed in the intro_*, remaining_* and reached_* messages. The other texts are printed as plain text.

Multi-currency

All calculations use the primary currency, and amounts are displayed in the visitor’s selected currency through the core price formatter. This respects decimals, separators, symbol position and the Show prices in selected and alternative currency setting. To show “round” amounts per currency, use Thresholds per currency.

Multi-Vendor behavior

Multi-Vendor splits the cart into one shipment per vendor, and each vendor has its own shipping methods. The add-on follows that model:

• Cart with products from one vendor: one bar, exactly like CS-Cart.
• Cart with products from several vendors: promotion goals (cart-wide) stay on the main bar. Free shipping is shown as a compact row per vendor: vendor name, remaining amount and a mini bar.
• Each vendor’s threshold is read from that vendor’s shipping methods (Automatic mode), so different vendors can have different thresholds.
• With a manual threshold you choose per vendor (default, matches the shipment split) or for the whole cart (when your marketplace makes shipping free for the whole order, for example with a promotion).
• Groups shipped by the marketplace (Common Products / order fulfillment) and groups without shipping (downloads) are skipped.

Direct Customer-to-Vendor Payments (separate checkout): this add-on replaces the cart with per-vendor carts that have their own templates. The mini-cart, sticky bar and block placements keep working. The cart-page placement relies on the core cart template and may not appear in the separate per-vendor carts in 1.0.0. Use a Block Manager block instead.

Ultimate (CS-Cart) storefronts

Every setting can be configured per storefront. The threshold is calculated from the shipping methods available to that storefront.