Instructions for Time Until Gift

What the add-on does

The add-on tracks cart promotions and shows customers their progress toward the next bonus. It supports conditions based on order subtotal and product quantity, calculates the remaining value until the bonus, and passes this data to storefront blocks, the mini cart, and the add-to-cart popup.

For each promotion, you can enable a dedicated notification, define a storefront title, and upload an image. If the store still has legacy csc_promo_progressbar blocks, the add-on migrates them to the current MS: Time Until Gift block type during the update.

Where to find it

• Marketing → Promotions, where the MS Time Until Gift tab appears on the promotion page.
• Add-ons → Time Until Gift → Settings, where you configure display in the add-to-cart popup and the compact progress bar in the cart.
• Design → Layouts, where you add the MS: Time Until Gift block and select its template.

How to configure a promotion

1. Open Marketing → Promotions and create or edit a cart promotion.
2. Make sure the promotion is active and its availability period is suitable for testing.
3. On the Conditions tab, add one of the supported rules, for example Order subtotal >= 1000 or Number of products in cart >= 3.
4. On the Bonuses tab, configure the gift or another bonus that should become available after the threshold is reached.
5. On the MS Time Until Gift tab, enable Show promotion notification.
6. If needed, fill in Storefront promotion title. If this field is empty, the regular promotion name is used.
7. If needed, upload the Image for the promotion page used in storefront templates.

How to configure the add-on

1. Open Add-ons → Time Until Gift → Settings.
2. Enable Show inside "Add to cart" pop-up if you want to display progress immediately after a product is added.
3. Enable Show compact progress bar in the cart if the cart should display a compact indicator for the nearest promotion.
4. Save the settings.

How to place the block on the storefront

1. Open Design → Layouts.
2. Add the MS: Time Until Gift block to the required page area, most often the cart page or another checkout-related area.
3. Select the block template according to the desired display scenario.

• Normal block, shows progress for several promotions within one main metric.
• Consolidated block, shows bonuses already available and those still ahead.
• Single block, shows one selected promotion.
• Circular block and Circular short block, compact one-promotion layouts.
• Compact progress bar, a narrow indicator for the nearest promotion that can work automatically or for a specific selected promotion.

For templates that work with one promotion, the block settings include the Promotion field. The list contains only cart promotions with the Show promotion notification option enabled.

Limitations and important conditions

• The add-on works only with cart promotions. Catalog promotions are ignored.
• Automatic progress calculation is supported for order subtotal and product quantity conditions.
• If a promotion zone is not Cart, the add-on cannot use it in storefront blocks.
• If Show promotion notification is disabled for a promotion, it will not appear in the block selector.

How to verify that it works

1. Create a test cart promotion with a bonus and a condition based on order subtotal or product quantity.
2. Enable Show promotion notification for it and optionally define a storefront title.
3. Place the MS: Time Until Gift block on the cart page or enable display inside the add-to-cart popup.
4. Add products to the cart below the threshold. The storefront must show how much is left until the bonus.
5. Increase the subtotal or product quantity to the threshold. The add-on must show that the bonus is now available.
6. If a single-promotion template is used, verify that the required promotion is selected in the block settings.

What to check if a promotion is not shown

• The promotion is created as a cart promotion, not a catalog promotion.
• The promotion period is active.
• The Show promotion notification option is enabled on the MS Time Until Gift tab.
• The promotion conditions use a supported metric, either subtotal or product quantity.
• CS-Cart cache has been cleared if the storefront does not refresh the block immediately.