# Loybox Documentation

> Loybox is a loyalty platform for brands: each brand builds its own membership
> club, where members earn points on every purchase and redeem them for rewards,
> with VIP tiers, referrals, reviews, recommendations and campaigns. It runs in
> brick-and-mortar stores (a PWA branded as the client's own app) and in online
> stores wired into the checkout. This documentation is in English and describes
> the product from the admin dashboard and from the API.

## Other languages

The same documentation exists in three languages, each with its own
`llms.txt`, its `llms-full.txt` and its per-page Markdown:

- Spanish (Argentina), the original: https://docs.loybox.com.ar/llms.txt
- Spanish (Latin America): https://docs.loybox.com.ar/es-419/llms.txt
- English (this version): https://docs.loybox.com.ar/en/llms.txt

Slugs are identical across the three languages: only the prefix changes.

## Formats for agents

- [llms-full.txt](https://docs.loybox.com.ar/en/llms-full.txt): the full text of the entire
  documentation in a single file.
- [openapi.json](https://docs.loybox.com.ar/openapi.json): the OpenAPI 3.1 specification of
  the public API, with all 25 endpoints, the response schemas and the two
  credentials. This is the source to generate a client from. There is one
  specification for all three languages, and its descriptions are in Spanish.
- Any page as raw Markdown, by appending `.md` to the path. For example
  [https://docs.loybox.com.ar/en/conceptos.md](https://docs.loybox.com.ar/en/conceptos.md). The normal URL also answers to
  the `Accept: text/markdown` header.
- [sitemap.xml](https://docs.loybox.com.ar/sitemap.xml): every indexable URL, in all three
  languages, with its alternates declared.

## The API in two minutes

Full reference in [About the API](https://docs.loybox.com.ar/en/api-reference) and the end-to-end
integration in [Getting started](https://docs.loybox.com.ar/en/api-reference/primeros-pasos). The
essentials:

- **Base URL**: `https://loybox-public-api-752998171300.southamerica-west1.run.app`. The version goes in the first segment
  (`/v1/...`); REST over HTTPS, JSON, `snake_case` fields, ISO 8601 dates.
- **Two credentials that are not interchangeable**: the merchant API key
  (`Authorization: Bearer {api-key}`) operates across every member and lives on
  the server only; the end-user token (`Authorization: Bearer {access}`, always
  alongside the `X-Commerce-Id` header) only sees its own data and can live in
  the browser.
- **The `X-Commerce-Id` header** is required on Authentication, My account and
  Public, even without a token. It is not a secret: it scopes, it does not
  authorize. It is the most common cause of a `422`.
- **The minimum integration** is a single call:
  `POST /v1/consumptions/email` with the member's email and the purchase
  amount. Loybox computes the points.
- **The reward cycle**: the member buys a benefit with points
  (`POST /v1/me/benefits/exchange`) and gets back a `client_benefit_code`; the
  merchant looks it up (`GET /v2/benefits/preview/{code}`), applies the discount
  and only then burns it (`POST /v1/benefits/redeem`).
- **Responses have no envelope**: the object comes at the root and lists are a
  plain array. Optional fields are always present, set to `null`.

## How Loybox works

Full reference in [Technical reference](https://docs.loybox.com.ar/en/referencia-tecnica). The
essentials:

- **Entities**: brand, member, consumption (a recorded purchase), point and
  reward.
- **Points per purchase**: `points = floor(amount ÷ money per point)`, rounding
  down. If the brand does not define that rule, a per-currency conversion applies
  (50 points per €; 1 point per 50 MXN; anything else is converted to USD at the
  MEP rate and earns 50 points per dollar).
- **Multipliers cascade**: the base point first, then double points if they are
  running, and last the percentage bonus of the tier the member held at the time
  of the purchase.
- **Balance** is always computed as live earned points minus redeemed points.
  There is no stored counter. Expired points are not deleted from the history,
  they stop counting.
- **Point expiration**: three modes. No expiration (the default), rolling (one
  date for the whole balance, renewed with every purchase) and per transaction
  (each consumption with its own date). It only applies when the period in days
  is greater than zero.
- **Tiers**: each tier has a threshold measured in accumulated points or in
  amount spent, always over the full history and never over the balance, so
  redeeming never demotes anyone. A member sits in the highest tier whose
  threshold they reached. Thresholds are increasing and the base tier does not
  expire.
- **Rewards**: type and value, cost in points, redemption cap (zero means
  unlimited), expiration. States are active, inactive, expired and sold out; only
  active ones can be redeemed.
- **Redemption**: the balance is checked, the points are deducted and a short,
  unique code is issued, bound to the brand and to that redemption, which cannot
  be validated twice.
- **Segmentation**: an RFM model (recency, frequency, monetary value) over the
  orders of the connected online store, with the standard segments (`Champions`,
  `Leales`, `En riesgo`, `Hibernando`, `Perdidos` and others — the API returns
  these names in Spanish).
- **Integrations**: Tiendanube (orders, products and customers), WhatsApp
  Business (notifications) and Perfit (contacts for email).

## Guides

- [Introduction](https://docs.loybox.com.ar/en/introduccion): Loybox is the loyalty program for ambitious brands. Build your membership club, earn points on every purchase and turn buying into a habit.
- [Concepts](https://docs.loybox.com.ar/en/conceptos): The mental model behind Loybox (brands, members, points and rewards) so everything fits together before you configure your club.

### Loyalty

- Points and rewards
  - [Fundamentals](https://docs.loybox.com.ar/en/puntos-y-premios): The Loybox points and rewards system, the core mechanic of your loyalty program, at a glance.
  - [Earning points](https://docs.loybox.com.ar/en/puntos-y-premios/ganar-puntos): How Loybox calculates the points of each purchase, and what other actions (referrals, birthdays, surveys, tiers) also earn them.
  - [Point expiration](https://docs.loybox.com.ar/en/puntos-y-premios/expiracion): The three Loybox expiration modes (no expiration, rolling and per transaction) and when each one makes sense.
  - [Rewards](https://docs.loybox.com.ar/en/puntos-y-premios/premios): How to build your reward catalog in Loybox, with reward types, cost in points, redemption caps and validity.
  - [Create a reward](https://docs.loybox.com.ar/en/puntos-y-premios/crear-un-premio): A step-by-step guide to creating a reward in the Loybox dashboard, from picking the type to making it available for redemption.
  - [Redemption](https://docs.loybox.com.ar/en/puntos-y-premios/canje): The redemption flow in Loybox, what happens when a member trades points for a reward, and how your team validates it with a code.
- Tiers
  - [Fundamentals](https://docs.loybox.com.ar/en/niveles): What Loybox VIP tiers are, and how they reward your best members with more benefits as they move up.
  - [How members move up](https://docs.loybox.com.ar/en/niveles/como-suben-de-nivel): How Loybox decides each member's tier using thresholds by accumulated points or amount spent, always over their full history.
  - [Benefits of each tier](https://docs.loybox.com.ar/en/niveles/beneficios-de-nivel): Everything you can give at each Loybox tier, from the points multiplier to the reward on arrival and the tier's exclusive rewards.
  - [Expiration and demotion](https://docs.loybox.com.ar/en/niveles/vencimiento-de-niveles): Tier expiration in Loybox, how status is kept with activity, demotion through inactivity, and when it is worth using.
  - [Design your tiers](https://docs.loybox.com.ar/en/niveles/armar-tus-niveles): The guide to designing your VIP tier ladder in Loybox and deciding how many tiers, which thresholds, which names and which benefits each one gets.
  - [Create a tier](https://docs.loybox.com.ar/en/niveles/crear-un-nivel): A step-by-step guide to creating a tier in the Loybox dashboard, from the base tier to the rewards of each step.
- Referrals
  - [Fundamentals](https://docs.loybox.com.ar/en/referidos): What the Loybox referral program is, and how your own members bring new members in exchange for points.
  - [Turn on referrals](https://docs.loybox.com.ar/en/referidos/activar-referidos): A step-by-step guide to turning on the referral program in the Loybox dashboard and defining how many points each referral earns.
- Reviews
  - [Fundamentals](https://docs.loybox.com.ar/en/resenas): How Loybox reviews work, with automatic WhatsApp requests after a purchase to collect reviews of your business and your products.
  - [Configure reviews](https://docs.loybox.com.ar/en/resenas/configurar-resenas): A step-by-step guide to turning on reviews in the Loybox dashboard, both Google reviews and product reviews (native or with your own system).
- Recommendations
  - [Fundamentals](https://docs.loybox.com.ar/en/recomendaciones): How Loybox's AI product recommendations work, showing similar, complementary, upgrade and personalized products to grow your sales.
  - [Configure recommendations](https://docs.loybox.com.ar/en/recomendaciones/configurar-recomendaciones): A step-by-step guide to turning on and tuning product recommendations in the Loybox dashboard, where they show up and which notifications to send.

### Automations

- Cart
  - [Fundamentals](https://docs.loybox.com.ar/en/carrito): Loybox's cart tools, to recover abandoned carts and reward purchases above a given amount.
  - [Recover abandoned carts](https://docs.loybox.com.ar/en/carrito/recuperar-carritos): A step-by-step guide to configuring abandoned-cart reminders over WhatsApp in Loybox.
  - [Cart rewards](https://docs.loybox.com.ar/en/carrito/recompensas-en-carrito): A step-by-step guide to creating amount-based reward rules in the Loybox cart and raising your average order value.
- Segmentation
  - [Fundamentals](https://docs.loybox.com.ar/en/segmentacion): How Loybox customer segmentation works, grouping your base by purchase patterns (RFM) so you can act on each group.
  - [Using your segments](https://docs.loybox.com.ar/en/segmentacion/usar-tus-segmentos): How to read the Loybox segmentation dashboard, see the members of each segment and act on them with campaigns.
- Campaigns
  - [Fundamentals](https://docs.loybox.com.ar/en/campanas): How Loybox campaigns work, messages aimed at a member segment over WhatsApp or email, with results tracking.
  - [Create a campaign](https://docs.loybox.com.ar/en/campanas/crear-una-campana): A step-by-step guide to creating, scheduling and sending a campaign to a member segment in Loybox.
- Integrations
  - [Integrations](https://docs.loybox.com.ar/en/integraciones): Connect your store, your WhatsApp and your marketing tools to Loybox so everything works together.
  - [Tiendanube](https://docs.loybox.com.ar/en/integraciones/tiendanube): Connect your Tiendanube store to Loybox to sync orders, products and customers.
  - [WhatsApp Business](https://docs.loybox.com.ar/en/integraciones/whatsapp): Connect WhatsApp Business to Loybox to send notifications and loyalty messages to your members.
  - [Perfit](https://docs.loybox.com.ar/en/integraciones/perfit): Connect Perfit to Loybox to sync your contacts and power up your email marketing campaigns.
- [Technical reference](https://docs.loybox.com.ar/en/referencia-tecnica): 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.

## API Reference

- [About the API](https://docs.loybox.com.ar/en/api-reference): A REST API to connect your loyalty program to your own systems, from your server or straight from your website.
- [Getting started](https://docs.loybox.com.ar/en/api-reference/primeros-pasos): From zero to the first purchase that earns points, and from there to redemption, with the exact calls for each step.
- [Credentials](https://docs.loybox.com.ar/en/api-reference/credenciales): The API's two credentials, which headers each call carries, and which one can live in the browser.
- [Objects](https://docs.loybox.com.ar/en/api-reference/objetos): The objects the API returns, field by field, and the difference between a benefit and a redeemable benefit.
- [Errors](https://docs.loybox.com.ar/en/api-reference/errores): The status codes the API returns, the shape of the error body and what to do in each case.

### Consumptions

- [Consumptions](https://docs.loybox.com.ar/en/api-reference/consumos): Recording your members' purchases so they earn points, by client code or by email.
- [Create consumption by code](https://docs.loybox.com.ar/en/api-reference/consumos/crear-por-codigo): Records a purchase using the member's code, so it earns points.
- [Create consumption by email](https://docs.loybox.com.ar/en/api-reference/consumos/crear-por-email): Records a purchase using the member's email, even if they do not have a Loybox account yet.

### Clients

- [Clients](https://docs.loybox.com.ar/en/api-reference/clientes): Looking up the commerce's members, their points and the benefits they can buy or already bought.
- [List clients](https://docs.loybox.com.ar/en/api-reference/clientes/listar): The commerce's client list, paginated by limit and offset.
- [Get a client](https://docs.loybox.com.ar/en/api-reference/clientes/obtener): Looks a client up by their code and returns their data and their point balance.
- [Benefits they can buy](https://docs.loybox.com.ar/en/api-reference/clientes/beneficios-disponibles): The benefits a client can buy with the points they hold.
- [Purchased benefits](https://docs.loybox.com.ar/en/api-reference/clientes/beneficios-comprados): The benefits a client already bought and can still redeem, each with its redemption code.

### Benefits

- [Benefits](https://docs.loybox.com.ar/en/api-reference/beneficios): The commerce's reward catalog, the lookup of a redemption code, and the redemption itself.
- [List benefits](https://docs.loybox.com.ar/en/api-reference/beneficios/listar): Every benefit the commerce created.
- [Get a benefit](https://docs.loybox.com.ar/en/api-reference/beneficios/obtener): The data of a catalog benefit, by its benefit_id.
- [Look up a code](https://docs.loybox.com.ar/en/api-reference/beneficios/consultar-codigo): Which reward a redemption code is, before redeeming it.
- [Look up a code (v2)](https://docs.loybox.com.ar/en/api-reference/beneficios/consultar-codigo-v2): Version 2 of the code lookup, with the title and the discount's value at the top level.
- [Redeem a benefit](https://docs.loybox.com.ar/en/api-reference/beneficios/canjear): Marks a redemption code as used. It is final.

### Authentication

- [Authentication](https://docs.loybox.com.ar/en/api-reference/autenticacion): End-user sign-in with a one-time code sent by email, to wire Loybox straight into your website.
- [Request a code](https://docs.loybox.com.ar/en/api-reference/autenticacion/pedir-codigo): Sends the user a 6-digit code by email to sign in.
- [Verify the code](https://docs.loybox.com.ar/en/api-reference/autenticacion/verificar-codigo): Validates the code received by email and returns the user's session tokens.
- [Renew the token](https://docs.loybox.com.ar/en/api-reference/autenticacion/renovar-token): A new access token from the refresh token, without asking the user for another code.

### My account

- [My account](https://docs.loybox.com.ar/en/api-reference/mi-cuenta): The end user's endpoints: their points, their benefits, their history and their tier in your program.
- [My account](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/obtener): Everything the first render needs: the user's data, their points, the commerce's branding and the points about to expire.
- [Benefits I can buy](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/beneficios-disponibles): The commerce's catalog of live benefits that the user can buy with their points.
- [Buy a benefit](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/comprar-beneficio): Trades the user's points for a catalog benefit and returns the redemption code.
- [My benefits](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/mis-beneficios): The benefits the user already bought and can still redeem, with their code.
- [My history](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/historial): The user's activity in the program: consumptions, benefit purchases, redemptions and rewards.
- [My tier](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/nivel): The user's current tier, their points multiplier and what is missing to reach the next one.
- [Program rewards](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/recompensas): The rewards the commerce hands out on its own: welcome, birthday and member of the month.
- [Join the program](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/adherirme): Subscribes the user to the commerce's loyalty program and returns the welcome reward.
- [Opt out](https://docs.loybox.com.ar/en/api-reference/mi-cuenta/darme-de-baja): Unsubscribes the user from the commerce's program, without losing the accumulated points.

### Public

- [Public](https://docs.loybox.com.ar/en/api-reference/publico): The commerce's data and the benefit catalog with no token at all, to show the program to a visitor.
- [Commerce data](https://docs.loybox.com.ar/en/api-reference/publico/comercio): The commerce's name, logo, brand color and category, with no token needed.
- [Benefit catalog](https://docs.loybox.com.ar/en/api-reference/publico/beneficios): The commerce's live benefits, with no token needed.