Promotions

What is a promotion?

A promotion is a rule that automatically gives customers a better price when their cart meets certain conditions. Examples:

• "Buy 2 cans of soda, get 1 free" - a BOGO promotion, available now.
• "20% off everything between 4 PM and 6 PM on weekdays" - coming soon.
• "Burger + fries + drink for a fixed price" - coming soon.
• "Buy 5 or more shirts, get 15% off each" - coming soon.
• "$10 off any cart over $50, all month" - coming soon.

BOGO is live now. See BOGO Promotions for a full guide. The remaining four types arrive in follow-on updates.

How the smart resolver works

The single most important behaviour: customers always get the best available deal, and discounts never stack by accident.

Imagine a VIP customer who has a 10% standing loyalty discount on her account. She shops during a BOGO promotion that saves her more than 10%. The system picks whichever option saves her more money - it does not add them together. Her standing discount is skipped for that transaction. Next time she shops without any active promotion, her 10% loyalty discount applies as normal.

TIP

This is automatic. The cashier does not pick. The customer does not pick. The system always picks the option that saves the most money.

If you want two promotions to add up (for example, "BOGO and a clearance promo can combine"), toggle the Stackable option on both when creating them. Stackable promotions add up; non-stackable promotions never combine, even with each other.

Enabling the promotions module

The promotions module is off by default. To switch it on:

1. Go to Settings.
2. Find the Promotions section and toggle Promotions enabled on. The change saves instantly.

Once enabled, the Promotions page appears in the sidebar and the POS begins evaluating active promotions on every cart change. When disabled, the POS skips all promotion resolution - manual cashier discounts still work as normal, and existing promotion records are preserved.

Creating a promotion

1. Go to Promotions > + New Promotion.
2. Pick the promotion type. BOGO is available now. The other types show a "Coming soon" badge until they ship.
3. Fill in the type-specific options on the next step. See BOGO Promotions for step-by-step BOGO instructions.
4. On the final step, set:
   • Exclusions - products, categories, or specific variants the promotion should not apply to. For example, exclude tobacco from a "20% off everything" sale, or exclude the large-size variant of a product from a BOGO.
   • Stackable - whether this promotion can combine with other stackable promotions. Default is off. Leave it off unless you have a specific reason.
   • Priority - a tiebreaker. If two promotions save exactly the same amount, the one with higher priority wins.
   • Preview - try it against a sample cart before activating. The preview shows exactly what would apply.
5. Save as Draft. Click Activate when you are ready to switch it on. The POS picks it up within seconds.

Pausing, expiring, and deleting

Action	What it does
Pause	Temporarily stops a promotion without losing its setup. The discount stops immediately. Click Activate again to resume.
Expire	Happens automatically when the promotion's end date passes. Expired promotions move to the Expired tab. Click any expired card to view its full configuration in read-only mode.
Delete	Only possible for promotions that have never been applied to a sale. Once a promotion has been used even once, you can only pause it - the history is preserved for your reports.

How promotions appear at the POS

When a promotion applies, the cart area shows two things:

1. Line badge - a small green tag appears next to each cart line that received a discount, showing the promotion name. The exact saving on that line is visible on hover.
2. Promotions panel (just above the cart total) - lists every applied promotion with the saving amount in green.

The panel also surfaces hints for promotions that are close but not yet applying:

• Indigo hint: a BOGO whose trigger items are in the cart but the reward item is missing. For example: "Soda BOGO: Add the free item to complete this offer." Adding the item immediately applies the deal.
• Amber hint: a promotion the customer almost qualifies for, such as a loyalty-members-only deal or a minimum basket not yet reached. Attaching a loyalty customer or adding more items to the cart may unlock it.
• Grey: a promotion that was evaluated and beaten by a better discount.

INFO

Some skipped reasons (for example, no matching items in the cart at all) are not shown in the panel since there is nothing actionable to display.

The receipt prints a "Promotions" line showing the combined saving (for example, "Promotions: -2.50"), replacing the standard "Discount" line when promotions are active.

Cashier Promo Sheet

Cashiers can tap the Megaphone button in the POS header to open the Active Promotions sheet. This shows every currently running promotion with its type, deal description (for example, "Buy 2 Coca-Cola → Get 1 Coca-Cola free" for BOGOs), schedule (days and time window), minimum spend, and any loyalty-only restrictions. Cashiers use it to tell customers about deals before scanning items.

Excluding products from promotions

To exclude a whole product from every promotion - edit the product and toggle Promotion eligible off. That product is excluded from every promotion automatically, regardless of what promotions are running.

To exclude a product from one specific promotion - on the promotion's final wizard step, add the product (or its whole category) to the Product exclusions or Category exclusions list.

To exclude a specific variant - on the final wizard step, expand the product row in the exclusions picker and check the individual variant you want to exclude. The other variants of the same product still participate.

Offline behaviour

WARNING

Promotions are evaluated by the server. When the POS is offline, the cart total reflects the price without automatic promotion discounts - the manual discount field still works as normal. When queued offline sales sync back online, the server applies whatever promotions are valid at the time of sync. If a promotion expired while you were offline, that sale syncs at the un-discounted price.

---

FAQ

Q: I created a promotion but it is not applying at the POS. Why?

A: Check four things:

1. Is the status Active, not Draft or Paused?
2. Is today inside the promotion's start and end date?
3. If the promotion is restricted to certain days or hours, are you currently inside that window?
4. Does the cart meet the minimum basket amount, and are the products not on the exclusion list or marked "Promotion eligible: off"?

The promotions panel above the cart total surfaces actionable hints - look there for clues.

Q: A VIP customer has a 10% loyalty discount. A running promotion saves her more. Does she get both?

A: No. The system picks whichever saves her more. The standing loyalty discount is skipped on that transaction. There is no double-discount - this is by design to protect your margin while always giving the customer the best price.

Q: Can two promotions add up?

A: Only if both are marked Stackable. By default every promotion is non-stackable. Stackable promotions add together; non-stackable promotions never combine. Turn stackable on only when you specifically want them to.

Q: The cashier entered a manual 20% discount, but the system applied a 10% promotion instead. Why?

A: The server compares the manual discount against running promotions. If 20% manual is bigger, the manual amount wins. If the cashier entered less than the running promotion, the promotion wins - the customer is never short-changed.

Q: I want to exclude tobacco from a "20% off everything" sale. How?

A: On the promotion's final wizard step, add the tobacco category to the Category exclusions list. The promotion applies to everything else automatically. Alternatively, toggle Promotion eligible off on each tobacco product to exclude it from every promotion permanently.

Q: Can I exclude just one size or variant of a product, not the whole product?

A: Yes. On the promotion's final wizard step, expand the product row in the exclusions picker - each variant is listed separately. Check only the variant you want to exclude. The other variants of the same product still participate.

Q: I deleted a promotion and now the savings are gone from my reports. Was that a mistake?

A: No. You can only delete promotions that have never been applied to a sale. Once a promotion has been redeemed, the system blocks deletion and offers Pause instead. Your reports always tell a true story.

Q: Does the promotion turn on automatically at the right time of day?

A: Yes. The resolver checks the day of week and time of day every time the cart changes. At the scheduled start time, the next cart change re-runs the resolver and the promotion applies. No need to log in or refresh.

Q: Does this work with the per-customer loyalty discount?

A: Yes. They compete automatically. The standing loyalty discount is treated as a candidate. If a running promotion saves more, the promotion wins. If the standing discount saves more, it wins. The customer always gets the better of the two; you never accidentally double-discount.

Q: Where can I see how much each promotion has saved overall?

A: On the Promotions page, each promotion card shows "Discount given" - the total amount discounted across all sales since the promotion was created.

Q: The Promotions page does not appear in my sidebar. What's wrong?

A: The module is disabled by default. Go to Settings, find the Promotions section, and toggle Promotions enabled on. The page and POS resolution activate immediately after saving.

Q: What is the Cashier Promo Sheet?

A: It is a quick-reference dialog opened from the Megaphone button in the POS header. It lists every currently active promotion with its type, deal preview, schedule, and any restrictions. Cashiers use it to tell customers about deals before scanning items.

Q: Can a manager see or manage promotions?

A: Managers do not see the Promotions admin page or sidebar link, but the POS applies promotions to their sales automatically. Only admins (and SUPER_ADMINs) can create, edit, activate, or pause promotions.

Q: The promotions panel shows an amber hint about a loyalty promotion. What does that mean?

A: An amber hint means a promotion is running that the customer almost qualifies for but does not quite meet the conditions - for example, a loyalty-members-only deal with no loyalty customer attached, or a minimum basket threshold not yet reached. Attaching a loyalty customer or adding more items to the cart may unlock it.