Countdown Timer Methods

SmartCart.formatCountdownTime ⇒ string¶

Formats a remaining time as m:ss, or h:mm:ss from one hour. Partial seconds round up, and negative or invalid input formats as 0:00.

Returns: string - The formatted time

Example

SmartCart.formatCountdownTime(285000); // "4:45"
SmartCart.formatCountdownTime(3661000); // "1:01:01"

SmartCart.getCountdownTimerComponent ⇒ object | null¶

Gets the Countdown Timer component from SmartCart.settings.components (single-use: the first one wins)

Returns: object | null - The component, or null when the cart has none

Example

const component = SmartCart.getCountdownTimerComponent();

console.log(component?.settings.duration_minutes); // 5

SmartCart.getCountdownTimerSettings ⇒ object¶

Gets the Countdown Timer settings, normalized: whole minutes and seconds folded into one durationMs, an action that is always none, hide, restart, clear_cart or checkout, a startTrigger that is always first_item, page_load or drawer_open, the showProgressBar flag, the rich title and expiredText strings and the theme object (colors).

Returns: object - { action, durationMs, expiredText, showProgressBar, startTrigger, theme, title }

Example

const { action, durationMs } = SmartCart.getCountdownTimerSettings();

console.log(action, durationMs); // "checkout" 300000

SmartCart.getCountdownTimerDurationMs ⇒ number¶

Gets the configured countdown duration in milliseconds (0 when the timer is not configured)

Returns: number - The duration

SmartCart.isCountdownTimerEnabled ⇒ boolean¶

Checks whether the cart has a visible Countdown Timer component with a positive duration

Returns: boolean - Whether the timer is enabled

SmartCart.isCountdownTimerExpired ⇒ boolean¶

Checks whether the countdown has reached zero: the expired state lasts until the clock resets (cart emptied, new session) or restarts

Returns: boolean - Whether the countdown has ended

SmartCart.isCountdownTimerProgressBarEnabled ⇒ boolean¶

Checks whether the depleting progress line under the text renders: the merchant setting (on by default), and only while the clock is running

Returns: boolean - Whether the progress line renders

SmartCart.isCountdownTimerVisible ⇒ boolean¶

Checks whether the Countdown Timer should render: an enabled component whose clock has started, items in the cart for the first_item and drawer_open triggers (page_load renders even with an empty cart), and once expired only for the none action, which shows the expired text. In the admin preview it always renders.

Returns: boolean - Whether the timer is visible

Example

document.addEventListener('rebuy:smartcart.show', () => {
  if (SmartCart.isCountdownTimerVisible()) {
    console.log(`Time left: ${SmartCart.getCountdownTimerTimeRemaining()}`);
  }
});

SmartCart.getCountdownTimerRemainingMs ⇒ number¶

Gets the time left on the countdown in milliseconds (the full duration before the clock starts, 0 once it has expired)

Returns: number - The remaining time

SmartCart.getCountdownTimerTimeRemaining ⇒ string¶

Gets the time left on the countdown, formatted for display (ie. 4:45)

Returns: string - The formatted remaining time

SmartCart.getCountdownTimerProgress ⇒ number¶

Gets the countdown progress as a fraction of the configured duration (1 just started, 0 done)

Returns: number - The progress, between 0 and 1

SmartCart.getCountdownTimerProgressPercent ⇒ string¶

Gets the countdown progress as a CSS percentage, used for the width of the progress line (ie. 95.00%)

Returns: string - The progress percentage

SmartCart.getCountdownTimerText ⇒ string¶

Gets the text the component shows. While the clock runs: the merchant's title with {{time_remaining}} replaced by the live countdown, wrapped in <span class="rebuy-cart__countdown-timer-time"> (a blank title renders the countdown alone; a title without the placeholder gets the countdown appended). Once expired: the merchant's expired text with the placeholder at 0:00, or the title at 0:00 when no expired text is set. The result is sanitized HTML.

Returns: string - Sanitized HTML for the timer text

Example

SmartCart.getCountdownTimerText();
// '<p>Your cart items are only available for <span class="rebuy-cart__countdown-timer-time">4:45</span></p>'

SmartCart.getCountdownTimerStatusText ⇒ string¶

Gets the plain-text announcement for the visually hidden status region: the expired text (placeholder at 0:00) once the countdown reaches zero, an empty string while the clock runs (the ticking digits are deliberately not announced)

Returns: string - The announcement text

SmartCart.getCountdownTimerStyle ⇒ object¶

Gets the inline style for the component root: the merchant's theme colors as the CSS custom properties --rebuy-countdown-timer-bg, --rebuy-countdown-timer-text and --rebuy-countdown-timer-progress. Unset colors fall through to the stylesheet defaults (the progress line to the text color).

Returns: object - The style object bound to the component root

Example

SmartCart.getCountdownTimerStyle();
// { '--rebuy-countdown-timer-bg': '#f4f4f4', '--rebuy-countdown-timer-text': '#434343' }

SmartCart.syncCountdownTimer ⇒ void¶

Starts, keeps or resets the countdown. Smart Cart calls it on mount, after every cart change and when the drawer opens. first_item: the clock starts when the cart goes from empty to non-empty. drawer_open: it starts the first time the drawer opens with items in the cart. Both continue from the persisted deadline of the same cart token and duration, and reset when the cart is emptied or the token changes. page_load: the clock starts on the first page view, continues for that tab's session regardless of the cart, and restarts only in a new tab session or on a changed duration. A deadline whose handling already ran on an earlier page, or in another tab, is settled as expired without firing the callback again.

Example

// Re-evaluate the clock after changing the cart outside of Rebuy's cart methods
SmartCart.syncCountdownTimer();

SmartCart.tickCountdownTimer ⇒ void¶

Advances the countdown by reading the clock: updates the remaining time and fires the end-of-timer handling once the deadline has passed. Smart Cart runs it once a second while the clock is running.

SmartCart.handleCountdownTimerExpiry ⇒ void¶

Runs the end-of-timer handling once per deadline: claims the deadline in the stored record (another tab that already claimed it settles silently), fires the merchant callback, then the configured action (none keeps the timer with the expired text, hide hides it, restart starts a new countdown, clear_cart empties the Shopify cart while it has items, checkout runs SmartCart.checkout() only while the drawer is open with items, with every gate the checkout button has). The admin preview never acts; it shows the expired text for a moment and restarts the clock instead.

SmartCart.initCountdownTimer ⇒ void¶

Initializes the Countdown Timer once the cart template is mounted (Smart Cart calls this during initialization)

SmartCart.resetCountdownTimer ⇒ void¶

Stops the clock and clears the runtime state. The persisted deadline is kept, so a re-initialization continues the same countdown.

Example

// Stop the clock for the rest of this page view (the deadline resumes on the next page load)
SmartCart.resetCountdownTimer();