PPS Countdown Timer: settings reference

Updated November 10, 2026

Select a timer source in WooCommerce > Countdown Timer and configure its deadline before enabling product-page output.

Release in preparation. This reference is not confirmation of download or Pro purchase availability.

Choose a real WooCommerce sale end date or a visitor timer. A countdown display does not, by itself, change a product price or make an evergreen offer expire on the server.

Where to configure it

WooCommerce > Countdown Timer. The menu and save handler require manage_woocommerce. Use Save Changes after editing.

Initial form values and unsaved runtime values can differ. The tables distinguish them instead of treating an unchecked form as an enabled setting. For checkbox groups, choose each method/day/location you want before the first save.

General

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Enable (enabled) Form: blank; runtime: unchecked On/off. Unchecked saves false. Free Show countdown timers on product pages.
Timer source (timer_type) sale_dates sale_dates = WooCommerce sale end date; fixed = Fixed date campaign; evergreen = Visitor-local timer (Pro). Invalid input uses sale_dates. Sale/fixed Free; evergreen requires entitled Pro Sale mode needs the product's actual scheduled sale end. Stored evergreen falls back to sale_dates in Free.
Campaign end date (fixed_datetime) blank Exact YYYY-MM-DD HH:MM:SS text; markup stripped on save. The strict site-local parser uses DateTimeImmutable with wp_timezone(), not PHP-default timezone parsing. Free Used in fixed mode. Relative dates, invalid calendar dates and nonexistent DST wall times are rejected. Ambiguous fall-back times use PHP's choice in the explicit site zone. An invalid global date supplies no fixed deadline.
Evergreen hours (evergreen_hours) 0 Number; min 0; max 168; UI step 1. Save casts to float and clamps; blank uses 0. Runtime uses whole hours. Entitled Pro; save skipped without approval Combined with minutes for a visitor-local deadline. It is not a WooCommerce sale end or price guarantee.
Evergreen minutes (evergreen_minutes) 15 Number; min 0; max 59; UI step 1. Save casts to float and clamps; blank uses 15. Runtime uses whole minutes. Entitled Pro; save skipped without approval Combined with hours; a zero total duration cannot start a future visitor deadline.
Message above the timer (pre_timer_msg) Hurry! Sale ends in: Text; stripped of markup on save. Free Sets message above the timer for this section. See the behavior notes for its conditions.

Appearance

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Layout (timer_layout_style) blocks blocks = Number blocks; inline = Inline text. Invalid input uses blocks. Free Sets layout for this section. See the behavior notes for its conditions.
Background (bg_color) #fef3ee Hex color (#RGB or #RRGGBB). Invalid/blank saves #fef3ee. Free Sets background in this section; it does not change other plugin colors.
Text color (text_color) #de3318 Hex color (#RGB or #RRGGBB). Invalid/blank saves #de3318. Free Sets text color in this section; it does not change other plugin colors.
Days label (label_days) Days Text; stripped of markup on save. Free Sets days label for this section. See the behavior notes for its conditions.
Hours label (label_hours) Hours Text; stripped of markup on save. Free Sets hours label for this section. See the behavior notes for its conditions.
Minutes label (label_minutes) Min Text; stripped of markup on save. Free Sets minutes label for this section. See the behavior notes for its conditions.
Seconds label (label_seconds) Sec Text; stripped of markup on save. Free Sets seconds label for this section. See the behavior notes for its conditions.

Placement and expiry (Pro)

Field Initial form / unsaved runtime Allowed input and save fallback Access Effect
Position on the product page (position) below_atc below_atc = Below the add to cart form; above_atc = Above the add to cart form; below_gallery = Below the product gallery. Invalid input uses below_atc. Pro field; save skipped without Pro Sets position on the product page for this section. See the behavior notes for its conditions.
Timers on category pages (show_on_archives) Form: blank; runtime: unchecked On/off. Unchecked saves false. Pro field; save skipped without Pro Show a mini timer on shop and category grids.
When the timer hits zero (action_on_expiry) hide_timer hide_timer = Hide the timer; show_message = Show the expiry message. Invalid input uses hide_timer. Pro field; save skipped without Pro Sets when the timer hits zero for this section. See the behavior notes for its conditions.
Expiry message (expiry_message) Sale ended. Text; stripped of markup on save. Pro field; save skipped without Pro Sets expiry message for this section. See the behavior notes for its conditions.
Custom CSS (custom_css) blank Semicolon-separated property declarations; text sanitation on save. Each output declaration is independently checked against a property allowlist and conservative literal-value syntax. Entitled Pro; save skipped without approval Scoped to the timer. Escapes, comments, quotes, URLs/resource functions, var indirection and selector/scope syntax are rejected. Only the supported visual functions described below are retained.

Design (Pro)

These text inputs appear in the licensed settings form, not a separate design editor. Defaults below apply when no design value is stored. Length values accept nonnegative numbers with optional px, em, rem or percent units; numeric lengths gain px at output. Invalid values save blank. Use unitless values for font weight and line height even though the common text validator accepts length suffixes. Browser CSS interpretation still applies. Mini archive styling fixes its own padding and margins.

Field Default and accepted input Effect
Use Theme Styles (design_use_theme_styles) Unchecked; on/off Suppresses individual design variables and adds theme-inherit styling.
Font Family (design_font_family) inherit; inherit, serif, sans-serif, monospace or system-ui Timer wrapper font family.
Font Size (design_font_size) Blank; length Wrapper font size; blank falls back to inherit.
Font Weight (design_font_weight) Blank; nonnegative number Wrapper weight; blank falls back to inherit.
Line Height (design_line_height) Blank; nonnegative number Wrapper line height; blank falls back to inherit.
Text Color (design_text_color) Blank; #RGB or #RRGGBB Overrides the basic Text color.
Bg Color (design_bg_color) Blank; #RGB or #RRGGBB Overrides the basic Background.
Padding Top (design_padding_top) Blank; length; fallback 12px Wrapper top padding.
Padding Right (design_padding_right) Blank; length; fallback 20px Wrapper right padding.
Padding Bottom (design_padding_bottom) Blank; length; fallback 12px Wrapper bottom padding.
Padding Left (design_padding_left) Blank; length; fallback 20px Wrapper left padding.
Margin Top (design_margin_top) Blank; length; fallback 12px Wrapper top margin.
Margin Right (design_margin_right) Blank; length; fallback 0 Wrapper right margin.
Margin Bottom (design_margin_bottom) Blank; length; fallback 12px Wrapper bottom margin.
Margin Left (design_margin_left) Blank; length; fallback 0 Wrapper left margin.
Border Radius (design_border_radius) Blank; length; fallback 10px Wrapper corner radius.
Border Color (design_border_color) Blank; #RGB or #RRGGBB; fallback transparent Wrapper border color.
Border Width (design_border_width) Blank; length; fallback 0 Wrapper border width.
Border Style (design_border_style) Blank; none, solid, dashed, dotted or double; fallback solid Wrapper border style.
Icon Size (design_icon_size) Blank; length Stored variable only; the current timer has no corresponding rendered icon-size consumer. Do not rely on a visible effect.
Icon Height (design_icon_height) Blank; length Stored variable only; no current rendered icon-height consumer.
Icon Gap (design_icon_gap) Blank; length Stored variable only; no current rendered icon-gap consumer.

Additional product controls

Field Location Format and initial value Access Behavior
Disable timer (_pps_cdt_disable) Products > Edit product > Product data > Advanced checkbox, unchecked Pro Hides the product timer while Pro is active.
End date override (_pps_cdt_fixed_datetime) Products > Edit product > Product data > Advanced Blank; exact site-local YYYY-MM-DD HH:MM:SS Entitled Pro A valid date overrides fixed, sale and visitor-local sources. Blank/invalid submission deletes the override and marker. Invalid previously retained metadata leaves the global deadline/source intact.

Behavior and edition boundaries

Free renders sale/fixed deadlines below the add-to-cart form, with text labels/colors/layout. Pro owns visitor-local timing, alternate placement, archive timers, expiry messages, design/CSS, product controls and [pps_countdown_timer product_id="123"]. The shortcode requires an enabled module, current paid approval and an existing positive product ID; the default 0 returns nothing. It uses the same renderer and deadline selection as the product placement.

A valid product end date wins over every global source unless the product timer is explicitly disabled. Invalid retained overrides do not erase a valid global fixed/sale deadline. Site-local fixed and product values use the explicit WordPress timezone parser. A fall-back DST time can be ambiguous; confirm the intended absolute deadline rather than assuming which repeated hour was chosen.

Visitor-local mode stores one deadline per product in browser localStorage. It reuses expired values without restarting; malformed saved values or unavailable storage fail closed rather than minting a new deadline. Clearing browser storage permits a new assignment. This display neither reserves a price nor changes a WooCommerce sale's server end. Default placement returns to the Free position after paid denial; paid callbacks recheck approval.

Custom CSS supports only bounded literal declarations and rgb/rgba/hsl/hsla, calc/min/max/clamp, and plain/repeating linear/radial gradient functions. It is not a general CSS parser; previously saved quotes, escapes, resources or indirection can now be dropped. The three icon design inputs are retained controls without a visible current consumer, not advertised timer features.

Pro field access depends on the add-on and its licensing gate. Freemius account or license screens are separate from frontend rendering; opening an account page does not establish that a feature rendered.

Troubleshooting

A sale timer stays hidden without a scheduled future sale end. Fixed dates must use the exact site-local format and a valid calendar/DST wall time. Check the product disable field, valid override precedence and current Pro approval before changing the global source. For a visitor timer, inspect its existing per-product browser deadline: reloading does not reset expired or malformed storage. Test the intended deadline, cache and placement with your theme before live use.

Disable or roll back safely

Record the current values before changing them. Clear Enable and save to stop new module output/actions. Revert one setting at a time. Deactivation is not an undo of cart changes, sent messages, created orders or saved records. Avoid uninstalling as a rollback, since uninstall may remove data. Back up the database before a data-changing rollback.

Services and data

The frontend script keeps the evergreen deadline in browser local storage. Sale and fixed deadlines come from product/settings data.

Account, licensing and updater traffic must be reviewed separately. This reference does not claim that all data stays local or that a service connection has been tested.

Related documentation

Setup: https://propluginstack.com/docs/countdown-timer-setup-reference/

Changelog: https://propluginstack.com/changelog/countdown-timer-source-changelog/