How Gatemi Countdown Works

Three rules govern the plugin.

The deadline is decided on the server

A countdown worked out in the browser from a date string and the visitor's timezone says something different on every laptop. Here the end of a campaign is decided on your site and sent as one absolute moment — a UTC timestamp in the data-gmcd-ends attribute. The Ends at you type is read in your store's timezone and stored as that timestamp, so changing the store's timezone later does not move a deadline you already set.

On each page the plugin:

  1. Finds the campaign for this product and placement (free: the first published fixed-date, store-wide campaign; Full edition: the first published campaign, in menu order, whose Covers includes the product and which has a deadline).
  2. Works out the deadline.
  3. If the deadline has passed and the campaign says take it off the page, prints nothing — so a shopper never sees a clock flash and vanish.
  4. Otherwise prints the headline and the digits — days (only when there are any, unless Always show the days column is on), hours, minutes, seconds — already filled in. The page is right before any script runs.
  5. Loads its small stylesheet and script in the footer — only if a countdown was printed. A page with no countdown loads neither.

The script first asks your site what time it is — one HEAD request for wp-includes/images/blank.gif, sent with cache: 'no-store' and no cookies — and reads the response's Date header. It then ticks the digits once a second against that corrected clock, so a visitor whose computer clock is wrong still sees the right time left; the server-rendered digits stand until the clock is known. If the request fails or takes more than two seconds, the visitor's own clock is used. Either way they cannot change the deadline itself: when it has passed, your site stops showing the countdown however their clock is set. At zero the script does what the campaign says — removes the countdown, or shows the message. Full edition: or leaves it at zero.

Sale-linked campaigns read WooCommerce's own dates — Full edition

A timer showing three hours left on a sale that ended yesterday is the failure this category is judged on, and it happens whenever two dates have to be kept in step by hand. A campaign set to Ends when the product's own sale ends has no date of its own: it reads the product's Sale price dates → To from WooCommerce (get_date_on_sale_to()).

  • No sale running, or a sale with no end date: no countdown. A countdown to nothing is worse than none.
  • The sale's end changes: the countdown changes with it.
  • A variable product holds its sale dates on its variations, not on itself, so the countdown runs to the soonest end among its variations on sale.

Evergreen campaigns live in the visitor's browser — Full edition

An evergreen campaign (Starts when each visitor first sees it) is sent with only its length (data-gmcd-minutes) and a key (c + the campaign id). The first time a visitor's browser sees it, the script writes the start time into a cookie, gmcd_seen, and counts down from there — both on the same corrected clock as a fixed-date campaign, so a wrong computer clock moves neither end. Nothing about the visitor is stored on your server, and the HTML is identical for everybody, which is what keeps a full-page cache safe.

  • With Start again for a visitor whose evergreen countdown has run out ticked, a visitor whose timer has expired gets a fresh one on their next visit. Unticked, it stays expired.
  • The cookie keeps the last 30 campaigns a visitor has met, lasts a year, and is SameSite=Lax (and Secure on HTTPS).
  • A visitor who clears cookies, or uses another browser, starts again. An evergreen timer is a nudge, not a lock.

Which campaign wins — Full edition

For each product and placement, campaigns are read in the order WordPress lists them (menu order, then id) and the first one that covers the product and has a deadline is shown — not the one that ends soonest. A rule you can see is a rule you can debug: to put a campaign first, give it a lower Order in its Page Attributes box; campaigns with the same order are read oldest first.

Covers works like this:

  • Every product — all of them.
  • These categories — any product in one of the category ids, or in a sub-category of one.
  • These products — the product ids listed; a variation counts as its parent.

The cart placement shows the first campaign with On the cart ticked and a deadline of its own (fixed or evergreen).

Where the countdown appears

Placement WooCommerce hook Edition
Product page woocommerce_single_product_summary, priority 25 (under the price) both
Shop and category listings woocommerce_after_shop_loop_item, priority 15 both
Cart woocommerce_before_cart Full edition
Anywhere [gatemi_countdown] shortcode Full edition

These are WooCommerce's classic template hooks. Block themes reach the product page and product listings through WooCommerce's own compatibility layer for its templates; the Cart block does not print woocommerce_before_cart, so the cart placement needs the classic cart page.

Page caches

The clock ticks in the browser, against the time it read from your site's own response headers, so a cached page counts down correctly. What a cache holds is the page around it: the digits printed when it was cached (they jump to the right value the moment the script runs), and, if you change Ends at, the old deadline until the cache is rebuilt. Clear your page cache after changing a campaign.

Shopping Cart
Scroll to Top