👥 Sell / Billing
Customers
Customers is your shop's CRM: a searchable list of every customer with a live stats row and a "Today's Celebrations" banner for birthdays and anniversaries, plus a detail panel per customer covering purchase history, loyalty points, store wallet, saved documents, favourites, recommendations and referrals.
📍 Menu path: Sell / Billing → Customers
👤 Who uses it: All roles with Customers access (Loyalty, Store Wallet, Documents, QR, Favourites, Referrals and Blacklist need the Advanced plan tier; Recommendations needs Enterprise)
Overview
The page opens with four stat cards (Total customers, Active this month, Total revenue from customers, Average spend) and, on the Advanced tier, a "Today's Celebrations" banner listing any customers with a birthday 🎂 or anniversary 💍 today.
The main list is a searchable, sortable, exportable table (or grid) of every customer; clicking any row slides in a Customer Detail panel from the right rather than navigating to a new page.
The Add/Edit Customer form is organised into up to four tabs — Contact, Business, Regulatory, and Custom Fields — so GST/tax details and drug-licence numbers do not clutter the everyday contact fields.
Several sections of the detail panel — Loyalty, Store Wallet, Documents, QR/referral code, Favourites, Blacklist — are only available on the Advanced tier or above; a "Recommendations" section (suggested products based on purchase pattern) needs Enterprise.
Before You Start
- You need Customers feature access to see this page at all.
- If you are an Admin, adding a new customer requires a specific branch (not "All branches") selected in the scope selector — otherwise the Add Customer button shows a toast asking you to pick one.
- Loyalty, Store Wallet, Documents, QR code, Favourites, Referrals and Blacklist all require the Advanced plan tier; Recommendations requires Enterprise.
Step-by-Step Guide
1 Add a new customer
- Click + Add Customer and, on the Contact tab, fill in Name (required), Phone, Email, Birthday, Anniversary, Gender, Address, City and Postal/Pincode.
- Pick a Customer Group from the dropdown, or type a new one and click + New group to create it inline without leaving the form.
- Optionally set a Customer Card Barcode (or click Gen to auto-generate one), a Credit Limit and Credit Days (for udhaar/credit sales), and — if you were referred — a "Referred by" code.
- Switch to the Business tab for Tax ID/GSTIN, State, a Wholesale Trade Account (if any exist) and a Delivery Route; switch to Regulatory for Drug Licence No. and FSSAI No. if your shop needs them.
- Fill in any Custom Fields your Admin has configured for customers, then click Save.
💡 Admins choose a Visibility for the new customer at creation time — This branch only, All branches in unit, or All branches (company) — which cannot be changed later.
2 Search, sort and filter your customer list
- Type into the search box to filter by name, customer group, phone or email.
- Click a sortable column header — Name, Sales Count, Total Spend, Loyalty Points, Last Purchase, or (Admins only) Branch — to reorder the list.
- Switch between Table and Grid view, change the page size (10/25/50/100), or click Export to download the current list.
3 Open a customer's profile
- Click any row to slide in the Customer Detail panel.
- Review Contact Info, Personal details (birthday/anniversary/gender/notes), and the stats row: Purchases, Total Spend, Loyalty Points, Store Wallet balance and Outstanding balance (with an overdue count if applicable).
- Scroll to Purchase History to see every past sale with its status; use Send Reminder or Collect directly on a pending/overdue invoice.
- Click Statement to open that customer's full ledger in Reports, or Share History to send their last 5 purchases and total spend over WhatsApp.
4 Manage loyalty points and the store wallet
- Click the Loyalty icon on a row (or in the detail panel) to open the Loyalty modal; toggle between Add and Redeem, enter a points value and a reason, then confirm.
- Click Wallet to open the Store Wallet modal — its History tab lists every credit/debit with a running balance, while the +Credit and −Debit tabs let you add or remove funds with a note.
💡 Redeeming more points than the customer currently holds, or entering a zero/negative amount in either modal, is blocked with an on-screen error.
5 Manage documents, QR code and referrals
- Click Documents to upload files (PDF, JPG, PNG, WEBP, DOC/DOCX, under 9 MB) grouped as GST Certificate, ID Proof, Agreement or Other; view, download or delete any saved document from the same modal.
- Click the QR tile to show the customer's personal QR code alongside their referral code, with a Copy button.
- Check the Referrals section to see who this customer referred and whether each referral has already earned its reward.
6 Blacklist a problem customer
- Open the customer's detail panel and use the Blacklist section to mark them Blacklisted (or Remove from Blacklist to reverse it).
Every Field & Button, Explained
| Field / Button | What it does |
|---|---|
Name * | Required field; validation blocks saving with an empty name. |
Visibility (Admin, create-only) | This branch only / All branches in unit / All branches (company) — sets which stores can see this customer; fixed after creation. |
Phone / Email | Validated with a phone-format check (7–15 digits, allows +, spaces, hyphens) and an email-format check; invalid values block saving and focus the offending field. |
Birthday / Anniversary | Date fields that power the "Today's Celebrations" banner and birthday-offer auto-discounts at billing. |
Gender | Male / Female / Other toggle buttons. |
Customer Group + New group | Assign the customer to a segment; type a new group name and click "+ New group" to create it without leaving the form. |
Customer Card Barcode + Gen | A scannable code you can print on a loyalty card; "Gen" auto-generates one (format CUST + timestamp + random suffix). |
Credit Limit / Credit Days | Blocks credit sales above the limit once set, and auto-calculates the invoice due date from Credit Days. |
Tax ID / GSTIN | Localised label and max length by country (e.g. GSTIN, 15 characters, for India). |
Wholesale Trade Account | Only shown if trade accounts exist; links the customer to a wholesale discount percentage. |
Drug Licence No. / FSSAI No. | Regulatory identifiers relevant to pharmacy/food businesses. |
Loyalty modal — Add / Redeem | Adjusts the customer's points balance up or down with a mandatory reason; redemption is capped at the current balance. |
Wallet modal — History / +Credit / −Debit | A running-balance ledger of store-wallet transactions plus forms to add or remove funds with a note. |
Documents modal | Upload/view/download/delete files under 9 MB, grouped by type (GST Certificate, ID Proof, Agreement, Other). |
Purchase History — Send Reminder / Collect | Per past sale: send a WhatsApp payment reminder, or record a payment collection against that invoice. |
Tips & Best Practices
- Set a Credit Limit and Credit Days on regular udhaar (credit) customers so overdue balances are flagged automatically instead of relying on memory.
- Use Customer Groups plus the printed Customer Card Barcode for a fast, scan-to-recall checkout experience for regulars.
- Encourage regulars to share their Referral Code — the Referrals section tracks who they bring in and whether the reward has already been paid out.
- Use Share History from the detail panel as a quick, personal WhatsApp touchpoint (last 5 purchases + total spend) instead of typing a message from scratch.
Troubleshooting & FAQ
Clicking + Add Customer does not open the form.
If you are an Admin, you must select one specific branch (not "All branches") in the scope selector before adding a customer.
Save fails with a phone or email error.
Phone numbers must be 7–15 digits (spaces/hyphens/+ allowed) and email addresses must match a standard name@domain.tld pattern.
The Loyalty, Wallet or Documents icon is missing or locked on a customer row.
Those features require the Advanced plan tier — ask your Admin to check the plan under Settings → Billing/Plan.
I tried to redeem loyalty points and it was rejected.
You cannot redeem more points than the customer currently holds — check their current balance in the stats row first.
The Customer Group dropdown is empty.
Type the group name you want directly into the field and click "+ New group" to create it on the spot — you do not need to set groups up elsewhere first.
🧑💻 Developer Notes
Source component(s):
frontend-app/packages/pos-react-lib/src/pages/Customers.jsx
Backend endpoints used:
GET /customersGET /customers/statsGET /customers/celebrations-todayGET /customers/:idPOST /customersPUT /customers/:idDELETE /customers/:idPATCH /customers/:id/blacklistPOST /customers/:id/loyaltyGET /customers/:id/walletPOST /customers/:id/wallet/creditPOST /customers/:id/wallet/debitGET /customers/:id/documentsPOST /customers/:id/documentsDELETE /customers/:id/documents/:docIdGET /customers/:id/favoritesPOST /customers/:id/favoritesDELETE /customers/:id/favorites/:productIdGET /customers/:id/recommendationsGET /customers/:id/referralsGET /settings/customer-groupsPOST /settings/customer-groupsGET /wholesale/trade-accountsPUT /sales/:id/payment
Related tables (db-core repositories):
CustomerCustomerGroupCustomerDocumentCustomerFavoriteCustomerWalletTransactionReferralSaleCustomField
Feature flag key: customers
All Advanced-tier sections (Celebrations banner, Loyalty, Wallet, Documents, QR, Favourites, Referrals, Blacklist) and the Enterprise-tier Recommendations section are individually wrapped in <TierGate feature="customers"> rather than gating the whole page, so the core list and Add/Edit form remain fully usable on the Basic tier. No custom keyboard shortcuts exist on this page.