Promo bars

A promo bar is a site-wide banner pinned to the top of every storefront page. Use it to surface a discount code, a free-shipping threshold, or a limited-time message. Active bars are served to your storefront by a small embed script, can be scheduled with start and end times, and can be geo-filtered so the right shoppers see the right offer. Shoppers can dismiss a bar for the session.

Where it lives

Dashboard → Promo bars. The page gives you the embed snippet, a composer with a live preview, and a list of your saved bars (up to 50, newest first). The storefront shows one bar at a time: the most recently scheduled active bar whose schedule and geo-targeting match the shopper.

Launching your first bar

Install the embed script (below) once in your theme layout - it does nothing until a bar is active, so it’s safe to add ahead of time.
Create a bar with a Name and a headline or a free-shipping threshold. The live preview shows exactly what shoppers will see as you type.
Optionally set a schedule and country codes, then save with Active on. The bar appears on the next storefront page load - no theme redeploy needed.
When the campaign ends, let the ends at time retire it automatically, or hit Pause. Scheduling the handoff beats toggling bars by hand at midnight.

Installing the embed

Add one script tag to your theme’s layout. It carries your store id and widget key and pulls the active bar at page load:

<script
  src="https://app.zubbyai.com/api/v1/widget/promo/embed.js"
  data-store-id="<your store id>"
  data-widget-key="<your widget key>"
  async defer
></script>

The exact snippet - with your store id pre-filled - is shown on the page under Embed instructions; use its configured app host if different from this example. The WooCommerce plugin enqueues the script when its promo-bar setting is enabled. Shopify has a separate Promo Bar theme app embed that must be enabled. Custom storefronts install the generated snippet manually. Check the page source or Network panel for this script before adding a second copy; see widget embed codes.

Verify the real storefront

A preview is a mockup, not a launch check. Save a meaningful headline or a true free-shipping threshold; Name alone can save a bar without useful shopper copy. Confirm the code and offer conditions in the commerce platform, because a banner does not create or enforce them. Use a controlled page load to check the script request, the active promo response, the selected bar, and its close button. Test a narrow phone layout for header overlap, keyboard focus, dismissal, and visible layout movement. Dismissal lasts for the tab session; use a fresh session for the next test.

Test both inside and outside the schedule and country list. A country-restricted bar is not served when country cannot be resolved. If no bar appears, check Active, start/end times, country eligibility, the widget key, and a previous session dismissal before reinstalling. The page requires recovery access. A real countdown should describe the configured end time, not imply stock reservation or a price hold.

Fields

Field	Required	What it does
Name	Yes	Internal label for the bar - not shown to shoppers.
Headline	No	The banner copy shoppers read.
Code	No	A discount code rendered as a pill next to the headline.
Starts at	No	ISO datetime the bar begins showing, e.g. `2026-06-01T00:00:00Z`.
Ends at	No	ISO datetime the bar stops showing.
Free shipping threshold	No	An order value above which shipping is free.
Country codes	No	ISO 2-letter codes (e.g. `US,CA,GB`) - restrict display by shopper geo.
Active	-	On/off switch; only active bars are served.

Only Name is required to save. If you leave the headline empty but set a free-shipping threshold, the bar falls back to a “Free shipping on orders over $X” message.

Live preview while you edit

The composer renders the bar exactly as shoppers will see it - headline, code pill, geo tags, and a paused state - above a mock store header. It updates as you type, so you can dial in the copy before saving.

Scheduling

Start and end times are ISO datetimes (UTC recommended, with a Z suffix). A bar with a future starts at stays hidden until then; one past its ends at stops showing. Leave both empty for an evergreen bar that runs while it’s active. You can also flip a bar on or off instantly with the Pause / Activate button regardless of its schedule.

Geo-targeting

Set one or more country codes to show a bar only to shoppers in those countries - useful for region-specific shipping offers or currency-specific codes. Codes are uppercased automatically. Leave the field empty to show the bar everywhere. The saved-bar row displays the active country codes as a badge so you can see targeting at a glance.

Multiple active bars

Only one bar is served per page load - the active bar with the most recent start date that matches the shopper’s country. If two campaigns overlap, the newer-scheduled one silently wins, which can make the other look “broken.” Use scheduling to hand off cleanly between campaigns rather than keeping several active at once.

Managing saved bars

Each saved bar shows its status badge, name, code, geo badge, schedule window, and headline, with Edit, Pause/Activate, and Delete actions. Edits save in place; changes propagate to the storefront on the next page load.

Gotchas

The embed script needs both data-store-id and a valid data-widget-key. A missing or wrong key means no bar renders - the same key that authorizes the chat widget.
Country codes must be ISO 2-letter (US, not USA or United States). Geo resolution reads the country header set by the CDN (Vercel or Cloudflare); a geo-targeted bar is hidden when the shopper’s country can’t be resolved.
Dismissal is per session - a shopper who closes the bar sees it again on a fresh session.
Datetimes are parsed as ISO; if a schedule isn’t taking effect, check the format and the timezone suffix.

Widget embed codes - where the storefront script lives.
Audience rules - target storefront experiences by cohort.
Cart & browse rescue - pair an on-site bar with off-site recovery.
Broadcasts - push the same promo to a segment by email or SMS.