Loyalty Tiers

The loyalty tier system rewards regular customers with automatic discounts based on their accumulated activity. As members use the cafe (spending money, logging in, purchasing packages, or placing orders) they earn loyalty points. When their total points exceed a tier threshold, they advance to a higher tier and receive a larger discount on session pricing.

Tier Structure

Each loyalty tier is defined by four fields:

Tiers are ordered by their threshold_points value. A member belongs to the highest tier for which they meet the point threshold.

Basis Point (BPS) Discounts

Discounts are expressed in basis points (BPS) rather than percentages to avoid floating-point rounding errors in financial calculations. One basis point equals 0.01%, or one hundredth of a percent.

Common discount values:

When a member with a tier discount starts a session, the pricing engine reduces the base hourly rate by the tier's discount_bps before calculating segment costs.

Loyalty Events

Members earn points through loyalty events. Each event records a point change and the activity that triggered it:

Each loyalty event record includes:

• points_delta: The number of points gained (positive) or lost (negative) from this event.
• amount_minor: The monetary amount associated with the event (in minor currency units), if applicable.
• minutes_delta: The number of minutes associated with the event, if applicable.
• source_entity / source_entity_id: A reference back to the session, order, or transaction that generated the event.
• event_at: The timestamp when the event occurred.

Tier Progression

Tier progression works as follows:

1. A member performs an activity (session, purchase, login, etc.).
2. The system creates a loyalty event with the corresponding points_delta.
3. The member's total points are recalculated as the sum of all their loyalty event points_delta values.
4. The system checks if the new total meets the threshold for a higher tier.
5. If the member qualifies for a new tier, their tier field is updated and the new discount takes effect on their next session.

Tier assignment can also be set manually by an administrator, overriding the automatic calculation.

How Tier Discounts Apply to Session Pricing

When the pricing engine calculates the cost of a session segment for a member:

1. The base hourly price is determined by the active pricing slot.
2. If the member has a tier with a discount_bps value, the base price is reduced: discounted_price = base_price * (10000 - discount_bps) / 10000.
3. Additionally, individual member-level discounts (member_discount_bps on the member record) are applied if present.
4. The final discounted rate is used to calculate the segment cost.

Tier discounts and member-level discounts can stack, giving the member the combined benefit of both.

Creating and Managing Tiers

To create a new tier:

1. Navigate to Settings and open the Pricing section (or the dedicated tier management area).
2. Click Add Tier.
3. Enter the code (unique, lowercase), name (display label), threshold points, and discount BPS.
4. Save the tier.

To edit an existing tier, select it from the list and modify any of its fields. Changes to a tier's discount_bps take effect on all members currently assigned to that tier, starting with their next session.

To delete a tier, remove it from the list. Members who were assigned to the deleted tier will fall back to the next-lower tier for which they qualify based on their points.

Example Tier Setup

A typical three-tier configuration might look like this:

In this setup, a new member starts at Bronze (no discount). After accumulating 500 points from visits, spending, and orders, they automatically upgrade to Silver with a 5% discount. At 2000 points they reach Gold (10%) and at 5000 points they achieve VIP status (15%).