Cart Progress Bar Documentation

Installation – top

Uploading

1. Download the add-on
2. Go to Admin panel > Add-ons > Manage Add-ons
3. Click on [+] to open upload modal window
4. Please choose whatever is comfortable to you:
   – Local: zip archive is saved on your computer
   – Server: zip archive is uploaded on your server
   – URL: you have a direct link to the zip archive
5. After you selected the zip archive corresponding to your current version of CS-Cart please click Upload & install

Activation

1. Open add-on settings page Admin panel > Add-ons > Manage Add-ons >
   Select add-on
2. In Activation tab insert License key
3. Save the settings and go back to Manage Add-ons page
4. In same line with the name of the add-on, click Active
5. Clear cache, choose Administration > Storage > Clear cache

Make sure that the add-on status is Active

That’s all, the add-on is installed

Settings – top

Block – top

For the checkout page or any other layout locations where you want to display the progress bar, you can add the block
[TH] Cart Upsell Bar

Location limitations – top

If you use location-based conditions (country, state, city, etc.) for promotions, please note the following:

• The Maps and Geolocation add-on must be active and properly configured.
  (setup guide)
• If the Maps and Geolocation add-on is disabled, promotions with location conditions will be shown only to customers who have already specified their shipping address.

  The shipping address can be defined on:

  • Checkout page
  • Cart page (if shipping is calculated there)
  • Customer profile

This behavior is standard for CS-Cart and is not related to the add-on logic.
To ensure correct promotion visibility for all visitors, make sure that Maps and Geolocation is enabled.

Hooks & Extensibility – top

The Cart Progress Bar add-on provides a hook that allows third-party add-ons or custom code
to modify or add cart promotions dynamically before they are processed and displayed.

This is useful if you want to:

• Add custom or virtual promotions without saving them in the database
• Modify existing promotion conditions or bonuses
• Integrate external logic (custom discounts, loyalty systems, etc.)

Available hook

ath_cart_progress_bar_get_front_promotions

This hook is executed right after promotions are fetched and before any filtering
(date, subtotal, location, vendor, etc.) is applied.

Hook signature

fn_set_hook(
    'ath_cart_progress_bar_get_front_promotions',
    $promotions,
    $params,
    $lang_code
);

Parameters

• $promotions – array of promotions fetched for the cart (passed by reference)
• $params – parameters used to fetch promotions (zone, active, etc.)
• $lang_code – current storefront language code

Example: adding a custom promotion

function fn_my_addon_ath_cart_progress_bar_get_front_promotions(
    &$promotions,
    $params,
    $lang_code
) {
    $promotions[] = [
        'promotion_id'         => 0,
        'company_id'           => 0,
        'ath_show_in_cart_bar' => 'Y',
        'from_date'            => 0,
        'to_date'              => 0,
        'conditions'           => [
            'conditions' => [
                [
                    'condition' => 'subtotal',
                    'operator'  => 'gte',
                    'value'     => 200
                ]
            ]
        ],
        'bonuses' => [
            [
                'bonus' => 'free_shipping'
            ]
        ],
        'ath_reward_text'      => __('free_shipping'),
        'ath_before_goal_text' => __('add_more_for_free_shipping'),
        'ath_icon_pair'        => []
    ];
}

This approach allows you to fully control how promotions are calculated and displayed in the progress bar,
while keeping the core add-on logic intact.

Change styles

You can edit/change it in Design tab in add-on settings

or

Style files add-on should not be changed, this can lead to incorrect work of the add-on. If there was a need to redefine or add styles, please use Theme editor for this

1. Go to Design > Themes
2. Press Visual Editor in front of the currently active layout
3. In the new tab, you will see your shop with Theme editor panel
4. In CUSTOMIZE selector choose Custom CSS
5. In textarea you can add your styles
6. After editing save your changes by pressing Save and press [X] to close editor

Add-on Update – top

The update through the Update Center

Changelog

2.04 (August 27, 2026)
Compatible with CS-Cart 4.21
The bar next to the buy buttons takes the full width of the buttons, it could shrink to the width of its labels
An update through the Upgrade Center now reliably delivers the settings of a new version and restores any that went missing
The update server answers in the language of the admin panel
The license system has been updated

2.03 (18 August 2026)
Storefront
The bar fits themes with their own cart: a custom minicart keeps its layout
New setting: pin the bar in the cart dropdown, so it stays in view while the list scrolls
In the cart dropdown the bar is shown at the top
One script less on the product page

Languages
The add-on is translated into all 30 languages of the package

Under the hood
PHP 8.2 and 8.3 compatibility
The license system has been updated

2.02 (22 Dec 2025)
Added support for default user group promotion restrictions
Added hook ath_cart_progress_bar_get_front_promotions
Fixed text placeholders
Improved texts
CSS fixes

2.01 (18 Nov 2025)
Added location support

2.00 (22 Oct 2025)
[!] Reinstallation of the add-on is required
The add-on functionality is now linked to promotions
Supports the Direct Payments add-on

1.01 (01 Sep 2025)
Fixed a bug in the display on the detailed product page

1.00 (01 Sep 2025)
Release