Installation and configuration guide for Countdown Promotion for Magento 2

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

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

Requirements

Before installation, make sure your store meets the following 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 via Composer

Go to the Magento project root directory.

For a Git repository, add the module repository to the Composer configuration:

composer config --global --auth github-oauth.github.com composer config repositories.kowal-countdown-promotion vcs https://github.com/kowalco/countdown-promotioncomposer require kowal/module-countdown-promotion

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

vendor/kowal/module-countdown-promotion

Enabling the module in Magento

Run the Magento commands from the store root directory:

bin/magento module:enable Kowal_CountdownPromotionbin/magento setup:upgradebin/magento cache:flush

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

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento indexer:reindexbin/magento cache:flush

Product configuration

For each product where the timer 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 timer 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 to a future date.

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

The 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

Timer position settings

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

Available options:

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

When you choose Custom CSS selector, complete the Category Custom CSS Selector field. The selected element should have data-product-id or be located inside the 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 timer 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 timer, for example:

Promocja kończy się za:

If the field is empty, the label before the timer 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 below the timer.

The Displayed Time Template field lets you choose the range of time units shown in the timer.

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 timer may display 02d 05h 30m 10s instead of 02d 05g 30m 10s.

Showing the timer only shortly before the promotion ends

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

Examples:

• empty field - the timer is shown immediately after the promotion conditions are met,
• 1 - the timer will appear on the last day of the promotion,
• 3 - the timer will appear during the last 3 days of the promotion,
• 7 - the timer will appear during the last 7 days of the promotion.

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

Appearance settings

The module lets you configure the timer appearance without code changes.

Available fields:

• Background Color - background color,
• Text Color - base text color,
• Label Color - color of the label before the timer,
• 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 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 for JavaScript errors.
12. The raw HTML source to confirm 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 separate integration.

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

Most common issues

The timer 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 to a future date,
• 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 timer 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.