Technical reference
How Loybox works under the hood, with the data model, the point calculation formulas, the expiration modes and the rules for tiers, rewards and redemption on a single page.
This page sums up, in one place, how Loybox works at a technical level: the entities, the formulas and the rules that govern each mechanism. Every section links to the matching guide if you need the full detail.
Entities
The whole model rests on five pieces (Concepts):
| Entity | What it represents |
|---|---|
| Brand | The company inside Loybox. It sets the currency, the point rules, the reward catalog and the app's identity. It can have one location or many. |
| Member | The person who joined the club. They have a relationship with the brand, with their own point balance and history. |
| Consumption | The record of a purchase, in the store or in the online store. It is what triggers the point calculation. |
| Point | The unit of loyalty. It is earned through consumptions and other actions, and spent redeeming rewards. |
| Reward | What the member gets in exchange for points. |
The API calls a member a client
In the API the member of a club is the client resource (/v1/clients), and the
dashboard says Cliente. This page uses "member", which is the product's term
for the people in the club; "client" is the brand that signs up. Where a field or
an endpoint is named, the API's own name is used.
Point calculation
The main rule is money per point (Earning points):
points = floor( purchase amount ÷ money per point )Rounding is always down. With 100 = 1 point, a purchase of 1,750 earns 17
points.
Default per-currency conversion
If the brand does not define a money-per-point rule, a per-currency conversion applies:
| Currency | Default rule |
|---|---|
| Euro (EUR) | 50 points per € |
| Mexican peso (MXN) | 1 point per 50 MXN |
| Everything else | Converted to dollars (MEP rate, refreshed regularly) and 50 points per USD |
As soon as the brand defines its own rule, this conversion stops applying.
The order of the multipliers
Order matters, because the adjustments cascade:
Base point
Following the money-per-point rule, or the per-currency conversion.
Double points
If the promotion is running, it doubles the previous result.
The tier's percentage bonus
Applied last, according to the tier the member holds at the time of the purchase (Tier benefits).
Other sources of points
Beyond consumptions, points are awarded by referrals (once the invitee's first purchase goes through), birthdays, joining the club and reaching a tier for the first time.
Balance
The balance is computed, not stored
A member's balance is always live earned points − redeemed points. There is no
persisted counter to reconcile, so the number is consistent with the real history
by construction.
Expired points are not deleted from the history: they stop counting when the available balance is calculated.
Point expiration
There are three modes (Point expiration):
| Mode | Behavior |
|---|---|
| No expiration | Points never expire. This is the default mode. |
| Rolling | The whole balance shares a single expiration date, renewed with every new purchase. |
| Per transaction | The points of each consumption expire at their own pace, regardless of later purchases. |
The days condition
Expiration only applies if the mode is rolling or per transaction and the
period in days is greater than zero. With the period at zero, points do not expire
even if the mode is active.
Tiers
A member's tier is resolved by thresholds (How members move up):
- Each tier is measured by accumulated points or by amount spent, and each tier can use its own criterion within the same ladder.
- Progress is calculated over the full history of the relationship, not over the current balance. That is why redeeming never demotes anyone: the balance drops, the tier does not.
- After each purchase, the member sits in the highest tier whose threshold they already reached.
- Thresholds always increase: a higher tier cannot demand less than a lower one.
The base tier is the entry step: it has no threshold and no expiration, and it never expires (Expiration and demotion). Tier expiration only applies to VIP tiers measured by points.
Rewards
A reward is defined by type and value, cost in points, redemption cap, expiration and an optional image (Rewards). The text the member sees is generated from the type and the value.
Types: free product, money voucher ($), percentage discount (%), 2-for-1,
free shipping and free-form (your own text).
Possible states, derived from the configuration:
| State | Condition |
|---|---|
| Active | Available to redeem. |
| Inactive | Paused manually. |
| Expired | Its expiration date has passed. |
| Sold out | It reached its total redemption cap. |
Only active rewards show up as available to the member. A redemption cap of zero means unlimited.
Redemption
The flow checks the balance before deducting (Redemption):
Balance check
The redemption goes through only if the member covers the reward's cost in points.
Deduction and issuance
The redemption is recorded, the cost is subtracted from the balance and the reward ends up in the member's name with a short, unique validation code.
Code validation
The code is bound to the brand and to that specific redemption. Once marked as used it cannot be validated again, which prevents double use.
A redeemed reward keeps the original reward's validity date.
Segmentation
Members are grouped automatically with the RFM model (Segmentation), over three signals: recency (how long ago they bought), frequency (how many times) and monetary value (how much they spent in total).
The segments follow the RFM standard: Champions, Leales, Leales en potencia, Necesitan atención, En riesgo, Hibernando and Perdidos (the
names come back from the product in Spanish: loyal, potential loyalists, need
attention, at risk, hibernating and lost). Each one exposes its RFM rule, its
member count, its weight in the base and in sales, and averages for recency,
frequency and order value.
Segmentation is calculated over the orders of the connected online store.
Channels and integrations
One brand can run the club in brick-and-mortar stores (a PWA app with its own branding) and in its online store (wired into the checkout). The point rules and the reward catalog are shared across channels.
Available integrations (Integrations): Tiendanube (orders, products and customers), WhatsApp Business (notifications and messages) and Perfit (contact sync for email).
Reviews and recommendations depend on having the online store connected.