👑 garment

VIP Tiers

VIP Tiers is a spend-based loyalty system — you define tiers such as Silver, Gold and Platinum with a minimum lifetime-spend threshold and a set of perks, and the page shows every customer's all-time spend alongside the tier they currently qualify for.

📍 Menu path: /garment/vip-tiers

👤 Who uses it: Owner,Manager

Overview

Each tier stores a Name, a Minimum Lifetime Spend threshold, a Colour (used for its badge), and a list of Perks — either freely typed or picked from eight preset suggestions (early access to new arrivals, free alterations, priority reservations, birthday discount, exclusive styling sessions, free home delivery, special season preview, complimentary gift wrapping).

The Tier Definitions tab lists every tier you have configured, sorted automatically from lowest to highest minimum spend.

The Customer Status tab lists every customer who has any recorded spend, their lifetime total, and the highest tier whose threshold they currently meet (or "No Tier" if they are below the lowest threshold) — this is computed fresh every time the page loads, it is not a stored/locked-in value.

Lifetime spend is summed across every Sale linked to that customer for your whole account, not scoped to a single branch, and covers the customer's entire history, not a rolling window.

Before You Start

Requires the "customers" plan feature to be enabled.
Tier Name and Minimum Lifetime Spend are both required to save a tier; Colour and Perks are optional.
A customer only appears on the Customer Status tab once they have at least one sale linked to their Customer record — walk-in sales with no customer selected are not counted toward anyone's spend.

Step-by-Step Guide

1 Define a VIP tier

On the Tier Definitions tab, click New Tier.
Enter Tier Name * (e.g. "Silver", "Gold", "Platinum") and Minimum Lifetime Spend * — the total a customer must have spent to unlock this tier.
Pick a Tier Colour swatch (used for the tier's badge everywhere it appears).
Add Perks by typing your own and pressing Enter/Add, or clicking any of the eight preset perk suggestions.
Click Save Tier.

2 Edit or remove a tier

Click the edit (pencil) icon on a tier card to reopen it pre-filled, adjust any field, and click Save Changes.
Click the trash icon and confirm to permanently delete a tier — customers previously in that tier are simply re-evaluated against whatever tiers remain.

3 Check which tier a customer is in

Switch to the Customer Status tab.
Find the customer in the list — their lifetime spend and current tier badge (or "No Tier") are shown together.

Every Field & Button, Explained

Field / Button	What it does
`Tier Definitions / Customer Status tabs`	Tier Definitions manages the tier configuration; Customer Status shows every customer's spend and current tier.
`New Tier`	Opens the tier creation form (Tier Definitions tab only).
`Tier Name *`	Required label for the tier, e.g. Silver, Gold, Platinum.
`Minimum Lifetime Spend *`	Required all-time spend threshold a customer must reach to unlock this tier; tiers are listed lowest-to-highest by this value automatically.
`Tier Colour`	One of eight preset swatches; used for the tier's badge on both tabs.
`Perks`	A list of perk strings, either freely typed or chosen from eight preset suggestions; stored as a JSON array.
`Tier card`	Shows the colour dot, name, minimum spend and perk chips, with Edit and Delete actions.
`Customer Status list`	Customer name, lifetime spend, and a colour-coded tier badge or "No Tier" if their spend is below every tier's threshold.

Tips & Best Practices

Set thresholds around your own customers' real spend distribution rather than round numbers borrowed from another shop — check the Customer Status tab after creating tiers to see how many customers actually land in each one.
Keep perks concrete and deliverable by staff (e.g. "Free alterations" rather than a vague "VIP treatment") since perks are only a promise shown on the badge — nothing in this page automatically applies a perk at billing time.
Recheck the Customer Status tab periodically — tiers are evaluated live from current data, so a customer's badge changes automatically the moment their lifetime spend crosses a threshold.

Troubleshooting & FAQ

A customer's badge shows "No Tier" even though I'm sure they have spent enough.

Lifetime spend is only summed from Sale records that are linked to that customer's saved Customer profile — if some of their purchases were rung up as walk-in sales without selecting their customer record, those amounts are not counted.

Customer names are missing or blank on the Customer Status tab.

This is a known gap: the underlying vip-status endpoint aggregates spend by customerId only and never looks up the matching name from the Customer table, so the customer name column can render blank even though the spend and tier figures are correct.

I deleted a tier and now a customer who used to show "Gold" shows something else.

Tiers are not stored per customer — the Customer Status tab recalculates the best-matching tier fresh every time the page loads, using whatever tiers currently exist. Deleting a tier removes it from consideration for every customer immediately.

I reordered my perks list but the tier order on the page didn't change.

Tiers are always displayed sorted by Minimum Lifetime Spend, ascending — there is currently no way to manually reorder tiers independent of their spend threshold.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/pos-app-garment/src/pages/garment/VipTierPage.jsx

Backend endpoints used:

GET /garment/vip-tiers
POST /garment/vip-tiers
PUT /garment/vip-tiers/:id
DELETE /garment/vip-tiers/:id
GET /garment/vip-status

Related tables (db-core repositories):

GarmentVipTier
Sale

Redux slices:

None — local component state only

Feature flag key: customers

getCustomerVipStatus (packages/pos-core/src/garment.js) selects only `customerId` and `total` from Sale to build lifetime spend, and never joins back to the Customer table for a name — yet VipTierPage.jsx renders `c.customerName` for every row on the Customer Status tab. That field is always undefined, so the customer name is silently blank for every row; this reads as a genuine bug (a missing join) rather than an intentional omission. Tier assignment takes the highest-threshold tier whose minSpend the customer's all-time total meets (tiers queried sorted descending by minSpend, first match wins) and is recomputed on every page load, never persisted per customer. GarmentVipTier also has a `sortOrder` column that create/update accept, but the UI never exposes a control for it and listVipTiers always orders by minSpend ascending regardless — sortOrder is effectively dead weight from this screen. Spend aggregation has no store/branch filter applied by the frontend, so lifetime spend is always account-wide across every branch.