# Documentación de Loybox
> Loybox es una plataforma de lealtad para marcas: cada marca arma su propio
> club de miembros donde los clientes acumulan puntos con cada compra y los
> canjean por recompensas, con niveles VIP, referidos, reseñas, recomendaciones
> y campañas.
Este archivo es el texto completo de toda la documentación EN ESPAÑOL NEUTRO DE
LATINOAMÉRICA, en el orden en que está organizada: primero las guías del
producto, después la referencia de la API. Cada página abre con un `#` seguido
de su URL.
La misma doc en español de Argentina: https://docs.loybox.com.ar/llms-full.txt
La misma doc en inglés: https://docs.loybox.com.ar/en/llms-full.txt
Índice de páginas y resumen de la API: https://docs.loybox.com.ar/es-419/llms.txt
Especificación de la API para generar un cliente: https://docs.loybox.com.ar/openapi.json
---
# Introducción (https://docs.loybox.com.ar/es-419/introduccion)
Los anuncios traen clientes. La lealtad los hace volver.
**Loybox es la plataforma para crear tu propio club de miembros**: una app con tu
marca para negocios físicos, o integrada a tu tienda online, con la que
premias a tus clientes, aumentas la recurrencia y haces crecer el valor de
cada relación.
## El problema que resuelve
Adquirir un cliente es sólo el primer paso. La rentabilidad real aparece
cuando ese cliente vuelve, gasta más y trae a otro. Sin un sistema de
lealtad, dependes de seguir pagando para traer una y otra vez al mismo
perfil de cliente.
## Cómo funciona, en una frase
Tus clientes suman puntos con cada compra y los canjean por las recompensas
exclusivas de tu marca. Alrededor de eso, Loybox suma niveles VIP, desafíos,
referidos, campañas y comunidad para que la compra se convierta en un hábito.
## Tu club, en todos tus canales
## Por dónde empezar
Esta documentación crece herramienta por herramienta. Arranca por los fundamentos:
# Conceptos (https://docs.loybox.com.ar/es-419/conceptos)
Antes de configurar tu club conviene tener claro el vocabulario. Todo Loybox
se construye sobre cuatro piezas.
## Las piezas
## El ciclo de lealtad
El corazón de Loybox es un ciclo simple que se repite y se refuerza en cada
visita:
### El cliente compra
En tu negocio o en tu tienda online. Cada compra queda registrada como un
consumo.
### Suma puntos
El consumo genera puntos automáticamente, según las reglas que defines
(ver [Ganar puntos](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)).
### Canjea recompensas
Cuando junta suficientes puntos, los cambia por una de las recompensas de tu
catálogo.
### Vuelve
La recompensa y el progreso hacia la próxima lo traen de nuevo. La compra se
vuelve un hábito.
## Saldo de puntos
El saldo de un cliente es el resultado de sumar todos los puntos que ganó
(que no estén vencidos) y restar todos los que gastó en canjes. Esto
garantiza que el número sea siempre consistente con su historial real.
## Multicanal
Una misma marca puede operar su club en negocios físicos (app PWA con tu
marca) y en su tienda online (integrado al checkout). Las reglas de puntos
y el catálogo de recompensas se comparten: el cliente vive una sola experiencia,
sin importar por dónde compre.
# Fundamentos (https://docs.loybox.com.ar/es-419/puntos-y-premios)
El sistema de puntos y recompensas es el motor de tu club: los clientes
acumulan puntos con cada compra y los canjean por las recompensas de tu marca.
Es la mecánica que transforma una compra suelta en una relación que vuelve.
## De un vistazo
## El flujo, punta a punta
### Configuras las reglas
Defines cuántos puntos vale cada compra y (opcionalmente) cuándo vencen.
### Armas el catálogo de recompensas
Creas las recompensas con su costo en puntos, límite de canjes y vigencia.
### El cliente acumula
Cada compra suma puntos a su saldo automáticamente.
### El cliente canjea
Cambia sus puntos por una recompensa y tu equipo la valida con un código.
Cada marca define sus propias reglas de puntos, sus modos de vencimiento y
su catálogo de recompensas. Nada está fijo: el sistema se adapta a cómo quieres
premiar a tus clientes.
# Ganar puntos (https://docs.loybox.com.ar/es-419/puntos-y-premios/ganar-puntos)
Cada compra genera puntos automáticamente. Cómo se traduce el monto de la
compra en puntos lo defines tú.
## La regla principal: dinero por punto
La forma más directa de configurar tu programa es definir cuánto dinero
equivale a un punto. Con esa regla, el cálculo es:
```
puntos = piso( monto de la compra ÷ dinero por punto )
```
Si configuras 100 = 1 punto, una compra de 1.750 otorga
17 puntos (1750 ÷ 100 = 17,5, redondeado hacia abajo). Los centavos que
sobran no se pierden: quedan para la próxima compra en la práctica, porque
siempre se calcula sobre el monto real.
Es un solo valor para ajustar: bajas el "dinero por punto" para que los puntos
se acumulen más rápido, o lo subes para que cuesten más.
## Conversión automática por moneda
Si no defines una regla de dinero por punto, Loybox usa una conversión por
defecto según la moneda de tu marca, para que todo funcione desde el primer
día:
| Moneda | Regla por defecto |
| -------------------- | ------------------------------------------------------------------------------- |
| Euro (EUR) | 50 puntos por cada € |
| Peso mexicano (MXN) | 1 punto cada 50 MXN |
| Resto de las monedas | Se convierte el monto a dólares (cotización MEP) y se otorgan 50 puntos por USD |
La cotización del dólar MEP se actualiza automáticamente de forma periódica,
así que las monedas que dependen de ella siempre usan un valor al día. En
cuanto defines tu propia regla de "dinero por punto", esta conversión deja de
aplicar.
## Multiplicadores
Sobre el cálculo base, dos ajustes pueden aumentar los puntos de una compra:
Primero se calcula el punto base (según tu regla de dinero por punto o la
conversión por moneda), después se aplican los puntos dobles si están activos
y, por último, el bono porcentual del nivel del cliente. El bono de nivel se
aplica según el nivel que el cliente tiene en el momento de la compra.
## Otras formas de sumar puntos
La compra es la fuente principal, pero no la única. Loybox puede otorgar
puntos también por:
# Vencimiento de puntos (https://docs.loybox.com.ar/es-419/puntos-y-premios/expiracion)
El vencimiento de puntos es una herramienta para generar urgencia: un
saldo que vence es un motivo para volver antes de perderlo. Loybox te deja
elegir cómo funciona, o desactivarlo por completo.
## Los tres modos
## El período de vencimiento
Cuando activas el vencimiento, defines un período en días. Los puntos de
una compra vencen una vez transcurrido ese período desde que se ganaron.
El vencimiento sólo se aplica si el modo es "acumulado" o "por transacción"
y el período de días es mayor que cero. Con el período en cero, los puntos
no vencen aunque el modo esté activo.
## Acumulado vs. por transacción
La diferencia clave es qué pasa cuando el cliente vuelve a comprar:
Acumulado premia la constancia y es más amable: sólo pierde puntos quien
se va del todo. Por transacción empuja a canjear seguido. Si recién
empiezas y no quieres fricción, arranca sin vencimiento y suma una regla más
adelante.
## Cómo lo ve el cliente
Los puntos vencidos simplemente dejan de contar para el saldo: no se "borran"
del historial, sino que no se suman cuando se calcula cuántos puntos tiene
disponibles el cliente. Así, el saldo que ve siempre es el saldo que puede
usar.
# Recompensas (https://docs.loybox.com.ar/es-419/puntos-y-premios/premios)
Las recompensas son lo que tus clientes obtienen a cambio de puntos.
Tu catálogo es lo que le da sentido a acumular: cuanto más deseable
sea, más fuerte es el incentivo para volver.
Sigue la guía paso a paso: [Crear una recompensa](https://docs.loybox.com.ar/puntos-y-premios/crear-un-premio).
## Qué configuras en una recompensa
Cada recompensa se define con un puñado de campos:
No hace falta escribir un título ni una descripción: el texto que ve el cliente
se genera automáticamente a partir del tipo y el valor que eliges. Menos
campos, menos fricción.
## Tipos de recompensa
Una recompensa puede entregar distintas cosas:
## El estado de una recompensa
En cada momento, una recompensa está en uno de estos estados según su
configuración:
| Estado | Qué significa |
| ------------ | -------------------------------------- |
| **Activo** | Disponible para canjear. |
| **Inactivo** | Pausado manualmente desde el catálogo. |
| **Vencido** | Pasó su fecha de vencimiento. |
| **Agotado** | Alcanzó su límite total de canjes. |
Sólo las recompensas activas (vigentes, con canjes disponibles y sin pausar)
aparecen para que el cliente las canjee.
## Recompensas para ocasiones especiales
Además de las recompensas del catálogo general, puedes reservar algunas para
momentos concretos del recorrido del cliente:
# Crear una recompensa (https://docs.loybox.com.ar/es-419/puntos-y-premios/crear-un-premio)
Crear una recompensa toma menos de un minuto. En esta guía lo hacemos de punta a
punta desde el panel.
## Paso a paso
### Entra a **Premios**
En el menú lateral, dentro de **Fidelización**, toca **Premios**. Vas a ver tu
**Catálogo de premios**.
### Toca **Nuevo premio**
El botón está arriba a la derecha del catálogo. Se abre una ventana para
armar la recompensa. (Si todavía no tienes ninguna, el botón dice **Crear premio**.)
### Elige el **Tipo de premio**
En el desplegable **Tipo de premio**, elige qué va a recibir el cliente:
| Tipo | Qué entrega |
| ---------------------------- | ------------------------------------------------ |
| **Producto gratis** | Un producto de tu catálogo, sin costo. |
| **Vale de dinero ($)** | Un monto fijo de descuento. |
| **Descuento porcentual (%)** | Un porcentaje de descuento. |
| **2x1** | Una promoción dos por uno. |
| **Envío gratis** | El envío sin costo. |
| **Otro** | Cualquier beneficio que definas con texto libre. |
### Completa el valor de la recompensa
Según el tipo, aparece un campo distinto:
* **Vale de dinero** → **Monto del vale ($)** (por ejemplo, `10.000`).
* **Descuento porcentual** → **Porcentaje de descuento** (de 1 a 100).
* **Producto gratis**, **2x1** u **Otro** → un campo **Detalle** para describirlo
(hasta 40 caracteres).
* **Envío gratis** → no necesita valor.
En los tipos con monto o porcentaje puedes sumar un **Detalle (opcional)** para
afinar el texto que ve el cliente (por ejemplo, “en tu próxima compra”).
### Sube una imagen *(opcional)*
En **Imagen del premio (opcional)** puedes subir una foto (PNG, JPG o WEBP, hasta
5 MB). Si no subes ninguna, Loybox usa un ícono según el tipo de recompensa.
### Pon el **Precio (puntos)**
Es cuántos puntos cuesta canjear la recompensa. Es obligatorio y tiene que ser
mayor a cero: hasta que lo completes, el botón de guardar queda deshabilitado.
### Ajusta los límites *(opcional)*
* **Límite de canjes (opcional)**: cuántas veces puede canjearse en total.
Déjalo en `0` para que sea ilimitado.
* **Vencimiento (opcional)**: la fecha hasta la que está disponible.
* **Otras restricciones (opcional)**: una aclaración libre (por ejemplo,
“No acumulable con otras promociones”).
### Revisa la **Vista previa**
A un costado vas a ver una **Vista previa** que muestra la recompensa tal como la
verá el cliente en su app, y se actualiza a medida que completas los campos.
### Toca **Crear premio**
Listo: la recompensa se guarda y aparece en tu **Catálogo de premios**, disponible
para canje. Puedes crear todas las que quieras.
## Dos cosas que conviene saber
No hay un campo de nombre ni de descripción. El título y el texto de la recompensa
se generan automáticamente a partir del tipo y el valor que eliges, y puedes
verlos en la vista previa.
No hay un interruptor de “activo” al crear. Si la recompensa está disponible,
agotada o vencida surge de su configuración (precio, límite de canjes y
vencimiento). Puedes ver el estado de cada una en el catálogo.
## Si tienes Tiendanube conectado
Si tu tienda de Tiendanube está conectada, al crear una recompensa aparece un
interruptor **Cupón Tiendanube**. Al activarlo, la recompensa genera un cupón
real en tu tienda cuando el cliente la canjea, y eliges el **Tipo de cupón**
(descuento porcentual, monto fijo, envío gratis o producto gratis) y, según el
caso, la **Categoría** a la que aplica.
Con el cupón de Tiendanube activado, la recompensa usa la configuración del cupón
en lugar de la imagen y el detalle libres. Es la opción ideal para que el
canje se aplique solo en el checkout de tu tienda online.
# Canje (https://docs.loybox.com.ar/es-419/puntos-y-premios/canje)
El canje es el momento en que los puntos se convierten en valor real para el
cliente. Loybox lo maneja de punta a punta: descuenta los puntos, le entrega
la recompensa y le da a tu equipo una forma simple de validarla.
## El flujo, paso a paso
### El cliente elige una recompensa
Desde la app ve el catálogo de recompensas disponibles y cuánto cuesta cada una en
puntos.
### Loybox valida el saldo
El canje sólo procede si el cliente tiene puntos suficientes para cubrir el
costo de la recompensa. Si no llega, se le avisa cuántos le faltan.
### Se descuentan los puntos
Al confirmar, se registra el canje y el costo de la recompensa se resta del saldo.
El cliente queda con la recompensa a su nombre y un código de validación.
### Tu equipo valida el código
En el negocio (o en el checkout de tu tienda), tu equipo ingresa el código para
confirmar la recompensa y marcarla como usada.
## El código de validación
Cada recompensa canjeada lleva un código corto y único que el cliente presenta
al momento de usarla.
El código está asociado a tu marca y a ese canje puntual. Tu equipo lo
busca, confirma que está pendiente de uso y lo marca como utilizado. Una vez
usado, no se puede volver a validar: evita que la misma recompensa se use dos
veces.
## Canje y saldo
Recuerda que el saldo del cliente se calcula: siempre es la suma de los
puntos ganados vigentes menos los canjeados. Por eso, apenas se registra un
canje, el saldo baja de forma consistente, sin ajustes manuales.
## Vigencia de la recompensa canjeada
Una recompensa ya canjeada mantiene la fecha de vigencia de la original: el
cliente la tiene reservada, pero debe usarla antes de que venza. Esto
mantiene el catálogo sano y evita recompensas "eternas" acumuladas sin usar.
# Fundamentos (https://docs.loybox.com.ar/es-419/niveles)
Los niveles son la herramienta con la que reconoces a tus mejores clientes:
a medida que consumen, avanzan de un nivel al siguiente y acceden a mejores
beneficios. Es una forma de premiar la lealtad sostenida, más allá de cada
compra puntual.
## Qué es un nivel
Un nivel es un escalón dentro de tu club. A medida que el cliente consume,
avanza de un nivel al siguiente y desbloquea mejores beneficios. Cada nivel
tiene:
## El nivel base
Todo cliente que se suma a tu club entra en el nivel base (el primer
escalón, sin requisitos). Desde ahí empieza a escalar. El nivel base siempre
existe y no vence: es el punto de partida de todos.
## Cómo funciona, de un vistazo
### El cliente se suma
Entra automáticamente en el nivel base.
### Acumula y avanza
Con cada compra suma hacia el umbral del próximo nivel. Al alcanzarlo, sube.
### Desbloquea beneficios
Cada nivel mejora lo que recibe: más puntos por compra, recompensas exclusivas y
reconocimiento.
### Mantiene su estatus
Mientras siga activo, conserva (y sigue subiendo) su nivel.
Además del valor de los beneficios, alcanzar un nivel funciona como un logro:
mantenerlo y seguir subiendo es un motivo concreto para que el cliente vuelva.
# Cómo suben de nivel (https://docs.loybox.com.ar/es-419/niveles/como-suben-de-nivel)
Cada nivel tiene un umbral: lo que el cliente necesita acumular para
alcanzarlo. Tú eliges en qué se mide ese umbral.
## Dos formas de medir el avance
Cada nivel se mide con su propio criterio, así que puedes combinar ambos dentro
de la misma escalera si tiene sentido para tu marca.
## Se mide sobre el historial completo
Este es el punto clave: el avance se calcula sobre lo que el cliente
acumuló a lo largo de toda su relación con tu marca, no sobre su saldo
actual.
Cuando un cliente gasta sus puntos en una recompensa, su saldo baja, pero su
nivel no. El nivel refleja todo lo que ganó o gastó de por vida, así que
canjear nunca lo hace retroceder. Puede disfrutar sus recompensas sin miedo a
perder su estatus.
## Cómo se calcula el nivel
Después de cada compra, Loybox revisa el historial del cliente y lo ubica en
el nivel más alto cuyo umbral ya alcanzó. Si con esa compra cruzó el
umbral del siguiente escalón, sube en el momento.
Un nivel superior nunca puede tener un umbral más bajo que uno inferior. La
escalera va de menor a mayor exigencia, de forma que subir siempre signifique
avanzar de verdad.
# Beneficios de cada nivel (https://docs.loybox.com.ar/es-419/niveles/beneficios-de-nivel)
Cada nivel puede mejorar lo que el cliente recibe de tres formas.
## Multiplicador de puntos
Cada nivel puede otorgar un porcentaje extra de puntos en cada compra. Es
la recompensa que más se nota, porque acelera todo el resto.
El multiplicador es un bono porcentual: 0 % = sin bono, 10 % = +10 %,
100 % = el doble de puntos. Un cliente “Oro” con +20 % que hace una compra
de 100 puntos, se lleva 120.
Se aplica según el nivel que el cliente tiene en el momento de la compra, y
sólo mientras ese nivel esté activo. Es un motivo concreto para escalar: cuanto
más alto el nivel, más rápido crece el saldo.
## Recompensa al alcanzar el nivel
Puedes otorgar una recompensa de bienvenida cada vez que un cliente sube a un
nivel: un empujón de puntos, un beneficio exclusivo, un regalo. Es el momento
de mayor entusiasmo del cliente, y conviene reconocerlo.
La recompensa de bienvenida a un nivel se da una única vez por cliente, la
primera vez que lo alcanza. Aunque más adelante baje y vuelva a subir, no se
repite.
## Recompensas exclusivas del nivel
Además de la recompensa de llegada, un nivel puede tener recompensas que sólo
disfrutan quienes están en él:
## Más allá de los puntos
Un nivel no tiene por qué basarse sólo en más puntos. También puedes sumar
beneficios que no dependen de un descuento:
Una buena práctica es usar el multiplicador de puntos para acelerar la
acumulación y los beneficios exclusivos para que cada nivel se distinga del
anterior. Así el progreso se nota tanto en el saldo como en la experiencia.
# Vencimiento y descenso (https://docs.loybox.com.ar/es-419/niveles/vencimiento-de-niveles)
Un nivel puede ser para siempre o algo que hay que mantener. Las dos
opciones son válidas; sirven para cosas distintas.
## Niveles que se mantienen
Puedes darle a un nivel una vigencia en días. Si el cliente lo alcanza y
después deja de tener actividad durante ese período, baja un escalón. De
esta forma el nivel se mantiene con actividad, en lugar de conservarse para
siempre tras alcanzarlo una vez.
Cuando un nivel vence, el cliente no cae hasta abajo: baja un solo nivel, y
el reloj vuelve a arrancar desde ahí. El descenso es gradual y siempre da
margen para reaccionar.
## Se puede volver a subir
El descenso responde a la inactividad, no a un castigo permanente. Como el
avance se calcula sobre el historial completo del cliente, si vuelve a comprar
y su acumulado todavía alcanza para el nivel superior, vuelve a subir en la
siguiente compra. En la práctica, el vencimiento sólo “pega” en quienes se
alejaron del todo.
## Dónde aplica
El vencimiento sólo tiene sentido en los niveles VIP (los que están por encima
del base) medidos por puntos. El nivel base (el punto de partida de todos)
no vence nunca: nadie queda afuera del club por inactividad.
## Cuándo conviene
Un período demasiado corto puede hacer que un cliente pierda el nivel por una
pausa normal entre compras. Conviene empezar con un plazo holgado y ajustarlo
según la frecuencia de compra real de tus clientes.
# Arma tus niveles (https://docs.loybox.com.ar/es-419/niveles/armar-tus-niveles)
Diseñar tus niveles es definir la escalera de tu club: cuántos hay, qué se pide
para subir y qué ofrece cada uno. No hay una fórmula única, pero sí buenas
prácticas. Esta es la guía.
## Los pasos
### Define el nivel base
Es el escalón de entrada, sin requisitos: todos empiezan ahí. No lleva umbral
ni vencimiento.
### Agrega tus niveles VIP
Crea los escalones que van por encima. Para la mayoría de las marcas, tres a
cuatro niveles en total es el punto justo: suficientes para dar progreso,
sin volverse confusos.
### Elige cómo se mide cada uno
Define si el umbral es por puntos acumulados o por monto gastado, y el
valor a alcanzar. Recuerda: cada nivel superior debe pedir más que el anterior.
### Carga los beneficios
Para cada nivel, define el multiplicador de puntos, la recompensa al alcanzarlo y
las recompensas exclusivas. Que cada escalón se sienta mejor que el anterior.
### Ponle nombre e ícono
El nombre comunica estatus (Plata, Oro, Platino… o algo propio de tu marca) y
el ícono lo hace visible en la app.
## Reglas que conviene tener en cuenta
## Niveles propios o los de Loybox
Puedes usar una escalera de niveles propia, diseñada a la medida de tu marca, o
partir de la configuración por defecto de Loybox para arrancar rápido.
Cuando defines tus propios niveles, tu marca usa esa escalera completa en lugar
de la predeterminada.
Un nombre descriptivo se entiende mejor que uno genérico: “Oro” comunica más
que “Nivel 3”. Elige una progresión clara y fácil de recordar.
## Un consejo para empezar
No hace falta lanzar con la escalera perfecta. Empieza con dos o tres niveles
claros, con beneficios genuinamente deseables, y ajusta con el tiempo según
cómo se mueven tus clientes reales entre escalones.
Sigue la guía paso a paso: [Crear un nivel](https://docs.loybox.com.ar/niveles/crear-un-nivel).
# Crear un nivel (https://docs.loybox.com.ar/es-419/niveles/crear-un-nivel)
Los niveles se arman como una escalera: primero el nivel base y después los
niveles que van por encima. En esta guía creamos uno de punta a punta desde el
panel.
## Paso a paso
### Entra a **Niveles**
En el menú lateral, dentro de **Fidelización**, toca **Niveles**.
### Toca **Nuevo nivel**
Se abre una ventana para configurar el nivel. Si todavía no tienes ninguno,
empieza por el nivel base (por ejemplo, *Bronce*): es el punto de partida de
todos los clientes.
### Pon el **Nombre**
El nombre que ve el cliente, por ejemplo *Oro*.
### Elige un **Ícono**
Busca y selecciona un ícono para el nivel. Es el distintivo visual que se
muestra en la app.
### Elige la **Métrica**
Cómo se mide el avance hacia el nivel:
* **Puntos**: por puntos acumulados.
* **Monto ($)**: por monto gastado.
### Define el **Umbral**
Cuánto necesita acumular el cliente para alcanzar el nivel (en puntos o en
dinero, según la métrica).
El nivel base no tiene umbral ni expiración: es el escalón de entrada, así
que estos campos no aparecen al configurarlo.
### Ajusta la **Expiración (días)** *(opcional)*
Si quieres que el nivel se mantenga con actividad, indica en cuántos días vence.
Déjalo vacío para que el nivel no venza.
### Carga los **Premios** del nivel
Puedes combinar los que quieras:
* **Multiplicador (%)**: el porcentaje extra de puntos por compra (0 = sin
bono, 10 = +10 %, 100 = el doble).
* **Puntos de regalo**: puntos que se otorgan una sola vez, al alcanzar el
nivel por primera vez.
* **Premios del catálogo**: recompensas existentes que se entregan al llegar al
nivel.
### Toca **Crear nivel**
El nivel se guarda y aparece en tu escalera de niveles.
## Ordenar los niveles
En la lista, arrastra los niveles para ordenarlos. El primero siempre es
el nivel base, y de ahí hacia arriba los umbrales tienen que ir de menor a
mayor.
## Tres cosas que conviene saber
Puntos o monto es una elección de toda la escalera, no de un nivel suelto. Si
cambias la métrica, se aplica a todos los niveles y los umbrales se
reinician a cero: revísalos antes de guardar.
Las recompensas exclusivas del nivel (al alcanzarlo o por evento, como
cumpleaños) se cargan una vez que el nivel está guardado. Crea el nivel
primero y después edítalo para sumarlas.
No hace falta lanzar con la escalera completa. Con el nivel base y dos o tres
niveles por encima alcanza para arrancar; siempre puedes sumar más y reordenar.
# Fundamentos (https://docs.loybox.com.ar/es-419/referidos)
Los referidos son la herramienta con la que tus propios clientes invitan a
gente nueva a tu club. Cuando un invitado hace su primera compra, tanto
quien invitó como el invitado ganan puntos.
Es un canal de adquisición en el que tus clientes hacen la recomendación por
ti, y la recompensa recién se paga cuando esa recomendación se convierte en una
compra real.
## Cómo funciona
### Activas el programa
Defines cuántos puntos se otorgan por cada referido efectivo.
### Cada cliente comparte su enlace
Desde su app, cada cliente tiene un enlace de invitación propio para
compartir con quien quiera.
### Un nuevo cliente se suma
La persona invitada abre el enlace y se suma a tu club.
### Ambos ganan puntos
Cuando ese invitado hace su primera compra, los puntos se acreditan a los
dos: a quien invitó y al invitado.
## Los puntos del referido
Configuras un solo valor: los mismos puntos se otorgan a quien invita y
al invitado. Se acreditan una sola vez, en la primera compra del invitado
(no al registrarse), de modo que la recompensa siempre acompaña a una venta real.
## Las reglas
Para que un referido sume, Loybox valida algunas condiciones:
# Activar los referidos (https://docs.loybox.com.ar/es-419/referidos/activar-referidos)
Activar los referidos toma menos de un minuto. Se configura desde la página de
**Premios**, junto al resto de las recompensas automáticas.
## Paso a paso
### Entra a **Premios**
En el menú lateral, dentro de **Fidelización**, toca **Premios**.
### Baja a **Premios especiales**
Debajo del catálogo vas a encontrar la sección **Premios especiales**, con las
recompensas automáticas.
### En **Invitar amigos**, toca **Configurar**
Es el recuadro que dice *“Cuando un amigo invitado compra por primera vez,
ambos ganan puntos.”* Si todavía no lo configuraste, aparece como
**Sin configurar**.
### Define los **Puntos para cada uno**
Ingresa cuántos puntos gana cada referido. Ese mismo valor se otorga a quien
invita y al invitado, cuando el invitado hace su primera compra.
### Toca **Guardar**
Listo: el programa queda activo y tus clientes empiezan a ganar puntos por
invitar.
## Editar o desactivar
El valor que cargas es el mismo para ambas partes: no se configuran por
separado los puntos de quien invita y los del invitado.
# Fundamentos (https://docs.loybox.com.ar/es-419/resenas)
Las reseñas son la herramienta con la que Loybox le pide a tus clientes,
automáticamente y por WhatsApp, que dejen una reseña después de comprar. Sirve
para juntar prueba social: reseñas de tu negocio en Google y reseñas de tus
productos.
Las reseñas se apoyan en los pedidos de tu tienda online: la solicitud se
dispara cuando se entrega una compra. Por eso la herramienta requiere tu tienda
conectada.
## Los tipos de reseña
## Cómo funciona el pedido
### El cliente recibe su compra
El pedido de reseña se apoya en la entrega de una compra de tu tienda.
### Loybox espera la demora que definiste
Configuras cuántas horas esperar desde la entrega (por ejemplo, 24 = un día
después de recibir el pedido).
### Se envía la solicitud por WhatsApp
El cliente recibe el mensaje para reseñar tu negocio y/o los productos que
compró.
### El cliente responde
Deja su reseña: en Google, en tu propio sistema, o respondiendo el WhatsApp con
estrellas y un comentario (reseñas nativas).
## La reseña nativa
Cuando usas las reseñas nativas de Loybox, el cliente califica de 1 a 5
estrellas y puede dejar un comentario opcional, todo dentro de la
conversación de WhatsApp. Loybox guarda esas reseñas y las marca como
verificadas, porque provienen de una compra real.
## Sin spam: la ventana de repetición
Para no cansar a tus clientes, Loybox no vuelve a pedir la misma reseña una y
otra vez:
# Configurar reseñas (https://docs.loybox.com.ar/es-419/resenas/configurar-resenas)
Configurar las reseñas es cuestión de activar lo que quieras usar. Los cambios
se guardan solos a medida que los haces.
La sección **Reseñas** requiere tu tienda online conectada, porque los pedidos
de reseña se disparan con la entrega de cada compra.
## Reseñas del negocio (Google)
### Entra a **Reseñas**
En el menú lateral, toca **Reseñas**.
### Activa **Pedir reseña en Google**
Con el interruptor encendido, después de cada compra se invita al cliente a
dejar una reseña de tu negocio en Google.
### Conecta tu ficha de Google
Busca y selecciona tu negocio. Hasta que lo elijas, Loybox no puede enviar el
pedido de reseña.
### Ajusta la **Demora del envío (horas)**
Cuántas horas esperar desde la entrega antes de pedir la reseña (por ejemplo,
`24` = un día después).
## Reseñas de productos
### Activa **Pedir reseña de productos**
Con esto, se le pide al cliente que reseñe los productos que compró.
### Elige el **Tipo de reseña**
### Ajusta la **Demora del envío (horas)**
Igual que en Google: cuánto esperar desde la entrega para pedir la reseña.
### Si elegiste **Externas**, carga los links
En la sección **Links de reseña por producto**, busca cada producto y pega su
link de reseña. Es lo que Loybox le va a mandar al cliente.
No hay un botón de guardar: cada cambio (interruptores, tipo de reseña, demora)
se aplica al instante. Puedes previsualizar cómo le llega el WhatsApp al cliente
en **Así le llega al cliente**.
# Fundamentos (https://docs.loybox.com.ar/es-419/recomendaciones)
Las recomendaciones son la herramienta con la que Loybox sugiere productos
relevantes a cada cliente en tu tienda online, usando IA. En lugar de armar
reglas producto por producto, el sistema aprende del catálogo y del
comportamiento de compra para mostrar el producto indicado en el momento
indicado.
Las recomendaciones funcionan sobre tu tienda online conectada: se muestran en
sus páginas (carrito, ficha de producto, checkout) y se envían por WhatsApp.
## Los tipos de recomendación
## Dónde aparecen
Eliges en qué puntos de la tienda se muestran:
## Recomendaciones por WhatsApp
Además de la tienda, las recomendaciones pueden llegar por WhatsApp en dos
momentos:
## Cómo se mide el impacto
Loybox atribuye las ventas que vienen de una recomendación: si el cliente
compra dentro de la ventana de atribución después de ver una sugerencia,
esa venta se cuenta como generada por las recomendaciones. Así puedes ver el
retorno real de la herramienta.
## Qué necesitas configurar
Muy poco: la IA hace el trabajo de elegir qué mostrar. Tú defines si está
activa, en qué lugares aparece y qué notificaciones enviar.
# Configurar recomendaciones (https://docs.loybox.com.ar/es-419/recomendaciones/configurar-recomendaciones)
La configuración está organizada en tres pestañas: **General**, **Ubicaciones**
y **Notificaciones**.
La sección **Recomendaciones** requiere tu tienda online conectada.
## General
### Entra a **Recomendaciones**
En el menú lateral, toca **Recomendaciones**.
### Activa **Recomendaciones activas**
Habilita el sistema de recomendaciones en toda la tienda.
### Ajusta **Upsell: % máximo más caro**
Cuando se sugiere un producto superior, hasta qué porcentaje más caro que el
producto base puede costar. Por ejemplo, `50%` sugiere productos de hasta un
50% más caros.
## Ubicaciones
En la pestaña **Ubicaciones** eliges en qué puntos de la tienda se muestran las
recomendaciones:
## Notificaciones
En la pestaña **Notificaciones** configuras los envíos por WhatsApp:
### Recomendación post-compra
Actívala para que, después de una compra, se le envíen al cliente productos que
combinan con lo que compró. Define la **Demora post-compra (horas)** para no
ser invasivo.
### Reactivación de inactivos
Actívala para enviarles recomendaciones a los clientes que dejaron de comprar.
Define los **Días para considerar inactivo** a partir de los cuales aplica.
### Ventana de atribución (horas)
Si el cliente compra dentro de esta ventana después de ver una recomendación,
esa venta se atribuye a la herramienta. Es lo que te permite medir el impacto.
## Guardar
Cuando termines, toca **Guardar configuración**. Los cambios quedan aplicados
en tu tienda.
# Fundamentos (https://docs.loybox.com.ar/es-419/carrito)
Las herramientas de carrito trabajan sobre el momento de la compra en tu
tienda online, con dos objetivos: recuperar las compras que quedaron a
medias y empujar el ticket con recompensas por monto.
Ambas herramientas requieren tu tienda online conectada.
## Dos herramientas
## Cuándo usar cada una
# Recuperar carritos abandonados (https://docs.loybox.com.ar/es-419/carrito/recuperar-carritos)
Cuando un cliente deja productos en el carrito y no compra, Loybox le puede
enviar recordatorios por WhatsApp para recuperar esa venta. Así se
configura.
## Paso a paso
### Entra a **Carrito**
En el menú lateral, toca **Carrito**. Arriba vas a ver **Carrito abandonado**.
### Activa los **Recordatorios**
Enciende **Recordatorios activos**. Con esto, si un cliente abandona su carrito,
le llega un recordatorio por WhatsApp.
### Define los tiempos de envío
En **Recordatorios (horas desde el abandono)** indicas cuántas horas después de
abandonar el carrito se envía cada recordatorio. Puedes poner varios: por
ejemplo, `1, 24, 72` = a la hora, al día y a los 3 días.
### Suma un cupón *(opcional)*
Si quieres dar un incentivo extra, agrega un cupón de descuento
(porcentaje sobre el total o monto fijo) y define su validez en
horas.
### Guarda
Los cambios quedan aplicados y los recordatorios empiezan a enviarse.
Los recordatorios viajan por WhatsApp, así que necesitas WhatsApp Business
conectado en Integraciones.
Con dos o tres alcanza. El primero, temprano (a la hora o al día), suele ser el
más efectivo; los siguientes sirven para reactivar a quien no respondió, sin
volverse molesto.
# Recompensas en el carrito (https://docs.loybox.com.ar/es-419/carrito/recompensas-en-carrito)
Las recompensas en el carrito son reglas que desbloquean un regalo cuando
la compra supera un monto. Sirven para empujar el ticket: “te falta poco para
tu regalo”. Así se crea una regla.
## Paso a paso
### Entra a **Carrito**
En el menú lateral, toca **Carrito**. Baja hasta la sección de recompensas.
### Toca **Nueva regla**
Se abre una ventana para configurar la regla.
### Pon un **Nombre**
Para identificarla en tu panel. Por ejemplo, *Regalo a partir de 20.000*.
### Define el **Monto mínimo del carrito**
El subtotal a partir del cual se desbloquea la recompensa.
### Elige el **Tipo de recompensa**
Según el tipo, completas el producto o el valor del descuento.
### Escribe el **Mensaje al cliente**
Es lo que ve en la tienda cuando desbloquea la recompensa (por ejemplo,
“¡Ya puedes acceder a tu regalo!”). Opcionalmente puedes definir el texto del
descuento en el checkout.
### Déjala **Activa** y toca **Crear regla**
Solo las reglas activas se aplican en la tienda. Puedes tener varias.
Pon el monto mínimo un poco por encima de tu ticket promedio: lo suficiente
para que el cliente sume un producto más, pero alcanzable como para que valga
la pena intentarlo.
# Fundamentos (https://docs.loybox.com.ar/es-419/segmentacion)
La segmentación agrupa automáticamente a tus clientes según sus patrones de
compra, para que sepas quién es quién en tu base y puedas accionar distinto con
cada grupo. Loybox arma los segmentos por ti: no hay que definir reglas a
mano.
La segmentación se calcula sobre los pedidos de tu tienda online conectada.
## Cómo se arma: el modelo RFM
Cada cliente se clasifica según tres señales de su comportamiento de compra:
Combinando estas tres señales, Loybox ubica a cada cliente en un segmento
con una persona y un insight que explican quiénes son y qué conviene hacer.
## Los segmentos
Los segmentos siguen el estándar RFM. Algunos de los más comunes:
| Segmento | Quiénes son |
| ---------------------- | ---------------------------------------------------------------- |
| **Champions** | Tus mejores clientes: compran seguido, hace poco y gastan mucho. |
| **Leales** | Clientes habituales y constantes. |
| **Leales en potencia** | Compradores recientes con buen ritmo, camino a ser leales. |
| **Necesitan atención** | Buenos clientes que empezaron a espaciar sus compras. |
| **En riesgo** | Solían comprar y se están alejando. |
| **Hibernando** | Hace tiempo que no compran. |
| **Perdidos** | Dejaron de comprar hace mucho. |
Cada segmento muestra su regla RFM, cuántos clientes agrupa, su peso en la
base y en las ventas, y promedios de recencia, frecuencia y ticket.
## Además: la salud de tu negocio
El panel también resume el estado general de tu base con métricas clave:
# Usar tus segmentos (https://docs.loybox.com.ar/es-419/segmentacion/usar-tus-segmentos)
La segmentación no es solo un diagnóstico: sirve para accionar distinto con
cada grupo de clientes. Así se usa el panel.
## Paso a paso
### Entra a **Segmentación**
En el menú lateral, toca **Segmentación**.
### Revisa la salud de tu negocio
Arriba vas a ver el diagnóstico general y los KPIs (clientes activos, órdenes,
ticket promedio, repeat rate y la concentración del top 20%).
### Explora cada segmento
Cada segmento se muestra como una tarjeta con su persona, su insight,
cuántos clientes agrupa y sus promedios (recencia, frecuencia, ticket) y la
regla RFM que lo define.
### Mira los clientes de un segmento
Abre un segmento para ver la lista de clientes que lo componen. Puedes ordenarla
por mayor o menor monto gastado, más o menos compras y por fecha de
compra (más antigua o más reciente).
### Acciona con una campaña
Desde un segmento puedes lanzar una campaña por WhatsApp dirigida a ese
grupo, para hablarle distinto a cada tipo de cliente.
Para crear campañas por WhatsApp necesitas tener WhatsApp Business conectado
en Integraciones.
## Cómo pensar cada segmento
La gracia está en tratar a cada grupo según lo que necesita:
La segmentación se recalcula de forma periódica, así que los grupos se
mantienen al día a medida que cambian los hábitos de tus clientes.
# Fundamentos (https://docs.loybox.com.ar/es-419/campanas)
Las campañas te permiten enviar un mensaje a un grupo de clientes por
WhatsApp o correo. Se apoyan en la [segmentación](https://docs.loybox.com.ar/segmentacion): en vez
de escribirle a toda tu base, le hablas distinto a cada grupo según su
comportamiento.
El punto de partida de una campaña es un segmento: se lanzan desde el
detalle de un segmento en **Segmentación**. Así la audiencia queda definida por
el comportamiento de compra.
## Cómo funciona
### Eliges la audiencia
Un segmento (por ejemplo, *En riesgo*) o un cliente individual.
### Eliges el canal
WhatsApp o correo, según cómo quieras llegar.
### Escribes el mensaje
Con variables de personalización como `{{first_name}}` para que cada cliente lo
reciba con su nombre.
### Programas o envías
Eliges fecha y hora, o lo envías en el momento.
### Sigues los resultados
Cada campaña muestra su estado y sus métricas.
## Los estados de una campaña
| Estado | Qué significa |
| -------------- | ------------------------------------ |
| **Borrador** | En preparación, todavía no se envió. |
| **Programada** | Con fecha y hora de envío agendadas. |
| **Enviando** | En proceso de envío. |
| **Enviada** | Ya salió a la audiencia. |
| **Cancelada** | Se detuvo antes de enviarse. |
| **Falló** | Hubo un problema en el envío. |
## Personalización
Los mensajes admiten variables que se completan con los datos de cada
cliente (por ejemplo `{{first_name}}`), de modo que un mismo mensaje llega
personalizado a cada persona.
Para enviar por WhatsApp necesitas WhatsApp Business conectado en
Integraciones.
# Crear una campaña (https://docs.loybox.com.ar/es-419/campanas/crear-una-campana)
Las campañas se crean a partir de un segmento, así que arrancan en la
sección **Segmentación**. Así se hace de punta a punta.
## Paso a paso
### Abre un segmento en **Segmentación**
Entra a **Segmentación** y abre el segmento al que le quieres hablar (por
ejemplo, *En riesgo* o *Champions*).
### Crea la campaña para ese grupo
Desde el detalle del segmento, inicia una campaña. La audiencia queda
definida por ese segmento.
### Elige el canal
WhatsApp o correo. Para usar WhatsApp necesitas tener
[WhatsApp Business conectado](https://docs.loybox.com.ar/integraciones/whatsapp) en Integraciones.
### Escribe el **Mensaje**
Redacta el texto. Usa variables como `{{first_name}}` para personalizarlo con
el nombre de cada cliente.
### Previsualiza
Revisa cómo va a llegar el mensaje antes de enviarlo.
### Programa el envío
En **Fecha y hora**, elige cuándo sale (tiene que ser a futuro) y toca
**Programar envío**. También puedes guardarla como borrador.
### Sigue los resultados
En **Campañas** vas a ver todas tus campañas con su estado (Borrador,
Programada, Enviando, Enviada…) y sus métricas.
La ventaja de partir de un segmento es poder ajustar el tono: a los
*Champions* agradecerles y premiarlos; a los *En riesgo* darles un motivo
concreto para volver. El mismo esfuerzo rinde más cuando el mensaje encaja con
quién lo recibe.
# Integraciones (https://docs.loybox.com.ar/es-419/integraciones)
Loybox se conecta con las herramientas que ya usas para que tu programa de
lealtad funcione sin fricción: tu tienda online, WhatsApp y tu marketing
por correo. Todas las integraciones se gestionan desde la sección
**Integraciones** del panel.
## Disponibles
Muchas herramientas de Loybox, como las reseñas y las recomendaciones,
se apoyan en tu tienda online conectada. Conectar Tiendanube es el primer paso
para aprovecharlas.
# Tiendanube (https://docs.loybox.com.ar/es-419/integraciones/tiendanube)
La integración con Tiendanube conecta tu tienda online con Loybox. Es la
base de la mayoría de las herramientas: los pedidos, los productos y los
clientes de tu tienda se sincronizan automáticamente.
## Qué habilita
## Cómo conectarla
### Entra a **Integraciones**
En el menú lateral del panel, abre **Integraciones**.
### En **Tiendanube**, toca **Conectar**
Te redirige a Tiendanube para autorizar la conexión con tu tienda.
### Autoriza el acceso
Confirma el permiso en Tiendanube. Al volver, la tienda queda conectada y
empieza la sincronización.
Conectar Tiendanube es el primer paso para usar puntos automáticos, canje en el
checkout, reseñas y recomendaciones.
# WhatsApp Business (https://docs.loybox.com.ar/es-419/integraciones/whatsapp)
La integración con WhatsApp Business le permite a Loybox enviar mensajes a
tus clientes por WhatsApp: notificaciones de puntos, pedidos de reseña,
recomendaciones y campañas.
## Qué habilita
## Cómo conectarla
### Entra a **Integraciones**
En el panel, abre la sección **Integraciones**.
### En **WhatsApp Business**, toca **Conectar**
Se abre el flujo de Meta para vincular tu cuenta de WhatsApp Business.
### Completa la conexión con Meta
Sigue los pasos de Meta para autorizar. Al terminar, WhatsApp Business queda
conectado.
La conexión se hace a través de Meta (Facebook), el proveedor oficial de la API
de WhatsApp Business.
# Perfit (https://docs.loybox.com.ar/es-419/integraciones/perfit)
La integración con Perfit sincroniza los contactos de tu club con tu cuenta
de Perfit, para que puedas sumar el marketing por correo a tu estrategia de
lealtad.
## Qué habilita
## Cómo conectarla
### Entra a **Integraciones**
En el panel, abre la sección **Integraciones**.
### En **Perfit**, toca **Conectar**
Vincula tu cuenta de Perfit siguiendo los pasos en pantalla.
### Listo
Al conectarse, Loybox empieza a sincronizar tus contactos con Perfit.
# Referencia técnica (https://docs.loybox.com.ar/es-419/referencia-tecnica)
Esta página resume, en un solo lugar, cómo funciona Loybox a nivel técnico:
las entidades, las fórmulas y las reglas que gobiernan cada mecanismo. Cada
sección enlaza a la guía correspondiente si necesitas el detalle completo.
## Entidades
Todo el modelo se apoya en cinco piezas ([Conceptos](https://docs.loybox.com.ar/conceptos)):
| Entidad | Qué representa |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Marca** | La empresa dentro de Loybox. Define moneda, reglas de puntos, catálogo de recompensas e identidad de la app. Puede tener una o varias sucursales. |
| **Cliente** | La persona sumada al club. Tiene una relación con la marca, con saldo de puntos e historial propios. |
| **Consumo** | El registro de una compra, en el negocio físico o en la tienda online. Es lo que dispara el cálculo de puntos. |
| **Punto** | La unidad de lealtad. Se gana con consumos y otras acciones, y se gasta canjeando recompensas. |
| **Recompensa** | Lo que el cliente obtiene a cambio de puntos. |
## Cálculo de puntos
La regla principal es dinero por punto
([Ganar puntos](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)):
```
puntos = piso( monto de la compra ÷ dinero por punto )
```
El redondeo es siempre hacia abajo. Con `100 = 1 punto`, una compra de `1.750`
otorga `17` puntos.
### Conversión por defecto según moneda
Si la marca no define una regla de dinero por punto, se aplica una conversión
por moneda:
| Moneda | Regla por defecto |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| Euro (EUR) | 50 puntos por cada € |
| Peso mexicano (MXN) | 1 punto cada 50 MXN |
| Resto | Se convierte a dólares (cotización MEP, actualizada periódicamente) y se otorgan 50 puntos por USD |
En cuanto la marca define su propia regla, esta conversión deja de aplicar.
### Orden de los multiplicadores
El orden importa, porque los ajustes se aplican en cascada:
### Punto base
Según la regla de dinero por punto, o la conversión por moneda.
### Puntos dobles
Si la promoción está vigente, duplica el resultado anterior.
### Bono porcentual del nivel
Se aplica al final, según el nivel que el cliente tiene en el momento de la
compra ([Beneficios de nivel](https://docs.loybox.com.ar/niveles/beneficios-de-nivel)).
### Otras fuentes de puntos
Además del consumo, otorgan puntos los referidos (al concretarse la primera
compra del invitado), el cumpleaños, la bienvenida al club y el hecho de
alcanzar un nivel por primera vez.
## Saldo
El saldo de un cliente es siempre `puntos ganados vigentes − puntos canjeados`.
No existe un contador persistido que haya que reconciliar, así que el número es
consistente con el historial real por construcción.
Los puntos vencidos no se borran del historial: dejan de sumar cuando se
calcula el saldo disponible.
## Vencimiento de puntos
Hay tres modos ([Vencimiento de puntos](https://docs.loybox.com.ar/puntos-y-premios/expiracion)):
| Modo | Comportamiento |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **Sin vencimiento** | Los puntos no vencen nunca. Es el modo por defecto. |
| **Acumulado** | Todo el saldo comparte una única fecha de vencimiento, que se renueva con cada compra nueva. |
| **Por transacción** | Los puntos de cada consumo vencen a su propio ritmo, sin importar las compras posteriores. |
El vencimiento se aplica sólo si el modo es `acumulado` o `por transacción`
y el período en días es mayor que cero. Con el período en cero, los puntos
no vencen aunque el modo esté activo.
## Niveles
El nivel de un cliente se resuelve por umbrales
([Cómo suben de nivel](https://docs.loybox.com.ar/niveles/como-suben-de-nivel)):
* Cada nivel se mide por puntos acumulados o por monto gastado, y cada
nivel puede usar su propio criterio dentro de la misma escalera.
* El avance se calcula sobre el historial completo de la relación, no sobre
el saldo actual. Por eso canjear nunca baja de nivel: el saldo baja, el
nivel no.
* Después de cada compra, el cliente queda en el nivel más alto cuyo umbral
ya alcanzó.
* Los umbrales son siempre crecientes: un nivel superior no puede exigir
menos que uno inferior.
El nivel base es el escalón de entrada: no tiene umbral ni expiración, y no
vence nunca ([Vencimiento y descenso](https://docs.loybox.com.ar/niveles/vencimiento-de-niveles)). El
vencimiento de niveles sólo aplica a los niveles VIP medidos por puntos.
## Recompensas
Una recompensa se define por tipo y valor, costo en puntos, límite de canjes,
vencimiento e imagen opcional ([Recompensas](https://docs.loybox.com.ar/puntos-y-premios/premios)). El texto
que ve el cliente se genera a partir del tipo y el valor.
Tipos: producto gratis, vale de dinero (`$`), descuento porcentual (`%`), 2x1,
envío gratis y libre (texto propio).
Estados posibles, derivados de la configuración:
| Estado | Condición |
| ------------ | ---------------------------------- |
| **Activo** | Disponible para canjear. |
| **Inactivo** | Pausado manualmente. |
| **Vencido** | Pasó su fecha de vencimiento. |
| **Agotado** | Alcanzó su límite total de canjes. |
Sólo las recompensas activas aparecen disponibles para el cliente. Un límite de
canjes en cero significa ilimitado.
## Canje
El flujo valida saldo antes de descontar ([Canje](https://docs.loybox.com.ar/puntos-y-premios/canje)):
### Validación de saldo
El canje procede sólo si el cliente cubre el costo en puntos de la recompensa.
### Descuento y emisión
Se registra el canje, el costo se resta del saldo y la recompensa queda a nombre
del cliente con un código de validación corto y único.
### Validación del código
El código está asociado a la marca y a ese canje puntual. Una vez marcado como
usado no puede volver a validarse, lo que evita el doble uso.
Una recompensa ya canjeada conserva la fecha de vigencia de la original.
## Segmentación
Los clientes se agrupan automáticamente con el modelo RFM
([Segmentación](https://docs.loybox.com.ar/segmentacion)), sobre tres señales: recencia (hace cuánto
compró), frecuencia (cuántas veces) y monto (cuánto gastó en total).
Los segmentos siguen el estándar RFM: Champions, Leales, Leales en potencia,
Necesitan atención, En riesgo, Hibernando y Perdidos. Cada uno expone su regla
RFM, su volumen de clientes, su peso en la base y en las ventas, y promedios de
recencia, frecuencia y ticket.
La segmentación se calcula sobre los pedidos de la tienda online conectada.
## Canales e integraciones
Una misma marca puede operar el club en negocios físicos (app PWA con su
marca) y en su tienda online (integrada al checkout). Las reglas de puntos
y el catálogo de recompensas se comparten entre canales.
Integraciones disponibles ([Integraciones](https://docs.loybox.com.ar/integraciones)): Tiendanube
(pedidos, productos y clientes), WhatsApp Business (notificaciones y
mensajes) y Perfit (sincronización de contactos para correo).
Las reseñas y las recomendaciones dependen de tener la tienda online conectada.
# Sobre la API (https://docs.loybox.com.ar/es-419/api-reference)
La API de Loybox sirve para lo mismo que el panel, pero desde tu código:
registrar compras que suman puntos, mostrar el catálogo de recompensas, canjear
códigos y consultar el estado de un cliente.
Es una API **REST sobre HTTPS**. Todo va y vuelve en JSON, los nombres de los
campos están en `snake_case` y las fechas en formato ISO 8601 con zona
horaria (`2026-03-14T18:30:00Z`).
## URL base
Todas las rutas de esta referencia cuelgan de:
```
https://loybox-public-api-752998171300.southamerica-west1.run.app
```
La versión va en el primer segmento de la ruta (`/v1/...`). Cuando un endpoint
cambia de forma no compatible aparece una versión nueva al lado de la anterior,
y la anterior sigue funcionando: es el caso de
[consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo) y su
[versión 2](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2).
## Los ejemplos
Cada página de endpoint trae la llamada entera en `curl`, lista para pegar en una
terminal. Tres cosas son variables y valen para todos los ejemplos:
| En el ejemplo | Qué poner |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `$LOYBOX_API_KEY` | Tu [API key](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio). Expórtala en el ambiente, no la pegues en el comando. |
| `$ACCESS_TOKEN` | El [token del usuario](https://docs.loybox.com.ar/api-reference/credenciales#token-del-usuario-final) que devolvió el login. |
| `X-Commerce-Id: 87` | El id de **tu** comercio. |
## Formato de máquina
La API también está publicada como especificación, para generar un cliente en
lugar de escribirlo:
```
https://docs.loybox.com.ar/openapi.json
```
Es OpenAPI 3.1 y cubre los 25 endpoints, los esquemas de respuesta y las dos
credenciales. Si estás integrando con la ayuda de un agente, pásale esa URL.
## Las dos formas de integrarse
Esta es la decisión más importante y conviene tomarla antes de escribir código,
porque cambia la credencial, los endpoints disponibles y dónde corre tu código.
Cada sección de esta referencia usa una de las dos, y cada página de endpoint lo
dice arriba:
| Sección | Credencial | Para qué |
| --------------------------------------------- | ----------------- | --------------------------------------------- |
| [Consumos](https://docs.loybox.com.ar/api-reference/consumos) | API key | Registrar compras que suman puntos |
| [Clientes](https://docs.loybox.com.ar/api-reference/clientes) | API key | Consultar clientes y sus beneficios |
| [Beneficios](https://docs.loybox.com.ar/api-reference/beneficios) | API key | Catálogo, consulta de códigos y canje |
| [Autenticación](https://docs.loybox.com.ar/api-reference/autenticacion) | — | Inicio de sesión del usuario final por correo |
| [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) | Token del usuario | Puntos, canjes e historial del usuario |
| [Público](https://docs.loybox.com.ar/api-reference/publico) | — | Marca y catálogo, sin inicio de sesión |
La API key del comercio da acceso a los datos de **todos** tus clientes. Vive
sólo en tu servidor. Lo que sí puede vivir en el navegador es el token de acceso
del usuario final, que sólo ve lo suyo.
## Cómo se ven las respuestas
Las respuestas no llevan sobre: el objeto viene en la raíz, y los listados
vienen como array directo.
```json
// GET /v1/clients/12345
{
"code": 12345,
"username": "Ana Pérez",
"email": "ana@example.com",
"points": 340
}
```
Los campos opcionales vienen presentes y en `null`, no ausentes. Puedes leerlos
sin chequear si existen, pero sí hay que revisar si son `null`.
## Paginación
Hay dos esquemas, y cada uno vive en un solo endpoint:
### Límite y desplazamiento
[Listar clientes](https://docs.loybox.com.ar/api-reference/clientes/listar) usa `limit` y `offset`, y
devuelve el total para que puedas armar los números de página.
```json
// GET /v1/clients/list?limit=20&offset=40
{
"items": [],
"total": 1875,
"limit": 20,
"offset": 40
}
```
`limit` va de 1 a 100 y por defecto es 20. `offset` arranca en 0.
### Cursor
[Mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial) usa cursor, porque es una
lista que crece por arriba y los números de página se desacomodan. Se pide la
página siguiente pasando el `next_cursor` de la respuesta anterior en `?cursor=`.
```json
// GET /v1/me/activity
{
"results": [],
"next_cursor": "eyJkIjoiMjAyNi0wMy0xNCJ9",
"previous_cursor": null
}
```
Cuando `next_cursor` viene en `null`, no hay más páginas.
## Por dónde empezar
# Primeros pasos (https://docs.loybox.com.ar/es-419/api-reference/primeros-pasos)
Esta página es la integración completa de punta a punta. Si vienes a implementar
y quieres leer una sola página antes de escribir código, es esta.
Hay **dos caminos** y no son excluyentes: casi todas las integraciones empiezan
por el primero y agregan el segundo cuando quieren que el cliente vea sus puntos
por su cuenta.
| Camino | Qué resuelve | Credencial |
| ------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [Desde tu servidor](#camino-1-sumar-puntos-desde-tu-servidor) | Que las compras sumen puntos y que los códigos se canjeen en la venta | [API key](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio) |
| [Desde tu frontend](#camino-2-el-club-en-tu-frontend) | Que el cliente vea sus puntos, canjee y muestre su código | [Token del usuario](https://docs.loybox.com.ar/api-reference/credenciales#token-del-usuario-final) |
## Antes de empezar
Necesitas dos cosas, y las dos te las damos nosotros: escríbenos a
[hola@loybox.com.ar](mailto:hola@loybox.com.ar).
La API key del comercio. Va sólo en tu servidor.
El id de tu comercio. Es el que viaja en el header `X-Commerce-Id` y puede
ir en el frontend.
Los ejemplos de aquí en adelante usan las
[convenciones de la referencia](https://docs.loybox.com.ar/api-reference#los-ejemplos): `$LOYBOX_API_KEY`
para la API key, `$ACCESS_TOKEN` para el token del usuario y `87` como
`commerce_id`.
## Camino 1: sumar puntos desde tu servidor
Es la integración mínima de un programa de lealtad: una sola llamada, en el
lugar donde tu sistema confirma una venta.
### Registra la compra
En el checkout online ya tienes el correo, así que
[por correo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-email) es el camino corto: funciona
incluso si el cliente todavía no tiene cuenta en Loybox.
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/consumptions/email \
-H "Authorization: Bearer $LOYBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_email": "ana@example.com",
"amount": 1750
}'
```
En un punto de venta físico, donde el cliente da su número, es la misma llamada
[por código](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo) con `client_code`.
`amount` son unidades enteras de la moneda del comercio. Una compra de
`1.750,50` se manda como `1750`.
Cuántos puntos suma no lo decide tu llamada: lo decide la configuración del
comercio. Mandas el monto y Loybox aplica la regla de dinero por punto, los
puntos dobles si están vigentes y el bono del nivel, en ese orden
([la fórmula](https://docs.loybox.com.ar/referencia-tecnica#cálculo-de-puntos)).
### Muéstrale el saldo
La respuesta del consumo no dice cuántos puntos sumó. El saldo se
[consulta aparte](https://docs.loybox.com.ar/api-reference/clientes/obtener):
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
Con esto ya tienes un programa funcionando: las compras suman y el cliente tiene
un saldo.
### Consulta el código que trae el cliente
Cuando el cliente llega con un código de canje (su `client_benefit_code`), lo
primero es ver qué es. Usa
[la v2](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2), que trae el valor del
descuento en la raíz:
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v2/benefits/preview/887766 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
Con el `type` y el `value` de la respuesta aplicas el descuento en tu venta:
| `type` | Qué hacer |
| --------------------- | --------------------------------- |
| `percentage_discount` | Aplicar el porcentaje de `value`. |
| `absolute_discount` | Descontar el monto de `value`. |
| `free_product` | Agregar el producto de `product`. |
Un `400` aquí significa que el código ya se usó: no apliques nada.
### Canjéalo cuando la venta se cerró
[El canje](https://docs.loybox.com.ar/api-reference/beneficios/canjear) quema el código y no tiene vuelta
atrás:
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/redeem \
-H "Authorization: Bearer $LOYBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_benefit_code": 887766
}'
```
Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeas
antes de cerrar la venta y la venta se cae, el cliente perdió la recompensa y no
hay forma de devolvérsela por API.
## Camino 2: el club en tu frontend
Aquí Loybox funciona como motor de lealtad debajo de tu producto: el usuario
inicia sesión con un código que le llega por correo y desde ahí ve sus puntos,
compra beneficios y muestra sus códigos. Todo esto puede correr en el navegador.
Ninguna llamada de este camino lleva la API key: da acceso a los datos de todos
tus clientes. Lo que viaja es el token del usuario, que sólo ve lo suyo, más el
`X-Commerce-Id`, que no es secreto.
### Pídele el código
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/request \
-H "X-Commerce-Id: 87" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com"
}'
```
Responde `200` siempre, incluso si ese correo no tiene cuenta. En la UI muestras
siempre el mismo mensaje ("te mandamos un código a tu correo"), porque no puedes
saber si la cuenta existía.
### Verifícalo y guarda la sesión
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/verify \
-H "X-Commerce-Id: 87" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com",
"otp": "418302"
}'
```
Devuelve `access` y `refresh`. Guarda los dos: el `access` vence a los
`expires_in` segundos y el `refresh` sirve para
[renovarlo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) sin pedirle otro código
al usuario. Si el correo no tenía cuenta, se crea, y en ambos casos el usuario
queda adherido a tu programa.
### Pinta la pantalla con una sola llamada
[`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) trae de una los puntos, la
marca del comercio y los puntos por vencer:
```js
const res = await fetch(
'https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me',
{
headers: {
Authorization: `Bearer ${accessToken}`,
'X-Commerce-Id': '87',
},
},
);
const me = await res.json();
// me.points -> el saldo grande de la pantalla
// me.commerce -> logo, nombre y color para la marca del programa
// me.subscribed -> si viene false, muestra el llamado a adherirse
```
Un `401` aquí quiere decir que el `access` venció:
[renuévalo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintenta la llamada.
### Muestra el catálogo y compra
[El catálogo](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) viene sin filtrar
por saldo: comparas el `cost` de cada beneficio con los `points` del usuario y
decides qué mostrar como alcanzable y qué como "te faltan N puntos".
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits/exchange \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87" \
-H "Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b" \
-H "Content-Type: application/json" \
-d '{
"benefit_id": "b_9f2a"
}'
```
Comprar cambia puntos por un beneficio, y lo hace el usuario desde tu frontend.
Canjear usa ese beneficio en la venta, y lo hace tu servidor con la API key
([paso 4 del camino 1](#camino-1-sumar-puntos-desde-tu-servidor)).
### Muéstrale el código
La compra devuelve un `client_benefit_code`. Ese número es el código de canje y
también el código de cupón: en una tienda online es lo que el usuario pega en el
checkout, y en un negocio físico es lo que muestra en el mostrador.
Muéstralo grande, con un botón de copiar y el `due_date` al lado. La lista
completa de los que tiene está en
[mis beneficios](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios).
## El circuito completo
Los dos caminos se cierran así, y es el modelo mental que conviene tener antes
de escribir código:
```
compra ──▶ POST /v1/consumptions/email (tu servidor, API key)
│
▼
puntos al cliente
│
▼
POST /v1/me/benefits/exchange (tu frontend, token del usuario)
│
▼
client_benefit_code
│
▼
GET /v2/benefits/preview/{code} (tu servidor, API key)
│
▼
POST /v1/benefits/redeem (tu servidor, API key)
```
## Antes de salir a producción
* La **API key vive sólo en tu servidor**. Si se filtró, escríbenos y la
rotamos.
* **Nunca reintentes un `400`** a ciegas: es el beneficio ya usado, el vencido o
los puntos que no alcanzan. Lee el `message` y corta.
* **Comprar un beneficio lleva `Idempotency-Key`**. Es lo que evita cobrar los
puntos dos veces cuando se corta la red.
* Un **`401`** en Mi cuenta es la señal de renovar el token, no de sacar al
usuario de la sesión.
* El **`404` de [mi nivel](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel)** es el caso normal
de un cliente nuevo: esconder la sección de niveles, no mostrar un error.
* **`points_expiration` no viene en `null`** cuando los puntos no vencen: viene
con `mode: "none"`. Revisa el `mode` antes de mostrar el aviso.
## Si estás implementando con un agente
La API está publicada en formato de máquina:
* [`/openapi.json`](https://docs.loybox.com.ar/openapi.json): la especificación OpenAPI 3.1 completa, con
los 25 endpoints, los esquemas y las dos credenciales. Sirve para generar un
cliente tipado.
* [`/llms.txt`](https://docs.loybox.com.ar/llms.txt) y [`/llms-full.txt`](https://docs.loybox.com.ar/llms-full.txt): la doc entera
en texto, pensada para pasarle como contexto.
* Cualquier página de la doc en Markdown crudo agregándole `.md` a la URL, por
ejemplo
[`/api-reference/credenciales.md`](https://docs.loybox.com.ar/api-reference/credenciales.md).
# Credenciales (https://docs.loybox.com.ar/es-419/api-reference/credenciales)
La API tiene **dos credenciales distintas**, y no son intercambiables. Cuál usas
depende de dónde corre tu código y de qué datos necesita ver.
## API key del comercio
Es la integración clásica: tu backend opera sobre todos los clientes del
comercio. La API key va en el header `Authorization`:
```
Authorization: Bearer {api-key}
```
Con esta credencial funcionan [Consumos](https://docs.loybox.com.ar/api-reference/consumos),
[Beneficios](https://docs.loybox.com.ar/api-reference/beneficios) y [Clientes](https://docs.loybox.com.ar/api-reference/clientes).
No hace falta ningún otro header: la key ya identifica al comercio.
La API key da acceso a los datos de **todos** tus clientes. No la pongas nunca
en el frontend, en una app móvil, ni en un repositorio. Si se filtró, escríbenos
a [hola@loybox.com.ar](mailto:hola@loybox.com.ar) para rotarla.
## Token del usuario final
Pensada para conectar Loybox directo al frontend y usarlo como motor de
lealtad: el usuario inicia sesión con un código que le llega por correo y a
partir de ahí consulta sus puntos, compra beneficios y ve su historial.
Van dos headers:
```
Authorization: Bearer {access-token-del-usuario}
X-Commerce-Id: {tu-commerce-id}
```
Con esta credencial funcionan [Autenticación](https://docs.loybox.com.ar/api-reference/autenticacion),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico). Este
token **sí puede vivir en el navegador**: sólo ve los datos de ese usuario en tu
comercio.
## El header X-Commerce-Id
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
Es obligatorio en **todos** los endpoints de Autenticación, Mi cuenta y Público,
incluso en los que no llevan token. Es el header que acota la respuesta a tu
programa: un mismo usuario puede estar en varios programas de Loybox y con este
header ve sólo el tuyo.
No es un secreto: va en el frontend sin problema. Lo que hace es delimitar, no
autorizar.
## El flujo de inicio de sesión
### Pedir el código
[`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
correo del usuario. Le llega un código de 6 dígitos.
### Verificarlo
[`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) con
el correo y el código. Devuelve un token de acceso (`access`) y uno de refresco
(`refresh`). Si el correo no tenía cuenta en Loybox se crea, y en ambos casos el
usuario queda adherido al programa de tu comercio.
### Usar la sesión
A partir de ahí, las llamadas a [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) van con
`Authorization: Bearer {access}`.
### Renovarla
Cuando el `access` vence,
[`POST /v1/auth/refresh`](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) devuelve
uno nuevo a partir del `refresh`, sin pedirle otro código al usuario.
El código vence a los **10 minutos** y admite **5 intentos**. Pedir un código
nuevo invalida el anterior.
## Resumen
| | API key del comercio | Token del usuario final |
| -------------- | --------------------------------- | -------------------------------------------------- |
| **Header** | `Authorization: Bearer {api-key}` | `Authorization: Bearer {access}` + `X-Commerce-Id` |
| **Dónde vive** | Sólo en tu servidor | Puede vivir en el navegador |
| **Qué ve** | Todos los clientes del comercio | Sólo ese usuario, sólo en tu comercio |
| **Vence** | No | Sí, se renueva con el `refresh` |
| **Secciones** | Consumos, Beneficios, Clientes | Autenticación, Mi cuenta, Público |
# Objetos (https://docs.loybox.com.ar/es-419/api-reference/objetos)
Esta página es el diccionario de la API: cada objeto que aparece en una
respuesta, con todos sus campos. Las páginas de endpoint enlazan aquí en lugar de
repetir las listas.
## Los tres códigos
Antes que nada, esto: la API maneja tres identificadores parecidos y confundirlos
es el error más común al integrarse.
| Código | Qué identifica | Dónde se usa |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `client_code` | Un **cliente**. Es el número que tiene cada persona registrada en Loybox. | [Registrar un consumo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo), [consultar un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener) |
| `benefit_id` | Un **beneficio del catálogo**, el que creó el comercio. | [Consultar un beneficio](https://docs.loybox.com.ar/api-reference/beneficios/obtener), [comprarlo](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio) |
| `client_benefit_code` | Un **beneficio ya comprado** por un cliente concreto. | [Consultar el código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo), [canjearlo](https://docs.loybox.com.ar/api-reference/beneficios/canjear) |
El comercio crea **beneficios**, y cada uno tiene un `benefit_id`. Cuando un
cliente compra uno con sus puntos recibe un **beneficio canjeable** con su propio
`client_benefit_code`.
El `benefit_id` sirve sólo para consultar información. El
`client_benefit_code` sirve para consultar **y para canjear**: es el código que
el cliente presenta en el negocio, o pega en el checkout de la tienda online.
## Cliente
Aparece en [listar clientes](https://docs.loybox.com.ar/api-reference/clientes/listar) y
[consultar un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener).
El código del cliente.
Nombre del cliente.
Correo del cliente.
Puntos que tiene en el comercio.
## Beneficio
El beneficio del catálogo. Aparece en casi todas las respuestas de
[Beneficios](https://docs.loybox.com.ar/api-reference/beneficios), [Clientes](https://docs.loybox.com.ar/api-reference/clientes),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico).
El `benefit_id`.
Qué clase de recompensa es: `percentage_discount`, `absolute_discount` o
`free_product`.
Descripción del beneficio.
Cuántos puntos cuesta comprarlo.
Hasta cuándo está vigente. `null` si no vence.
`normal` para los del catálogo; `welcome`, `birthday`, `monthly_top` o
`level` para las recompensas especiales. Por defecto, `normal`.
Color de marca del comercio, en hexadecimal.
Cantidad total de canjes permitidos para este beneficio. `0` significa sin
límite.
El detalle de la recompensa. Ver [Premio](#premio).
El cupón, si el beneficio se aplica en una tienda de Tiendanube. Ver
[Cupón de Tiendanube](#cupón-de-tiendanube).
### Beneficio (v2)
[`GET /v2/benefits/preview/{client_benefit_code}`](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2)
devuelve una versión con tres campos más, que evitan tener que entrar a `prize`
para lo básico:
Título del beneficio. En la v1 sólo estaba dentro de `prize`.
El valor del descuento: el porcentaje si es `percentage_discount`, el monto
si es `absolute_discount`.
El producto, si es `free_product`. Ver [Producto](#producto).
El resto de los campos son los mismos que en [Beneficio](#beneficio).
## Beneficio canjeable
Un beneficio que un cliente ya compró. Aparece en
[beneficios comprados](https://docs.loybox.com.ar/api-reference/clientes/beneficios-comprados),
[mis beneficios](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios) y como respuesta de
[comprar un beneficio](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio).
El código de canje. Es lo que el cliente presenta en el comercio, y también
el código de cupón en una tienda online.
Cuándo lo compró.
Hasta cuándo puede canjearlo. `null` si no vence.
Si ya fue canjeado. Por defecto, `false`.
El beneficio comprado. Ver [Beneficio](#beneficio).
## Premio
El detalle de lo que gana el cliente. Va dentro de `prize`.
`percentage_discount`, `absolute_discount` o `free_product`.
Título de la recompensa.
Descripción de la recompensa.
El porcentaje o el monto del descuento, según el `type`.
El producto de regalo. Ver [Producto](#producto).
Vencimiento de la recompensa.
URL de la imagen de la recompensa.
## Producto
Id del producto en Loybox.
Nombre del producto.
Id del producto en el sistema del comercio.
## Comercio
Los datos de marca del programa. Aparece en
[datos del comercio](https://docs.loybox.com.ar/api-reference/publico/comercio) y dentro de
[mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).
El `commerce_id`, el mismo que va en el header `X-Commerce-Id`.
Nombre del comercio.
URL del logo.
Color de marca en hexadecimal, para la UI del programa.
Giro del comercio, por ejemplo `Tienda de cómics`.
Moneda del comercio.
## Mi cuenta
La respuesta de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).
Nombre del usuario.
Correo del usuario.
Teléfono del usuario.
Puntos del usuario en este comercio. Por defecto, `0`.
Si el usuario está adherido al programa de este comercio. Por defecto,
`false`.
Datos del comercio, para pintar la marca del programa. Ver
[Comercio](#comercio).
Puntos que están por vencer. Ver
[Vencimiento de puntos](#vencimiento-de-puntos).
## Vencimiento de puntos
Puntos que están por vencer. Por defecto, `0`.
Cuándo vencen.
Días que faltan.
Meses que faltan.
Cómo vencen los puntos en este comercio: `none`, `rolling` o `accumulated`.
`none` significa que no vencen.
Si el comercio no hace vencer los puntos, el objeto viene con `mode: "none"` y
`points: 0`, no en `null`. Ver
[Vencimiento de puntos](https://docs.loybox.com.ar/puntos-y-premios/expiracion) para el detalle de los
modos.
## Nivel
La respuesta de [`GET /v1/me/level`](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel).
Nombre del nivel.
Posición del nivel en la escalera.
Multiplicador de puntos que da el nivel.
URL del icono del nivel.
Cuándo alcanzó el nivel.
Cuándo vence el nivel.
Si el nivel ya venció.
El nivel siguiente y qué falta para alcanzarlo. Ver
[Próximo nivel](#próximo-nivel).
Puntos ganados en total, el acumulado histórico.
Monto gastado en total.
Cantidad de consumos registrados.
### Próximo nivel
Nombre del próximo nivel.
Posición del próximo nivel.
Con qué se mide el umbral: por puntos acumulados o por monto gastado.
El valor del umbral a alcanzar.
## Movimiento
Cada item de [mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial).
Qué pasó: `consumption` (una compra que sumó puntos), `benefit_exchange`
(compró un beneficio con puntos), `benefit_usage` (canjeó un beneficio) o
`points_special_reward` (una recompensa automática le dio puntos).
Cuándo pasó.
Puntos que sumó o restó el movimiento.
El beneficio involucrado, en los movimientos de beneficio. Ver
[Beneficio](#beneficio).
Monto de la compra, en los movimientos de tipo `consumption`.
El evento que disparó la recompensa, en los `points_special_reward`.
Nota adicional del movimiento.
## Recompensa automática
Cada item de [recompensas del programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/recompensas).
Evento que la dispara: `welcome`, `birthday` o `monthly_top`.
`benefit` si entrega un beneficio, `points` si entrega puntos.
El beneficio que entrega, cuando `reward_type` es `benefit`. Ver
[Beneficio](#beneficio).
Los puntos que entrega, cuando `reward_type` es `points`.
## Sesión
La respuesta de
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo).
Token de acceso. Se manda como `Authorization: Bearer {access}` en los
endpoints de Mi cuenta.
Token de refresco, para obtener un nuevo `access` sin volver a pedir un
código.
Segundos de validez del token de acceso.
Id del usuario.
Nombre del usuario.
Correo del usuario.
Teléfono del usuario.
## Cupón de Tiendanube
Va dentro de `tiendanube_coupon` cuando el beneficio se aplica en una tienda de
[Tiendanube](https://docs.loybox.com.ar/integraciones/tiendanube).
`percentage`, `absolute` o `shipping`.
El valor del cupón.
Id de la categoría de Tiendanube a la que aplica el cupón.
Nombre de esa categoría.
Hasta cuándo vale el cupón.
El producto al que aplica el cupón, si aplica a uno solo. Ver
[Producto de Tiendanube](#producto-de-tiendanube).
### Producto de Tiendanube
Id del producto en Tiendanube.
Nombre del producto.
URL del producto en la tienda.
Si hay existencias.
Si está publicado en la tienda.
Marca del producto.
Categorías del producto, cada una con `id` y `name`. Por defecto, vacío.
# Errores (https://docs.loybox.com.ar/es-419/api-reference/errores)
Cuando algo sale mal, la API responde con un código de estado HTTP y un cuerpo
con un solo campo:
```json
{
"message": "Client not found"
}
```
El `message` es un texto para el desarrollador, no para mostrarle al usuario:
puede cambiar sin aviso. Lo que conviene mirar en el código es **el código de
estado**.
## Códigos de estado
| Código | Qué significa | Qué hacer |
| ------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `200` | Salió bien. | — |
| `201` | Se creó el recurso. Lo devuelven los dos endpoints de [Consumos](https://docs.loybox.com.ar/api-reference/consumos). | — |
| `400` | El pedido no se pudo procesar: el beneficio ya se usó, no está vigente, o al usuario no le alcanzan los puntos. | Leer el `message` para saber cuál de los casos es. No reintentar igual. |
| `401` | La credencial falta, venció o no sirve para este endpoint. | Con API key, revisar que sea la correcta. Con token de usuario, [renovarlo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token). |
| `403` | El cliente existe pero no puede tener consumos. | No reintentar. |
| `404` | El recurso no existe: cliente, beneficio o comercio. | Revisar el código o el id que mandaste. |
| `422` | El cuerpo o los headers no pasaron la validación. | Ver [Errores de validación](#errores-de-validación). |
## Errores de validación
El `422` es distinto a los demás: no trae `message` sino un `detail` con la lista
de todo lo que está mal, un item por campo.
```json
{
"detail": [
{
"loc": ["body", "amount"],
"msg": "Input should be a valid integer",
"type": "int_parsing"
}
]
}
```
Dónde está el problema. El primer elemento dice en qué parte del pedido
(`body`, `query`, `header`, `path`) y el resto es el camino hasta el campo.
Qué tiene de malo.
El tipo de error de validación.
La causa más frecuente de un `422` no es el cuerpo: es **el header
`X-Commerce-Id` que falta**. Es obligatorio en todos los endpoints de
[Autenticación](https://docs.loybox.com.ar/api-reference/autenticacion),
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) y [Público](https://docs.loybox.com.ar/api-reference/publico).
## Dos casos que no son errores
[`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo)
responde `200` incluso si el correo no tiene cuenta en Loybox. Es a propósito:
si respondiera distinto, cualquiera podría usar el endpoint para averiguar qué
correos están registrados. No lo uses para validar si un usuario existe.
[`GET /v1/me/level`](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel) devuelve `404` cuando el
usuario todavía no tiene nivel, o cuando el comercio no usa niveles. Es el caso
normal de un cliente nuevo, no una falla: en la UI corresponde esconder la
sección de niveles, no mostrar un error.
## Reintentos
Comprar un beneficio mueve puntos, así que un reintento a ciegas puede cobrarlos
dos veces. Para eso
[`POST /v1/me/benefits/exchange`](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio)
acepta el header `Idempotency-Key`: si mandas el mismo valor otra vez, la compra
no se repite.
```
Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b
```
Usa un valor distinto por cada compra que el usuario inicia (un UUID
alcanza) y el mismo en todos los reintentos de esa compra.
# Consumos (https://docs.loybox.com.ar/es-419/api-reference/consumos)
Un **consumo** es el registro de una compra. Es lo que dispara el cálculo de
puntos: cada vez que un cliente compra, tu sistema avisa a Loybox y Loybox le
suma los puntos que correspondan.
Es la integración mínima de un programa de lealtad. Si sólo vas a llamar un
endpoint de toda esta API, es alguno de estos dos.
## Los dos endpoints
Hacen lo mismo y se diferencian sólo en cómo identifican al cliente:
| | Por código | Por correo |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------ |
| **Identifica al cliente con** | Su `client_code` | Su correo |
| **Si el cliente no existe** | Devuelve `404` | Registra el consumo igual y lo invita por correo |
| **Cuándo usarlo** | Punto de venta o app donde el cliente da su código | Checkout online, donde ya tienes el correo |
## Cuántos puntos suma
Eso no lo decide la llamada: lo decide la configuración del comercio. Tú mandas
el **monto** de la compra y Loybox aplica la regla de dinero por punto, los
puntos dobles si están vigentes y el bono del nivel del cliente, en ese orden.
La fórmula y el orden de los multiplicadores están en
[Referencia técnica](https://docs.loybox.com.ar/referencia-tecnica#cálculo-de-puntos).
El campo `amount` es un `integer`: son unidades de la moneda del comercio, sin
decimales. Una compra de `1.750,50` se manda como `1750`.
## Credencial
Los dos endpoints van desde tu servidor, con la
[API key del comercio](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio):
```
Authorization: Bearer {api-key}
```
# Crear consumo por código (https://docs.loybox.com.ar/es-419/api-reference/consumos/crear-por-codigo)
Registra un nuevo consumo usando el código del cliente. Es la llamada que suma
los puntos de una compra.
El cliente tiene que existir: si el código no corresponde a ningún cliente, la
llamada devuelve `404` y no se registra nada. Si prefieres que el consumo se
registre igual, usa
[crear consumo por correo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-email).
## Cuerpo
El código del cliente que hizo la compra.
Monto de la compra, en unidades enteras de la moneda del comercio.
Id del punto de venta donde se hizo la compra.
Id de la sucursal donde se hizo la compra.
## Ejemplo
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/consumptions/client-code \
-H "Authorization: Bearer $LOYBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_code": 12345,
"amount": 1750,
"counter_id": 2,
"id_suc": 1
}'
```
```json
// 201 Created
{
"message": "Consumption created successfully"
}
```
La respuesta no dice cuántos puntos sumó. Para verlo, consulta al cliente con
[`GET /v1/clients/{client_code}`](https://docs.loybox.com.ar/api-reference/clientes/obtener).
## Errores
| Código | Cuándo |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `400` | No se pudo crear el consumo. |
| `403` | El cliente existe pero no es elegible para tener consumos. |
| `404` | El cliente no existe. |
| `422` | Falta un campo del cuerpo o tiene el tipo equivocado. Ver [Errores de validación](https://docs.loybox.com.ar/api-reference/errores#errores-de-validación). |
# Crear consumo por correo (https://docs.loybox.com.ar/es-419/api-reference/consumos/crear-por-email)
Registra un nuevo consumo usando el correo del cliente. Es el que conviene en un
checkout online, donde el correo ya lo tienes y pedirle un código al cliente
sobraría.
Si el correo no corresponde a ninguna cuenta de Loybox, el consumo **se crea
igual** y automáticamente le llega un correo invitándolo a registrarse. Cuando se
registra, los puntos de esa compra ya están esperándolo.
Es la forma de que el programa empiece a acumular valor antes de que el cliente
se sume.
## Cuerpo
Correo del cliente que hizo la compra.
Monto de la compra, en unidades enteras de la moneda del comercio.
## Ejemplo
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/consumptions/email \
-H "Authorization: Bearer $LOYBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_email": "ana@example.com",
"amount": 1750
}'
```
```json
// 201 Created
{
"message": "Consumption created successfully"
}
```
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | No se pudo crear el consumo. |
| `403` | El cliente existe pero no es elegible para tener consumos. |
| `404` | El cliente no existe. |
| `422` | Falta un campo del cuerpo, o el correo no tiene formato válido. Ver [Errores de validación](https://docs.loybox.com.ar/api-reference/errores#errores-de-validación). |
# Clientes (https://docs.loybox.com.ar/es-419/api-reference/clientes)
Un **cliente** es una persona sumada al club del comercio. Tiene un
`client_code`, un saldo de puntos y un historial propios.
Esta sección es de sólo lectura: sirve para mostrar el estado de un cliente en
tu sistema: en la pantalla del punto de venta, en el perfil de la tienda online, en un
CRM. Los puntos se mueven registrando [consumos](https://docs.loybox.com.ar/api-reference/consumos) y
[canjeando beneficios](https://docs.loybox.com.ar/api-reference/beneficios/canjear), no desde aquí.
## Los dos listados de beneficios
Hay dos endpoints de beneficios por cliente y conviene no confundirlos:
| Endpoint | Qué trae |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`/available-benefits`](https://docs.loybox.com.ar/api-reference/clientes/beneficios-disponibles) | Los que el cliente **puede comprar** con los puntos que tiene |
| [`/benefits`](https://docs.loybox.com.ar/api-reference/clientes/beneficios-comprados) | Los que **ya compró** y todavía puede canjear, cada uno con su código |
## Credencial
Toda la sección va desde tu servidor, con la
[API key del comercio](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio):
```
Authorization: Bearer {api-key}
```
Estos endpoints exponen nombre, correo y puntos de las personas del club. No los
llames desde el frontend: si necesitas que el propio usuario vea sus datos, para
eso está [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta), que sólo muestra lo suyo.
# Listar clientes (https://docs.loybox.com.ar/es-419/api-reference/clientes/listar)
Trae el listado de clientes del comercio, paginado en formato límite y
desplazamiento.
## Parámetros
Cuántos clientes traer por página. De `1` a `100`. Por defecto, `20`.
Desde qué posición arrancar. Por defecto, `0`.
## Respuesta
Los clientes de esta página. Ver [Cliente](https://docs.loybox.com.ar/api-reference/objetos#cliente).
Cantidad total de clientes del comercio, sin paginar.
El límite aplicado.
El desplazamiento aplicado.
## Ejemplo
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/list?limit=2&offset=0 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
{
"items": [
{
"code": 12345,
"username": "Ana Pérez",
"email": "ana@example.com",
"points": 340
},
{
"code": 12346,
"username": "Bruno Díaz",
"email": "bruno@example.com",
"points": 0
}
],
"total": 1875,
"limit": 2,
"offset": 0
}
```
Para recorrer todo el listado, ve sumando `limit` al `offset` hasta que la
suma llegue a `total`.
## Errores
| Código | Cuándo |
| ------ | ---------------------------------------------------------------- |
| `401` | La API key es inválida: no tiene un comercio asociado. |
| `422` | `limit` está fuera del rango de 1 a 100, o `offset` es negativo. |
# Obtener un cliente (https://docs.loybox.com.ar/es-419/api-reference/clientes/obtener)
Busca un cliente por su código. El `client_code` es el número que tiene cada
persona registrada en Loybox: es el que el cliente da en el punto de venta y el que se usa
para [registrar un consumo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo).
## Parámetros
El código del cliente.
## Respuesta
Un objeto [Cliente](https://docs.loybox.com.ar/api-reference/objetos#cliente).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
{
"code": 12345,
"username": "Ana Pérez",
"email": "ana@example.com",
"points": 340
}
```
El campo `points` es el saldo disponible: puntos ganados vigentes menos puntos
canjeados. Los puntos vencidos no cuentan. Ver
[Saldo](https://docs.loybox.com.ar/referencia-tecnica#saldo).
## Errores
| Código | Cuándo |
| ------ | ------------------------------------- |
| `404` | El cliente no existe. |
| `422` | El código no tiene un formato válido. |
# Beneficios que puede comprar (https://docs.loybox.com.ar/es-419/api-reference/clientes/beneficios-disponibles)
Busca los beneficios disponibles para un cliente: los que se le muestran en su
panel de beneficios, es decir los que **puede comprar** con sus puntos.
Es la contracara de
[beneficios comprados](https://docs.loybox.com.ar/api-reference/clientes/beneficios-comprados), que trae
los que ya canjeó puntos por ellos.
## Parámetros
El código del cliente.
## Respuesta
Un array de [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345/available-benefits \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
[
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": {
"type": "percentage_discount",
"title": "20% off",
"description": "Válido en toda la tienda",
"value": 20,
"product": null,
"expiration": "2026-12-31T23:59:59Z",
"image": null
},
"tiendanube_coupon": null
}
]
```
El `cost` de cada beneficio es lo que cuesta en puntos. Para saber cuáles le
alcanzan, compáralo con el `points` de
[obtener un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener).
## Errores
| Código | Cuándo |
| ------ | ------------------------------------- |
| `404` | El cliente no existe. |
| `422` | El código no tiene un formato válido. |
# Beneficios comprados (https://docs.loybox.com.ar/es-419/api-reference/clientes/beneficios-comprados)
Trae los beneficios que el cliente **ya compró** con sus puntos y todavía puede
canjear en el comercio.
Es la contracara de
[beneficios que puede comprar](https://docs.loybox.com.ar/api-reference/clientes/beneficios-disponibles):
ahí van los que le alcanzan con sus puntos, aquí los que ya son suyos.
El `client_benefit_code` de cada item es el código que se usa para
[consultar el beneficio](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo) y para
[canjearlo](https://docs.loybox.com.ar/api-reference/beneficios/canjear). Es el número que el cliente
presenta en el negocio o pega en el checkout.
## Parámetros
El código del cliente.
Sin especificar trae **sólo los canjeables**: sin usar y sin vencer. `true`
trae los ya canjeados y `false` los no canjeados, en ambos casos sin filtrar
por vencimiento.
El comportamiento por defecto es el que sirve para operar: mostrarle al cliente
qué puede usar hoy. El parámetro `used` es para consultar el historial.
## Respuesta
Un array de
[Beneficio canjeable](https://docs.loybox.com.ar/api-reference/objetos#beneficio-canjeable).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345/benefits \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
[
{
"client_benefit_code": 887766,
"issue_date": "2026-03-01T14:22:00Z",
"due_date": "2026-04-01T14:22:00Z",
"used": false,
"benefit": {
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
}
}
]
```
## Errores
| Código | Cuándo |
| ------ | ----------------------------------------------------------------- |
| `401` | La API key es inválida: no tiene un comercio asociado. |
| `404` | El cliente no existe. |
| `422` | El código no tiene un formato válido, o `used` no es un booleano. |
# Beneficios (https://docs.loybox.com.ar/es-419/api-reference/beneficios)
Esta sección tiene las dos mitades de la vida de una recompensa: **el catálogo** que
armó el comercio, y **el canje** de un código que un cliente trae para usar.
El comercio crea **beneficios**, y cada uno tiene un `benefit_id`. Cuando un
cliente compra uno con sus puntos recibe un **beneficio canjeable** con su propio
`client_benefit_code`.
El `benefit_id` sirve sólo para consultar información. El
`client_benefit_code` sirve para consultar **y para canjear**.
## El flujo del canje
Así se ve del lado de tu sistema cuando un cliente llega con un código:
### El cliente da su código
Lo tiene en su app de Loybox. Es el `client_benefit_code`.
### Consultas qué es
[`GET /v1/benefits/preview/{client_benefit_code}`](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo)
te dice qué recompensa es y, si corresponde, qué descuento aplicar. Todavía no
canjea nada.
### Aplicas el descuento
En tu punto de venta, tu ecommerce o donde corra la venta, con los datos del paso
anterior.
### Lo marcas como usado
[`POST /v1/benefits/redeem`](https://docs.loybox.com.ar/api-reference/beneficios/canjear). A partir de aquí
el código queda quemado y no se puede volver a usar.
Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeas
antes de cerrar la venta y la venta se cae, el cliente perdió la recompensa.
## Los endpoints
## Credencial
Toda la sección va desde tu servidor, con la
[API key del comercio](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio):
```
Authorization: Bearer {api-key}
```
# Listar beneficios (https://docs.loybox.com.ar/es-419/api-reference/beneficios/listar)
Trae una lista de todos los beneficios creados por el comercio. Es el catálogo
completo, sin filtrar por vigencia ni por cliente.
No lleva parámetros ni paginación.
## Respuesta
Un array de [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/list \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
[
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
},
{
"id": "b_4c81",
"type": "free_product",
"description": "Café de regalo",
"cost": 100,
"expiration": null,
"benefit_type": "welcome",
"color": "#f1a10d",
"buy_limit": 1,
"prize": null,
"tiendanube_coupon": null
}
]
```
El campo `benefit_type` distingue los beneficios del catálogo (`normal`) de las
recompensas que el comercio entrega solas: `welcome`, `birthday`, `monthly_top` y
`level`. Si quieres mostrar sólo lo que el cliente puede comprar con puntos,
filtra por `normal`, o usa
[beneficios que puede comprar](https://docs.loybox.com.ar/api-reference/clientes/beneficios-disponibles),
que ya viene filtrado.
## Errores
Este endpoint no declara errores propios más allá de los
[generales](https://docs.loybox.com.ar/api-reference/errores).
# Obtener un beneficio (https://docs.loybox.com.ar/es-419/api-reference/beneficios/obtener)
Trae información sobre un beneficio del catálogo usando su id.
El `benefit_id` identifica un beneficio del **catálogo**, no el de un cliente
concreto. Para consultar el beneficio que un cliente trae para usar, el
identificador es el `client_benefit_code` y el endpoint es
[consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo).
## Parámetros
El id del beneficio.
## Respuesta
Un objeto [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/b_9f2a \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": {
"type": "percentage_discount",
"title": "20% off",
"description": "Válido en toda la tienda",
"value": 20,
"product": null,
"expiration": "2026-12-31T23:59:59Z",
"image": null
},
"tiendanube_coupon": null
}
```
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------ |
| `401` | La API key es inválida: no tiene un comercio asociado. |
| `404` | El beneficio no existe. |
| `422` | El id no tiene un formato válido. |
# Consultar un código (https://docs.loybox.com.ar/es-419/api-reference/beneficios/consultar-codigo)
Trae información sobre un beneficio usando el código que el cliente tiene para
canjearlo.
Sirve para saber **qué acciones tomar** antes de canjear: qué clase de recompensa es,
cuánto descuento aplicar, si es un producto de regalo. Con eso tu sistema puede
aplicar el beneficio en la venta y sólo después
[marcarlo como usado](https://docs.loybox.com.ar/api-reference/beneficios/canjear).
Consultar no canjea: puedes llamarlo las veces que necesites.
[La v2](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2) devuelve lo mismo más el
`title`, el `value` del descuento y el `product` al nivel de arriba, sin tener
que entrar a `prize`. Para una integración nueva conviene esa.
## Parámetros
El código de canje que tiene el cliente.
## Respuesta
Un objeto [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/preview/887766 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": {
"type": "percentage_discount",
"title": "20% off",
"description": "Válido en toda la tienda",
"value": 20,
"product": null,
"expiration": "2026-12-31T23:59:59Z",
"image": null
},
"tiendanube_coupon": null
}
```
Qué mirar según el `type`:
| `type` | Qué hacer |
| --------------------- | --------------------------------------- |
| `percentage_discount` | Aplicar el porcentaje de `prize.value`. |
| `absolute_discount` | Descontar el monto de `prize.value`. |
| `free_product` | Agregar el producto de `prize.product`. |
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------ |
| `400` | El beneficio ya fue usado. |
| `401` | La API key es inválida: no tiene un comercio asociado. |
| `404` | El beneficio no existe. |
| `422` | El código no tiene un formato válido. |
Un `400` aquí ya te dice que no sigas: el código está quemado y no hay que aplicar
ningún descuento.
# Consultar un código (v2) (https://docs.loybox.com.ar/es-419/api-reference/beneficios/consultar-codigo-v2)
Hace lo mismo que
[la versión 1](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo), que trae información
sobre el beneficio a partir del código que el cliente tiene para canjearlo, pero
devuelve tres campos más en la raíz del objeto.
Para una integración nueva, usa esta.
## Qué cambia
| Campo | En la v1 | En la v2 |
| --------- | ---------------------- | ------------------------------ |
| `title` | Sólo dentro de `prize` | En la raíz, y siempre presente |
| `value` | Sólo dentro de `prize` | En la raíz |
| `product` | Sólo dentro de `prize` | En la raíz |
En la práctica: para aplicar el descuento ya no hace falta entrar a `prize` ni
revisar que exista. El resto de los campos son los mismos.
## Parámetros
El código de canje que tiene el cliente.
## Respuesta
Un objeto [Beneficio (v2)](https://docs.loybox.com.ar/api-reference/objetos#beneficio-v2).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v2/benefits/preview/887766 \
-H "Authorization: Bearer $LOYBOX_API_KEY"
```
```json
// 200 OK
{
"id": "b_9f2a",
"type": "percentage_discount",
"value": 20,
"title": "20% off",
"description": "Válido en toda la tienda",
"product": null,
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
}
```
Qué mirar según el `type`:
| `type` | Qué hacer |
| --------------------- | --------------------------------- |
| `percentage_discount` | Aplicar el porcentaje de `value`. |
| `absolute_discount` | Descontar el monto de `value`. |
| `free_product` | Agregar el producto de `product`. |
## Cómo se canjea
Igual que en la v1: con
[`POST /v1/benefits/redeem`](https://docs.loybox.com.ar/api-reference/beneficios/canjear). El canje no
tiene versión 2: el mismo código sirve para las dos.
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------ |
| `400` | El beneficio ya fue usado. |
| `401` | La API key es inválida: no tiene un comercio asociado. |
| `404` | El beneficio no existe. |
| `422` | El código no tiene un formato válido. |
# Canjear un beneficio (https://docs.loybox.com.ar/es-419/api-reference/beneficios/canjear)
Canjea el beneficio usando el código que tiene el cliente. Es el último paso del
flujo: a partir de aquí el código queda quemado y no se puede volver a usar.
Llama a este endpoint recién cuando la venta esté cerrada y el descuento
aplicado. Si lo llamas antes y la venta se cae, el cliente pierde la recompensa y no
hay forma de devolvérsela por API.
Para ver qué recompensa es sin quemarla, usa
[consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo).
## Cuerpo
El código de canje que tiene el cliente.
## Ejemplo
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/redeem \
-H "Authorization: Bearer $LOYBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_benefit_code": 887766
}'
```
```json
// 200 OK
{
"message": "Benefit redeemed successfully"
}
```
## Errores
| Código | Cuándo |
| ------ | ---------------------------------- |
| `400` | El beneficio ya fue usado. |
| `404` | El beneficio no existe. |
| `422` | Falta el campo, o no es un entero. |
Es lo que pasa cuando alguien intenta usar el mismo código dos veces. No es un
error de tu integración: conviene mostrarle a quien atiende un mensaje claro de
"este código ya se usó" en lugar de un error genérico.
# Autenticación (https://docs.loybox.com.ar/es-419/api-reference/autenticacion)
Inicio de sesión del **usuario final** con un código de un solo uso enviado por
correo. Es la sección que habilita integrar Loybox directamente en el frontend de
tu web, sin pasar por tu servidor.
No hay contraseñas: el usuario pone su correo, recibe un código de 6 dígitos y con
eso queda dentro.
## El flujo
### Pedir el código
[`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
correo del usuario. Le llega un código de 6 dígitos. El endpoint responde `200`
siempre, incluso si ese correo no tiene cuenta.
### Verificarlo
[`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) con
el correo y el código. Devuelve un token de acceso (`access`) y uno de refresco
(`refresh`). Si el correo no tenía cuenta en Loybox, se crea; en ambos casos el
usuario queda adherido al programa de tu comercio.
### Usar la sesión
A partir de ahí, las llamadas a [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) van con el
header `Authorization: Bearer {access}`.
### Renovarla
Cuando el `access` vence,
[`POST /v1/auth/refresh`](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) devuelve
uno nuevo a partir del `refresh`, sin pedirle otro código al usuario.
## Reglas del código
* Vence a los **10 minutos**.
* Admite **5 intentos**.
* Pedir un código nuevo **invalida el anterior**.
## El header X-Commerce-Id
Todos los endpoints de esta sección y de [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta)
requieren el header `X-Commerce-Id` con el id de tu comercio:
```
X-Commerce-Id: {tu-commerce-id}
```
Ese header es el que limita la respuesta a tu programa: el usuario nunca ve datos
de otros comercios.
La **API key** del comercio es secreta y va únicamente en tu servidor. El
**token de acceso del usuario** es el que puede vivir en el navegador. No mandes
nunca la API key desde el frontend. Ver
[Credenciales](https://docs.loybox.com.ar/api-reference/credenciales).
## Los endpoints
# Pedir un código (https://docs.loybox.com.ar/es-419/api-reference/autenticacion/pedir-codigo)
Envía por correo un código de 6 dígitos para que el usuario final inicie sesión.
Si el correo no tiene cuenta en Loybox, la cuenta se crea al
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo), no aquí.
Responde `200` incluso si el correo no existe. Es **a propósito**: si respondiera
distinto, cualquiera podría usar este endpoint para averiguar qué correos están
registrados.
En la UI esto significa que después de pedir el código muestras siempre el mismo
mensaje ("te mandamos un código a tu correo") sin poder saber si la cuenta
existía.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
No lleva `Authorization`: es el endpoint con el que arranca la sesión.
## Cuerpo
Correo del usuario. Tiene que tener formato válido.
## Ejemplo
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/request \
-H "X-Commerce-Id: 87" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com"
}'
```
```json
// 200 OK
{
"message": "Código enviado"
}
```
## Reglas del código
* Vence a los **10 minutos**.
* Admite **5 intentos**.
* Pedir un código nuevo **invalida el anterior**.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------- |
| `422` | Falta el header `X-Commerce-Id`, o el correo es inválido. |
# Verificar el código (https://docs.loybox.com.ar/es-419/api-reference/autenticacion/verificar-codigo)
Valida el código enviado por correo y devuelve los tokens de sesión del usuario
final.
Si el correo no tenía cuenta, **la crea**. En ambos casos deja al usuario adherido
al programa del comercio indicado en `X-Commerce-Id`.
El `access` que devuelve es el que se usa como `Authorization: Bearer {access}`
en todos los endpoints de [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta).
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Cuerpo
El mismo correo con el que se
[pidió el código](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo).
Código de 6 dígitos recibido por correo. Exactamente 6 caracteres.
## Respuesta
Un objeto [Sesión](https://docs.loybox.com.ar/api-reference/objetos#sesión).
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/verify \
-H "X-Commerce-Id: 87" \
-H "Content-Type: application/json" \
-d '{
"email": "ana@example.com",
"otp": "418302"
}'
```
```json
// 200 OK
{
"access": "eyJhbGciOiJIUzI1NiIs...",
"refresh": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 3600,
"user_id": 4821,
"username": "Ana Pérez",
"email": "ana@example.com",
"phone": null
}
```
Guarda los dos tokens. El `access` vence a los `expires_in` segundos; el
`refresh` es el que después sirve para
[renovarlo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) sin volver a pedirle un
código al usuario.
No hace falta llamar a
[adherirme al programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/adherirme) después de esto: el
usuario ya queda adherido. Ese endpoint es para volver a adherirse después de
una baja.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------- |
| `400` | El código es inválido o venció. |
| `422` | Falta el header `X-Commerce-Id`, o el cuerpo es inválido. |
Después de 5 intentos fallidos el código deja de servir y hay que
[pedir uno nuevo](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo).
# Renovar el token (https://docs.loybox.com.ar/es-419/api-reference/autenticacion/renovar-token)
Devuelve un nuevo token de acceso a partir del token de refresco obtenido al
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo), sin
necesidad de pedirle al usuario un código nuevo.
Es lo que hace que la sesión se sienta continua: cuando una llamada a
[Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) devuelve `401`, renuevas y reintentas.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Cuerpo
El token de refresco que devolvió
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo).
## Respuesta
El token de acceso nuevo.
Segundos de validez del token nuevo.
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/refresh \
-H "X-Commerce-Id: 87" \
-H "Content-Type: application/json" \
-d '{
"refresh": "eyJhbGciOiJIUzI1NiIs..."
}'
```
```json
// 200 OK
{
"access": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 3600
}
```
La respuesta trae sólo el `access`. El `refresh` que ya tenías sigue siendo el
válido: guárdalo y sigue usándolo.
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------------ |
| `401` | El token de refresco es inválido o venció. |
| `422` | Falta el header `X-Commerce-Id`, o falta el campo `refresh`. |
Un `401` aquí quiere decir que la sesión terminó de verdad: hay que volver a
[pedir un código](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo).
# Mi cuenta (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta)
Endpoints del **usuario final**, autenticados con el token de acceso que
devuelve [verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo):
```
Authorization: Bearer {access}
X-Commerce-Id: {tu-commerce-id}
```
Todo lo que devuelven está limitado al comercio del header `X-Commerce-Id`:
puntos, beneficios, historial y nivel son los de ese programa y nada más. Un
mismo usuario puede estar en varios programas de Loybox y cada uno ve sólo el
suyo.
## El circuito típico
Así se arma una web de lealtad con estos endpoints:
### El primer render
[`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) trae de una los puntos, la marca
del comercio y los puntos por vencer. Con una sola llamada pintas el header y el
saldo.
### El catálogo
[`GET /v1/me/benefits/available`](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles)
para mostrar qué puede canjear.
### El canje
[`POST /v1/me/benefits/exchange`](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio)
cambia puntos por un beneficio.
### Los códigos
[`GET /v1/me/benefits`](https://docs.loybox.com.ar/api-reference/mi-cuenta/mis-beneficios) para mostrarle
los códigos que tiene para presentar en el comercio.
## Al armar la UI
Tres cosas que ahorran vueltas:
* El `client_benefit_code` de cada beneficio del usuario es **a la vez el código
de cupón**: en una tienda online es lo que el usuario pega en el checkout.
* Los beneficios traen `benefit_type`, que distingue los del catálogo (`normal`)
de las recompensas especiales (`welcome`, `birthday`, `monthly_top`, `level`),
y `color`, el color de marca del comercio.
* **Cuánto le falta** al usuario para un beneficio se calcula con el `cost` del
beneficio menos los `points` de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).
## Comprar y canjear no son lo mismo
| | Comprar | Canjear |
| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Qué hace** | Cambia puntos por un beneficio | Usa el beneficio en el comercio |
| **Quién lo llama** | El usuario, desde tu web | Tu servidor, en la venta |
| **Endpoint** | [`POST /v1/me/benefits/exchange`](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio) | [`POST /v1/benefits/redeem`](https://docs.loybox.com.ar/api-reference/beneficios/canjear) |
| **Credencial** | Token del usuario | API key del comercio |
## Los endpoints
## El 401 en toda la sección
Todos estos endpoints devuelven `401` cuando el token de acceso falta, venció o
no corresponde a un usuario final. Es el caso normal cuando pasó el tiempo:
[renuévalo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintenta la llamada.
# Mi cuenta (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/obtener)
Todo lo que necesita el frontend en el primer render: los datos del usuario, sus
puntos y adhesión en el programa del comercio indicado en `X-Commerce-Id`, los
datos de marca del comercio (nombre, logo, color, giro) y los puntos que están
por vencer.
Es la llamada con la que arranca la app. No hace falta pedir los datos del
comercio aparte: vienen dentro.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un objeto [Mi cuenta](https://docs.loybox.com.ar/api-reference/objetos#mi-cuenta).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
{
"username": "Ana Pérez",
"email": "ana@example.com",
"phone": null,
"points": 340,
"subscribed": true,
"commerce": {
"id": 87,
"name": "Tienda Central",
"logo": "https://cdn.loybox.com.ar/logos/87.png",
"color": "#f1a10d",
"category_name": "Tienda de comics",
"currency": "ARS"
},
"points_expiration": {
"points": 120,
"expiration_date": "2026-09-30T23:59:59Z",
"days_left": 37,
"months_left": 1,
"mode": "accumulated"
}
}
```
Qué hacer con cada pieza:
| Campo | Para qué |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `points` | El saldo grande de la pantalla. Es con lo que se compara el `cost` de cada beneficio. |
| `subscribed` | Si viene en `false`, muestra el llamado a [adherirse](https://docs.loybox.com.ar/api-reference/mi-cuenta/adherirme) en lugar del catálogo. |
| `commerce` | Logo, nombre y color para pintar la marca del programa. |
| `points_expiration` | El aviso de "te vencen X puntos en Y días". |
`points_expiration` no viene en `null`: viene con `mode: "none"` y `points: 0`.
Revisa el `mode` antes de mostrar el aviso de vencimiento.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `422` | Falta el header `X-Commerce-Id`. |
# Beneficios que puedo comprar (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/beneficios-disponibles)
Catálogo de beneficios vigentes del comercio, que el usuario puede comprar con
sus puntos.
Para saber cuáles le alcanzan, comparar el `cost` de cada beneficio con los
`points` de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener). La API no filtra
por saldo: devuelve el catálogo y la UI decide qué mostrar como alcanzable y qué
como "te faltan N puntos".
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un array de [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits/available \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
[
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": {
"type": "percentage_discount",
"title": "20% off",
"description": "Válido en toda la tienda",
"value": 20,
"product": null,
"expiration": "2026-12-31T23:59:59Z",
"image": null
},
"tiendanube_coupon": null
}
]
```
El `id` de cada item es lo que se manda como `benefit_id` a
[comprar un beneficio](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio).
Para mostrarle el catálogo a un visitante que todavía no inició sesión hay
[`GET /v1/public/benefits`](https://docs.loybox.com.ar/api-reference/publico/beneficios), que no necesita
token.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `422` | Falta el header `X-Commerce-Id`. |
# Comprar un beneficio (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/comprar-beneficio)
Cambia los puntos del usuario por un beneficio del catálogo. Devuelve el
beneficio comprado con su `client_benefit_code`, que es el código con el que
después se canjea en el comercio.
Es la única llamada de [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta) que mueve puntos.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
Clave para que un reintento no cobre los puntos dos veces.
Si la red se corta después de que el servidor procesó la compra, tu reintento
puede cobrar los puntos otra vez. Con el `Idempotency-Key`, mandar la misma clave
de nuevo no repite la compra.
Genera un valor por cada compra que el usuario inicia (un UUID alcanza) y usa
el mismo en todos los reintentos de esa compra.
## Cuerpo
Id del beneficio a comprar, tal como lo devuelve
[beneficios que puedo comprar](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles).
## Respuesta
Un objeto
[Beneficio canjeable](https://docs.loybox.com.ar/api-reference/objetos#beneficio-canjeable).
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits/exchange \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87" \
-H "Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b" \
-H "Content-Type: application/json" \
-d '{
"benefit_id": "b_9f2a"
}'
```
```json
// 200 OK
{
"client_benefit_code": 887766,
"issue_date": "2026-08-24T13:05:00Z",
"due_date": "2026-09-23T13:05:00Z",
"used": false,
"benefit": {
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
}
}
```
El `client_benefit_code` es lo que hay que mostrarle al usuario: es su código de
canje y también el código de cupón en una tienda online. Después de comprar,
conviene refrescar los `points` con
[`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).
## Errores
| Código | Cuándo |
| ------ | -------------------------------------------------------------------------------- |
| `400` | El beneficio no existe, no está vigente, o al usuario no le alcanzan los puntos. |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `422` | Falta el header `X-Commerce-Id`, o falta el `benefit_id`. |
El `400` junta los tres casos, así que conviene prevenirlos en la UI: no ofrezcas
comprar un beneficio cuyo `cost` supere los puntos del usuario.
# Mis beneficios (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/mis-beneficios)
Beneficios que el usuario ya compró con sus puntos en este comercio y todavía
puede canjear.
El `client_benefit_code` de cada item es el código que el usuario presenta en el
comercio para canjearlo.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un array de
[Beneficio canjeable](https://docs.loybox.com.ar/api-reference/objetos#beneficio-canjeable).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
[
{
"client_benefit_code": 887766,
"issue_date": "2026-08-24T13:05:00Z",
"due_date": "2026-09-23T13:05:00Z",
"used": false,
"benefit": {
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
}
}
]
```
En una tienda online, el `client_benefit_code` es lo que el usuario pega en el
checkout. Conviene mostrarlo grande y con un botón de copiar, y al lado el
`due_date` para que sepa hasta cuándo lo puede usar.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `422` | Falta el header `X-Commerce-Id`. |
# Mi historial (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/historial)
Movimientos del usuario en el programa del comercio: consumos que sumaron
puntos, compras de beneficios, canjes y recompensas especiales.
Paginado por cursor: para traer la página siguiente se pasa el `next_cursor` de
la respuesta anterior en `?cursor=`.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Parámetros
Cursor de la página a traer. Se obtiene del `next_cursor` de la respuesta
anterior. Sin especificar, trae la primera página.
## Respuesta
Los movimientos de esta página. Ver
[Movimiento](https://docs.loybox.com.ar/api-reference/objetos#movimiento).
Se pasa como `?cursor=` para traer la página siguiente. `null` cuando no hay
más.
El cursor de la página anterior.
## Ejemplo
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/activity \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
{
"results": [
{
"type": "consumption",
"date": "2026-08-20T18:42:00Z",
"points": 17,
"benefit": null,
"amount": 1750,
"event": null,
"additional_note": null
},
{
"type": "benefit_exchange",
"date": "2026-08-24T13:05:00Z",
"points": -250,
"benefit": {
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": null,
"tiendanube_coupon": null
},
"amount": null,
"event": null,
"additional_note": null
}
],
"next_cursor": "eyJkIjoiMjAyNi0wOC0yMCJ9",
"previous_cursor": null
}
```
## Los cuatro tipos de movimiento
| `type` | Qué pasó | Campos que trae |
| ----------------------- | --------------------------------------- | ------------------------------ |
| `consumption` | Una compra que sumó puntos | `amount`, `points` |
| `benefit_exchange` | Compró un beneficio con puntos | `benefit`, `points` (negativo) |
| `benefit_usage` | Canjeó un beneficio en el comercio | `benefit` |
| `points_special_reward` | Una recompensa automática le dio puntos | `event`, `points` |
Como los campos que vienen cargados dependen del `type`, conviene armar la fila
del historial con un `switch` sobre `type` y no leer todos los campos siempre.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `422` | Falta el header `X-Commerce-Id`. |
# Mi nivel (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/nivel)
Nivel actual del usuario en este comercio, con su multiplicador de puntos, el
progreso acumulado y cuál es el próximo nivel.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un objeto [Nivel](https://docs.loybox.com.ar/api-reference/objetos#nivel).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/level \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
{
"name": "Plata",
"rank": 2,
"points_multiplier": 1.25,
"icon_url": "https://cdn.loybox.com.ar/levels/plata.png",
"reached_at": "2026-05-11T10:00:00Z",
"expiration_date": "2027-05-11T10:00:00Z",
"is_expired": false,
"next_level": {
"name": "Oro",
"rank": 3,
"threshold_type": "points",
"threshold": 5000
},
"total_earned_points": 3120,
"total_spent_amount": 312000,
"total_consumptions_count": 48
}
```
## Cómo armar la barra de progreso
El progreso se calcula contra el acumulado histórico, no contra el saldo. Según
el `threshold_type` del próximo nivel:
| `threshold_type` | Compararlo con |
| ----------------- | --------------------- |
| Por puntos | `total_earned_points` |
| Por monto gastado | `total_spent_amount` |
El nivel se mide sobre el historial completo de la relación, así que gastar
puntos baja el saldo pero nunca el nivel. Ver
[Cómo suben de nivel](https://docs.loybox.com.ar/niveles/como-suben-de-nivel).
## Errores
| Código | Cuándo |
| ------ | ------------------------------------------------------------------------------------------ |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `404` | El usuario todavía no tiene nivel asignado en este comercio, o el comercio no usa niveles. |
| `422` | Falta el header `X-Commerce-Id`. |
No lo trates como una falla. Cuando el usuario todavía no tiene nivel, o el
comercio no usa niveles, corresponde **esconder la sección de niveles** en la UI,
no mostrar un error.
# Recompensas del programa (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/recompensas)
Recompensas que el comercio entrega solas cuando pasa algo: la de bienvenida al
adherirse, la de cumpleaños, la de cliente del mes.
Cada una indica si da un beneficio o puntos. Sirve para mostrarle al usuario qué
gana **además** de canjear puntos.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un array de
[Recompensa automática](https://docs.loybox.com.ar/api-reference/objetos#recompensa-automática).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/rewards \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
[
{
"event": "welcome",
"reward_type": "benefit",
"benefit": {
"id": "b_4c81",
"type": "free_product",
"description": "Café de regalo",
"cost": 0,
"expiration": null,
"benefit_type": "welcome",
"color": "#f1a10d",
"buy_limit": 1,
"prize": null,
"tiendanube_coupon": null
},
"points": null
},
{
"event": "birthday",
"reward_type": "points",
"benefit": null,
"points": 200
}
]
```
## Los tres eventos
| `event` | Cuándo se entrega |
| ------------- | ----------------------------------- |
| `welcome` | Al adherirse al programa |
| `birthday` | En el cumpleaños del cliente |
| `monthly_top` | Al cliente que más compró en el mes |
El `reward_type` dice dónde mirar: si es `benefit`, la recompensa está en `benefit`;
si es `points`, está en `points`. El otro campo viene en `null`.
Devuelve las recompensas **configuradas** por el comercio, no las que el usuario
ya recibió. Para eso está
[mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial), donde las recompensas de
puntos aparecen como movimientos de tipo `points_special_reward`.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `404` | El comercio no existe. |
| `422` | Falta el header `X-Commerce-Id`. |
# Adherirme al programa (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/adherirme)
Adhiere al usuario al programa de lealtad del comercio. Si el comercio
configuró una recompensa de bienvenida, se devuelve en `welcome_benefit` o
`welcome_points`.
[Verificar un código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) ya deja al
usuario adherido, así que este endpoint sirve **sobre todo para volver a
adherirse después de una baja**.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
No lleva cuerpo.
## Respuesta
Resultado de la operación.
Beneficio de bienvenida, si el comercio configuró uno y el usuario recién se
adhirió. Ver [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
Puntos de bienvenida, si el comercio configuró puntos en vez de un beneficio.
```bash
curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/subscription \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
{
"message": "Subscribed successfully",
"welcome_benefit": {
"id": "b_4c81",
"type": "free_product",
"description": "Café de regalo",
"cost": 0,
"expiration": null,
"benefit_type": "welcome",
"color": "#f1a10d",
"buy_limit": 1,
"prize": null,
"tiendanube_coupon": null
},
"welcome_points": null
}
```
Los dos campos de bienvenida son excluyentes: viene uno o el otro, según lo que
el comercio haya configurado. Si no configuró nada, vienen los dos en `null`.
Es un buen momento para mostrar una pantalla de bienvenida: si vino
`welcome_benefit`, la recompensa; si vino `welcome_points`, los puntos que acaba de
ganar.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `404` | El comercio no existe. |
| `422` | Falta el header `X-Commerce-Id`. |
# Darme de baja (https://docs.loybox.com.ar/es-419/api-reference/mi-cuenta/darme-de-baja)
Da de baja al usuario del programa del comercio.
Los puntos acumulados quedan donde están: si el usuario
[vuelve a adherirse](https://docs.loybox.com.ar/api-reference/mi-cuenta/adherirme), siguen estando.
Vale la pena decírselo en la pantalla de confirmación: es la diferencia entre
una baja y un borrado, y saberlo hace que dar de baja no dé miedo.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
No lleva cuerpo.
## Respuesta
`200 OK`. La respuesta no tiene una forma definida: alcanza con mirar el código
de estado.
```bash
curl -X DELETE https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/subscription \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Commerce-Id: 87"
```
Después de la baja, [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) devuelve
`subscribed: false`.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------------------------- |
| `401` | El token de acceso falta, venció o no corresponde a un usuario final. |
| `404` | El comercio no existe, o el usuario no estaba adherido. |
| `422` | Falta el header `X-Commerce-Id`. |
El `404` cubre también el caso de una baja repetida: si el usuario ya no estaba
adherido, no hay nada que dar de baja.
# Público (https://docs.loybox.com.ar/es-419/api-reference/publico)
Endpoints que **no requieren ningún token**, sólo el header `X-Commerce-Id`.
Sirven para mostrarle tu programa de lealtad a un visitante que todavía no
inició sesión: la marca en el header y el catálogo de recompensas, para que vea qué
gana si se suma.
```
X-Commerce-Id: {tu-commerce-id}
```
## Los endpoints
## Después del inicio de sesión, no hace falta volver a pedirlos
Una vez que el usuario inicia sesión, los mismos datos vienen por los endpoints
de [Mi cuenta](https://docs.loybox.com.ar/api-reference/mi-cuenta):
| Sin sesión | Con sesión |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`GET /v1/public/commerce`](https://docs.loybox.com.ar/api-reference/publico/comercio) | Viene dentro de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) |
| [`GET /v1/public/benefits`](https://docs.loybox.com.ar/api-reference/publico/beneficios) | [`GET /v1/me/benefits/available`](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) |
En la práctica: usa los públicos para la pantalla de bienvenida, y cambia a los
de Mi cuenta en cuanto haya sesión.
Va en el frontend sin problema. Lo que hace es delimitar la respuesta a tu
comercio, no autorizar el acceso.
# Datos del comercio (https://docs.loybox.com.ar/es-419/api-reference/publico/comercio)
Nombre, logo, color de marca y giro del comercio, **sin necesidad de token**.
Sirve para pintar el header del programa antes de que el usuario inicie sesión.
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un objeto [Comercio](https://docs.loybox.com.ar/api-reference/objetos#comercio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/public/commerce \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
{
"id": 87,
"name": "Tienda Central",
"logo": "https://cdn.loybox.com.ar/logos/87.png",
"color": "#f1a10d",
"category_name": "Tienda de comics",
"currency": "ARS"
}
```
Una vez iniciada la sesión, los mismos datos vienen dentro de
[`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener) en el campo `commerce`, así que
no hace falta volver a pedirlos.
## Errores
| Código | Cuándo |
| ------ | -------------------------------- |
| `400` | No se pudo obtener el comercio. |
| `422` | Falta el header `X-Commerce-Id`. |
# Catálogo de beneficios (https://docs.loybox.com.ar/es-419/api-reference/publico/beneficios)
Beneficios vigentes del comercio, **sin necesidad de token**.
Sirve para mostrarle el programa de lealtad a un visitante que todavía no
inició sesión: es la vitrina de recompensas que responde "¿qué gano si me sumo?".
## Headers
Id del comercio que integra la API. Todas las respuestas quedan limitadas a
este comercio.
## Respuesta
Un array de [Beneficio](https://docs.loybox.com.ar/api-reference/objetos#beneficio).
```bash
curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/public/benefits \
-H "X-Commerce-Id: 87"
```
```json
// 200 OK
[
{
"id": "b_9f2a",
"type": "percentage_discount",
"description": "20% de descuento en toda la tienda",
"cost": 250,
"expiration": "2026-12-31T23:59:59Z",
"benefit_type": "normal",
"color": "#f1a10d",
"buy_limit": 0,
"prize": {
"type": "percentage_discount",
"title": "20% off",
"description": "Válido en toda la tienda",
"value": 20,
"product": null,
"expiration": "2026-12-31T23:59:59Z",
"image": null
},
"tiendanube_coupon": null
}
]
```
Una vez iniciada la sesión conviene usar
[`GET /v1/me/benefits/available`](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles),
que es el mismo catálogo pero ya filtrado por lo que el comercio habilitó para
ese usuario.
## Errores
| Código | Cuándo |
| ------ | --------------------------------------------------- |
| `400` | No se pudieron obtener los beneficios del comercio. |
| `422` | Falta el header `X-Commerce-Id`. |