Countdown Promotion for Magento 2

Installation and configuration guide for Countdown Promotion for Magento 2

The Kowal_CountdownPromotion module adds a promotion end countdown to Magento 2. The countdown can be visible on category listings and product pages when the product has an active special price and a set promotion end date.

The visible countdown is created by JavaScript after the page loads. The backend passes only technical data to the frontend, including the product ID and promotion end timestamp.

Requirements

Before installation, make sure your store meets the requirements:

• Magento Open Source or Adobe Commerce 2.4.x,
• PHP 7.4 or PHP 8.1+ according to the Magento version,
• ability to install Composer packages of the magento2-module type,
• access to Magento CLI,
• access to the module repository.

Installation with Composer

Go to the Magento project root directory.

Add the Kowal Composer repository to the project configuration:

You will receive access credentials for the Composer repository (customer email address and license token) by email after purchase. They are also available in the customer panel after logging in at kowal.store. Replace TWOJ_EMAIL_KLIENTA with your account email address and TWOJ_TOKEN with the token you received. Run the commands in the Magento root directory.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
composer require kowal/module-countdown-promotion

After installation, Composer will place the module in the directory:

vendor/kowal/module-countdown-promotion

Enabling the module in Magento

Run Magento commands from the store root directory:

bin/magento module:enable Kowal_CountdownPromotion
bin/magento setup:upgrade
bin/magento cache:flush

In a production environment, you usually also need to run the deployment commands used in the project:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento indexer:reindex
bin/magento cache:flush

Product configuration

For each product where the countdown should appear:

1. Set Countdown Promotion to Yes.
2. Set Special Price.
3. Set Special Price To Date.
4. Optionally set Special Price From Date.

The countdown will appear only when all conditions are met:

• the countdown_promotion attribute is enabled,
• special_price is set,
• the special price is lower than the regular price,
• special_from_date is empty or the promotion has already started,
• special_to_date is set in the future.

For configurable products, enable Countdown Promotion on the parent product. The module can use the promotion date from the parent product or active promotion dates from associated simple products when the promotion is set on variants.

Module configuration

Module options are available in the Magento admin panel:

Stores > Configuration > Catalog > Countdown Promotion > Appearance

After changing the configuration, clear the cache:

bin/magento cache:flush

Countdown placement settings

The Category Placement field defines the countdown position on the category listing.

Available options:

• Below price - countdown below the price,
• Bottom of product image - countdown at the bottom of the product image,
• Top of product image - countdown at the top of the product image,
• Custom CSS selector - countdown next to the element specified by a custom CSS selector.

When you select Custom CSS selector, fill in the Category Custom CSS Selector field. The selected element should have data-product-id or be located inside a product tile that contains .price-box[data-product-id].

Example selectors:

.price-box[data-product-id].product-item-info .price-box[data-product-id].product-item-details .price-box[data-product-id]

The Product Page Custom CSS Selector field applies only to the product page. Enter the selector of the element after which the countdown should be added.

Examples:

.product-info-main .product-info-price#custom-price-target

If the field is empty, the module uses the default selector:

.product-info-main .price-box

Text and time format settings

The Text Before Countdown field sets the text before the countdown, for example:

Promocja kończy się za:

If the field is empty, the label before the countdown is not displayed and the countdown value itself is centered.

The Text Before End Date field sets the text before the promotion end date, for example:

Promocja do:

If the field is empty, only the date is displayed under the countdown.

The Displayed Time Template field lets you select the range of time units shown in the countdown.

Available templates:

• 00d 00g 00m 00s,
• 00d 00g 00m,
• 00d 00g,
• 00d,
• 00g 00m 00s,
• 00m 00s.

Time unit symbols can be changed using separate fields:

• Days Symbol, default d,
• Hours Symbol, default g,
• Minutes Symbol, default m,
• Seconds Symbol, default s.

Example: if you set Hours Symbol to h, the countdown can display 02d 05h 30m 10s instead of 02d 05g 30m 10s.

Showing the countdown only before the promotion ends

The Show Countdown Days Before End field defines how many days before the promotion ends the countdown should become visible.

Examples:

• empty field - the countdown is displayed as soon as the promotion conditions are met,
• 1 - the countdown appears on the last day of the promotion,
• 3 - the countdown appears during the final 3 days of the promotion,
• 7 - the countdown appears during the final 7 days of the promotion.

The field accepts integers. An empty value means no restriction.

Appearance settings

The module lets you configure the countdown design without code changes.

Available fields:

• Background Color - background color,
• Text Color - base text color,
• Label Color - color of the label before the countdown,
• Timer Color - color of the countdown value,
• Border Color - border color,
• Font Size - font size.

Color fields use a color picker and save hex values, for example:

#ffffff#333333#d32f2f

The font size is selected from a list:

• 12px,
• 14px,
• 16px,
• 18px.

Post-deployment check

After installation and configuration, check:

1. A simple product with an active promotion on the product page.
2. A simple product with an active promotion on the category listing.
3. A product without an active special price.
4. A product with a Special Price To Date date in the past.
5. A product with an empty Special Price To Date.
6. A product with a special price equal to or higher than the regular price.
7. The Show Countdown Days Before End configuration.
8. Different Displayed Time Template templates.
9. Changing time unit symbols.
10. Changing colors and font size after clearing the cache.
11. The browser console to make sure there are no JavaScript errors.
12. The raw HTML source to make sure it does not contain a ready-made .countdown-promotion element.

Known limitations

The module uses promotions based on standard Magento fields:

• special_price,
• special_from_date,
• special_to_date.

Catalog rules, Adobe Commerce Scheduled Updates, and configurable product variants with completely independent promotion dates may require a separate integration.

Themes that significantly change price rendering or the product tile structure may require custom CSS selectors.

Most common issues

The countdown is not visible

Check whether:

• the product has Countdown Promotion = Yes,
• the product has Special Price set,
• the special price is lower than the regular price,
• Special Price To Date is set in the future,
• Special Price From Date does not point to a future date,
• Magento cache has been cleared,
• the CSS selector set for the category points to the correct product element.

The countdown is in the wrong place

Change Category Placement or set a custom Category Custom CSS Selector. On the product page, use Product Page Custom CSS Selector.

Appearance changes are not visible

Clear the Magento cache:

bin/magento cache:flush

In production, refreshing static assets according to the store's deployment process may also be required.