🏷️ Sell / Billing

Offers & Coupons

Offers & Coupons has two tabs: Coupons for customer-entered discount codes, and Promotions for automatic discount rules that apply themselves at billing with no code to type — both support percentage or flat-amount discounts.

📍 Menu path: Sell / Billing → Offers & Coupons

👤 Who uses it: Roles with Promotions access and the relevant Create/Edit/Delete permission; Advanced plan tier or above

🏷️ Plan tier: advanced+

Overview

Coupons require the customer or cashier to enter a specific code at checkout to unlock the discount; Promotions apply automatically to every qualifying sale without any code.

Both Coupons and Promotions currently let you create Percent or Flat discount types from this screen. Two other types — Buy X Get Y and Bundle Price — appear in the Promotions list as pre-existing, read-only entries; they cannot be created, edited, or toggled from this page, only viewed.

A Promotion's Visibility scope (This branch only / All branches in unit / All branches company) can only be set by an Admin, and only at the moment of creation — it cannot be changed afterwards on edit.

Neither form has a start date — only a single Expires At date. A discount is considered active from the moment it is created until that date (or indefinitely if left blank).

Before You Start

This page requires the Advanced plan tier and the Promotions feature — it is not visible in the sidebar below Advanced.
Creating, editing or deleting requires the corresponding Create/Edit/Delete permission on this page.
Setting a Promotion's Visibility scope additionally requires the Admin role, and only appears while creating a new promotion, not while editing one.

Step-by-Step Guide

1 Create a coupon code

Switch to the Coupons tab and click + New Coupon.
Enter a Code (automatically forced to uppercase, e.g. SUMMER20) and an optional Description.
Choose Type — Percent (%) or Flat ($) — and enter the Value.
Optionally set a Min Order value (default 0), and — for Percent coupons only — a Max Discount cap so a huge cart cannot trigger an unlimited discount.
Optionally set Max Uses (leave blank for unlimited) and an Expires At date, then Save.

2 Create an automatic promotion

Switch to the Promotions tab and click + New Promotion.
Enter a Name (required) and optional Description.
Choose Type — Percent (%) or Flat ($) — and enter the Discount Value (required).
Optionally set Min Order, Max Uses (default unlimited) and Expires At.
If you are an Admin, choose Visibility for this new promotion: This branch only, All branches in unit, or All branches (company) — the default is company-wide — then Save.

💡 Visibility cannot be changed after creation, so double-check it before saving if you manage multiple branches.

3 Activate, deactivate, edit or delete an offer

On the Promotions tab, use the toggle icon to Activate or Deactivate a promotion instantly (no confirmation needed), or the pencil icon to Edit its details.
On the Coupons tab, the trash icon is a soft "Deactivate" rather than a true delete — it asks for confirmation and keeps the coupon's usage history intact, it just stops it from being redeemable again.
Buy X Get Y and Bundle Price entries in the Promotions list have their toggle and edit actions disabled ("Read-only type") — they can only be viewed here.

Every Field & Button, Explained

Field / Button	What it does
`Coupon — Code`	The string a cashier or customer types at checkout to apply the discount; automatically uppercased.
`Coupon/Promotion — Type`	Percent (%) or Flat ($) — the only two types creatable from this screen.
`Coupon — Max Discount`	Only shown for Percent-type coupons; caps the maximum rupee amount a single redemption can discount.
`Min Order Value`	The cart subtotal must reach this amount before the coupon/promotion can apply; 0 means no minimum.
`Max Uses`	Total number of times the coupon/promotion can be redeemed across all customers; blank means unlimited (shown as usedCount / ∞ in the list).
`Expires At`	The single expiry date for the offer — there is no separate start date field.
`Promotion — Visibility (Admin, create-only)`	This branch only / All branches in unit / All branches (company) — controls which stores the automatic promotion applies at.
`Active toggle`	Instantly switches a promotion on/off without a confirmation dialog; disabled for read-only Buy X Get Y / Bundle Price types.
`Coupons list — Uses column`	Shows usedCount / maxUses, or usedCount / ∞ if no max was set.

Tips & Best Practices

Keep coupon codes short and easy to say out loud (e.g. DIWALI15) since a cashier or customer has to type them exactly at checkout.
Pair Percent coupons with a Max Discount cap so a single unusually large cart cannot eat into your margin more than intended.
Use a company-wide Promotion Visibility scope to run one sale across every branch from head office instead of recreating it store by store.
Use Min Order Value to stop small baskets from qualifying for a discount meant to encourage bigger purchases.

Troubleshooting & FAQ

I can't find a way to create a Buy X Get Y or Bundle Price deal.

Those two types are read-only on this page — they show up in the Promotions list if they already exist, but new ones cannot be created, edited or toggled here.

I deleted a coupon but it still shows up.

Deleting a coupon is really a soft "deactivate" — it stays visible with its usage history intact but can no longer be redeemed.

The Visibility field is missing when I try to edit a promotion.

Visibility scope can only be chosen once, at creation, and only by an Admin — it is not editable afterwards by design.

The Offers & Coupons menu item does not appear at all.

This page requires the Advanced plan tier and the Promotions feature — check your plan under Settings → Billing/Plan if you believe you should have access.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/packages/pos-react-lib/src/pages/PromotionsPage.jsx

Backend endpoints used:

GET /promotions/coupons
POST /promotions/coupons
DELETE /promotions/coupons/:id
GET /promotions/promotions
POST /promotions/promotions
PUT /promotions/promotions/:id
DELETE /promotions/promotions/:id

Related tables (db-core repositories):

Coupon
Promotion

Feature flag key: promotions (requires advanced plan tier or above)

Access control on this page is purely permission-based (usePagePermission() → canCreate/canEdit/canDelete) layered on top of the page-level Advanced-tier gate from the sidebar; there is no additional per-widget TierGate inside the component itself. Both list queries are scoped with the same selectCurrentScope / getScopeQueryParams pattern used on Sales and Customers, so what you see always matches your currently selected branch/unit/company.