Countdown timers create urgency by showing customers how much time remains in your promotion or bonus period.
Prerequisites
- Enable the Giveaway Gator Body Tag in your theme’s App Embeds.
Basic Implementation
Add this HTML element anywhere in your theme:
<div data-gg-countdown-timer></div>Customization Options
Data Attributes:
data-gg-countdown-timer(required) — Initializes the timer.data-template(optional) — Custom display format.- Default:
${days}d ${hours}h ${minutes}m ${seconds}s - Variables:
${days},${hours},${minutes},${seconds},${multiplier},${multiplierX}
- Default:
data-style(optional) — Display style (default:inline).data-gg-end(optional) — Set topromoto count down to the giveaway end. See End time.
Example Templates
<!-- Basic Timer -->
<div data-gg-countdown-timer></div>
<!-- Custom Format -->
<div data-gg-countdown-timer
data-template="${days} Days, ${hours}:${minutes}:${seconds}"></div>
<!-- With Multiplier -->
<div data-gg-countdown-timer
data-template="${multiplierX} Bonus Entries - ${days}d ${hours}h left!"></div>
<!-- Multiplier Only (no ticking countdown) -->
<div data-gg-countdown-timer
data-template="${multiplierX} Bonus Entries"></div>CSS Styling
.gg-countdown-timer {
--gg-timer-bg: #f3f4f6;
--gg-timer-text: #111827;
--gg-timer-font-size: 16px;
--gg-timer-border-radius: 4px;
}Multiplier-Only Display
If your template only uses ${multiplier} or ${multiplierX} — without any time variables (${days}, ${hours}, ${minutes}, ${seconds}) — the timer renders once and stops. It won’t tick every second, since there’s nothing time-based to update.
This is useful when you want to display the current bonus multiplier as a static badge or banner without a countdown. For example:
<div data-gg-countdown-timer
data-template="${multiplierX} Bonus Entries"></div>This shows “50X Bonus Entries” (or whatever the active multiplier is) without any ticking. The value still updates when the page reloads or every 5 minutes during a revalidation cycle.
Behavior Notes
- Starts when the page loads
- Keeps working in the theme editor when you add or remove sections
- Auto-updates every second (unless using a multiplier-only template — see above)
- Revalidates every 5 minutes for accuracy
- Auto-hides when countdown reaches zero
- Shows bonus multipliers when active
- Counts down to the active bonus period when one is running, and to the giveaway end otherwise. See End time
- If multiple promotions are running, shows the site-wide promotion the storefront picks. See Multiple Promotions
End time
By default, the timer counts down to the end of the active bonus period when one is running. If no bonus period is active, it counts down to the giveaway end.
Add data-gg-end="promo" to skip the bonus period and always count down to the giveaway end. This works on a text timer, timer boxes, and the countdown progress bar.
Turn on the Giveaway Gator app embed. If the giveaway has no end date, or that date has already passed, the timer stays hidden.
Text timer
<span data-gg-countdown-timer data-style="inline" data-gg-end="promo" data-template="${days}d ${hours}h ${minutes}m ${seconds}s"></span>Timer boxes
Add four elements with the class gg-timer-value, in this order: days, hours, minutes, seconds.
<div data-gg-timer-boxes data-gg-end="promo">
<span class="gg-timer-value"></span>
<span class="gg-timer-value"></span>
<span class="gg-timer-value"></span>
<span class="gg-timer-value"></span>
</div>Multiple Promotions
If two promotions run at the same time, give them the same multiplier so customers see one clear number.
Promotions limited to specific products do not need to line up. They never set the site-wide multiplier, because they are not site-wide.
The timer shows one promotion.
- Promotions limited to specific products are left out.
- Among site-wide promotions that have a bonus running right now, the one that ends first wins. If two end at the same time, the higher multiplier wins.
- If no site-wide promotion has a bonus running, the site-wide promotion that ends first is shown at 1X. A bonus that starts later counts as no bonus until it starts.
This runs automatically, nothing to set.
Troubleshooting
Timer shows “1X” instead of the correct multiplier:
- Verify your bonus period is currently active (not upcoming or ended). Bonus periods use your promotion’s timezone, so check the start and end times carefully.
- Make sure the bonus period’s dates fall within the promotion’s date range. You can check this on the Bonus Periods page — any bonus period with dates outside the promotion window will show an “Outside promo dates” warning badge.
- If you’re using
${multiplierX}or${multiplier}in your template, the timer needs an active bonus period to display a value other than 1X.
Timer not showing at all:
- Confirm the Giveaway Gator Body Tag is enabled in your theme’s App Embeds.
- Make sure you have an active promotion with a future end date.
- Check that your HTML element has the
data-gg-countdown-timerattribute.
