# Technical reference (https://docs.loybox.com.ar/en/referencia-tecnica)



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](https://docs.loybox.com.ar/conceptos)):

| 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.                                                                                                   |

<Callout type="info" title="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.
</Callout>

## Point calculation
The main rule is money per point
([Earning points](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)):

```
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:

<Steps>
  <Step>
    ### Base point
    Following the money-per-point rule, or the per-currency conversion.
  </Step>

  <Step>
    ### Double points
    If the promotion is running, it doubles the previous result.
  </Step>

  <Step>
    ### The tier's percentage bonus
    Applied last, according to the tier the member holds at the time of the purchase
    ([Tier benefits](https://docs.loybox.com.ar/niveles/beneficios-de-nivel)).
  </Step>
</Steps>

### 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
<Callout title="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.
</Callout>

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](https://docs.loybox.com.ar/puntos-y-premios/expiracion)):

| 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. |

<Callout type="info" title="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.
</Callout>

## Tiers
A member's tier is resolved by thresholds
([How members move up](https://docs.loybox.com.ar/niveles/como-suben-de-nivel)):

* 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](https://docs.loybox.com.ar/niveles/vencimiento-de-niveles)). 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](https://docs.loybox.com.ar/puntos-y-premios/premios)). 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](https://docs.loybox.com.ar/puntos-y-premios/canje)):

<Steps>
  <Step>
    ### Balance check
    The redemption goes through only if the member covers the reward's cost in
    points.
  </Step>

  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

A redeemed reward keeps the original reward's validity date.

## Segmentation
Members are grouped automatically with the RFM model
([Segmentation](https://docs.loybox.com.ar/segmentacion)), 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.

<Callout type="info">
  Segmentation is calculated over the orders of the connected online store.
</Callout>

## 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](https://docs.loybox.com.ar/integraciones)): 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.