> For the complete documentation index, see [llms.txt](https://docs.samita.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samita.io/samita-countdown-timer-bar/reference/how-it-works.md).

# How it works

A plain-language look at what actually happens when a shopper loads a page with a countdown on it.

You don't need any of this to use the app — [turning on the app embed](/samita-countdown-timer-bar/quick-start/enable-app-embed.md) is the whole setup. But if you're wondering why a countdown behaves the way it does, or reasoning about a problem, this is what's going on underneath.

## The app embed runs on every storefront page

Countdown Timer Bar Samita reaches your storefront through a Shopify theme app extension embed, listed in your theme editor as **Samita Countdown Timer Bar**. Once it's on for a theme, a small script from the app runs on every page a shopper loads on that theme.

On most page views it has nothing to do. Its first job is to work out whether anything you've configured applies to this page, and for most pages on most stores the answer is no, so it gets out of the way.

Because the countdowns live in the app rather than in your theme, changes you save show up on the storefront without republishing the theme.

## What it knows about the page

Alongside your countdown settings, the embed picks up a few things from the page itself as Shopify renders it:

* **The page type** — product page, collection, cart, blog, and so on. This is what a **Page** condition matches against.
* **The storefront language** the shopper is browsing in, which drives both the **Language** condition and [translated text](/samita-countdown-timer-bar/design-and-translation/translate.md).
* **The signed-in customer**, if there is one, including their tags. This is what **Customer** and **Customer tag** conditions read.
* **The product** being viewed, on a product page.

This all comes from the page the shopper already loaded, which is why customer and language conditions resolve immediately.

## Finding somewhere to render

There are two ways a countdown gets a place on the page.

**Automatic, on product pages.** If **Product page** is ticked, the script looks for the theme's Add to cart area and inserts the countdown just below it. It recognises the patterns used by a long list of themes — but a heavily customised theme can defeat it, and then nothing renders. That's the usual reason automatic placement fails.

**Shortcode blocks.** A `<div class="samita-countdown" ...>` placed through a **Samita Countdown** app block is already on the page, so the script simply fills it. This works regardless of theme, which is why it's the reliable fallback.

**Cart countdowns** place themselves at the top of the cart form, on the cart page and in the cart drawer, when the cart has items. **Sale popups** are added to the page and floated at the position you set.

## Deciding whether to show

For each countdown that could apply, the app checks its conditions against what it knows about the page, the product, and the shopper. Most conditions are answered on the spot.

Two need to look something up:

* **Collections** — the app can't see a product's collections from the page alone, so it fetches them using the template file described in [Enable the Collection condition](/samita-countdown-timer-bar/where-countdowns-appear/collection-search-file.md). Without that file the condition can't be answered, so it matches nothing.
* **Country** — determined by looking up the shopper's IP address, not read from their account. A VPN or proxy changes the result.

## Working out the time

The remaining time is calculated in the shopper's browser, by comparing your settings against their device clock. There's no server tick.

That's what makes the app light on your page, and it has three consequences worth knowing:

* A shopper whose device clock is badly wrong sees a wrong timer.
* A **Daily recurring timer**'s window is evaluated against their local clock, so "9 am to 11 am" means 9 am where they are.
* A **Countdown to a date** timer counts to the moment you set, which every shopper sees as their own correct remaining time.

## Remembering a Fixed minutes timer

A **Fixed minutes** timer has to survive page changes, so the first time a shopper sees it the app writes their personal end time into a cookie in their browser. On later page views it reads that cookie back and continues.

Hence: per browser and per device, lost when cookies are cleared, and reset for everyone if you change the configured number of minutes.

## What the app doesn't do

* **It doesn't change your products.** No prices, no inventory, no availability. A timer hitting zero removes the timer, nothing else.
* **It doesn't reserve stock.** A cart countdown is a prompt, not a hold.
* **It doesn't edit your theme's templates.** Turning on the embed adds the app's script; app blocks are added and removed in the theme editor like any other block. The one exception is the optional template file for collection conditions, which you add yourself.

## Next steps

* [Permissions and data](/samita-countdown-timer-bar/reference/permissions-and-data.md)
* [How countdowns work](/samita-countdown-timer-bar/quick-start/how-countdowns-work.md)
* [Countdown not showing](/samita-countdown-timer-bar/help/countdown-not-showing.md)
* [Display overview](/samita-countdown-timer-bar/where-countdowns-appear/overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.samita.io/samita-countdown-timer-bar/reference/how-it-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.