# Documentación de Loybox

> Loybox es una plataforma de fidelización para marcas: cada marca arma su
> propio club de miembros donde los clientes acumulan puntos con cada compra y
> los canjean por premios, con niveles VIP, referidos, reseñas, recomendaciones
> y campañas.

Este archivo es el texto completo de toda la documentación, 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.

Índice de páginas y resumen de la API: https://docs.loybox.com.ar/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/introduccion)



Los anuncios traen clientes. La fidelidad los hace volver.

**Loybox es la plataforma para crear tu propio club de miembros**: una app con tu
marca para locales físicos, o integrada a tu tienda online, con la que
premiás a tus clientes, aumentás la recurrencia y hacés crecer el valor de
cada relación.

## El problema que resuelve [#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
fidelización, dependés de seguir pagando para traer una y otra vez al mismo
perfil de cliente.

<Cards>
  <Card title="+67% de gasto" description="Lo que gasta de más un cliente recurrente frente a uno nuevo." />

  <Card title="2,5× frecuencia" description="Aumento típico en la frecuencia de compra con un club activo." />

  <Card title="+10% ticket promedio" description="Los miembros compran más en cada visita." />

  <Card title="$0 de adquisición" description="Un cliente que vuelve no se vuelve a pagar." />
</Cards>

## Cómo funciona, en una frase [#cómo-funciona-en-una-frase]

Tus clientes suman puntos con cada compra y los canjean por los premios
exclusivos 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 [#tu-club-en-todos-tus-canales]

<Cards>
  <Card title="Locales físicos" icon="Smartphone" description="Una app (PWA) con tu identidad que tus clientes llevan en el teléfono, accesible al instante desde cualquier navegador o instalable desde las stores." />

  <Card title="Tienda online" icon="ShoppingCart" description="La misma experiencia integrada a tu ecommerce: puntos automáticos post-compra y canje de premios en el checkout, sin que el cliente salga del flujo." />
</Cards>

## Por dónde empezar [#por-dónde-empezar]

Esta documentación crece herramienta por herramienta. Arrancá por los fundamentos:

<Cards>
  <Card title="Conceptos" icon="BookText" href="/conceptos" description="El modelo mental de Loybox: marcas, clientes, puntos y premios." />

  <Card title="Puntos y premios" icon="Gift" href="/puntos-y-premios" description="El corazón del programa: cómo se ganan los puntos y cómo se canjean." />
</Cards>


# Conceptos (https://docs.loybox.com.ar/conceptos)



Antes de configurar tu club conviene tener claro el vocabulario. Todo Loybox
se construye sobre cuatro piezas.

## Las piezas [#las-piezas]

<Cards>
  <Card title="Marca" icon="Building2" description="Tu empresa dentro de Loybox. Define la moneda, las reglas de puntos, los premios y la identidad de la app. Puede tener una o varias sucursales." />

  <Card title="Cliente" icon="User" description="La persona que se suma a tu club. Cada cliente tiene una relación con tu marca, con su propio saldo de puntos e historial." />

  <Card title="Punto" icon="Coins" description="La unidad de fidelidad. Se gana con cada compra (y otras acciones) y se gasta canjeando premios." />

  <Card title="Premio" icon="Gift" description="La recompensa que tu cliente obtiene a cambio de puntos: un descuento, un producto gratis o un beneficio exclusivo de tu marca." />
</Cards>

## El ciclo de fidelidad [#el-ciclo-de-fidelidad]

El corazón de Loybox es un ciclo simple que se repite y se refuerza en cada
visita:

<Steps>
  <Step>
    ### El cliente compra [#el-cliente-compra]

    En tu local o en tu tienda online. Cada compra queda registrada como un
    consumo.
  </Step>

  <Step>
    ### Suma puntos [#suma-puntos]

    El consumo genera puntos automáticamente, según las reglas que definís
    (ver [Ganar puntos](https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)).
  </Step>

  <Step>
    ### Canjea premios [#canjea-premios]

    Cuando junta suficientes puntos, los cambia por uno de los premios de tu
    catálogo.
  </Step>

  <Step>
    ### Vuelve [#vuelve]

    El premio y el progreso hacia el próximo lo traen de nuevo. La compra se
    vuelve un hábito.
  </Step>
</Steps>

## Saldo de puntos [#saldo-de-puntos]

<Callout title="El saldo siempre se calcula, nunca se “guarda”">
  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.
</Callout>

## Multi-canal [#multi-canal]

Una misma marca puede operar su club en locales físicos (app PWA con tu
marca) y en su tienda online (integrado al checkout). Las reglas de puntos
y el catálogo de premios se comparten: el cliente vive una sola experiencia,
sin importar por dónde compre.


# Fundamentos (https://docs.loybox.com.ar/puntos-y-premios)



El sistema de puntos y premios 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 [#de-un-vistazo]

<Cards>
  <Card title="Ganar puntos" icon="Coins" href="/puntos-y-premios/ganar-puntos" description="Cómo se calculan los puntos de cada compra y qué otras acciones suman." />

  <Card title="Vencimiento" icon="Clock" href="/puntos-y-premios/expiracion" description="Los tres modos de vencimiento y cuándo conviene cada uno." />

  <Card title="Premios" icon="Gift" href="/puntos-y-premios/premios" description="Cómo armar tu catálogo: tipos de premio, costo en puntos, stock y vigencia." />

  <Card title="Canje" icon="BadgeCheck" href="/puntos-y-premios/canje" description="Qué pasa cuando un cliente canjea y cómo lo valida tu equipo." />
</Cards>

## El flujo, punta a punta [#el-flujo-punta-a-punta]

<Steps>
  <Step>
    ### Configurás las reglas [#configurás-las-reglas]

    Definís cuántos puntos vale cada compra y (opcionalmente) cuándo vencen.
  </Step>

  <Step>
    ### Armás el catálogo de premios [#armás-el-catálogo-de-premios]

    Creás los premios con su costo en puntos, stock y vigencia.
  </Step>

  <Step>
    ### El cliente acumula [#el-cliente-acumula]

    Cada compra suma puntos a su saldo automáticamente.
  </Step>

  <Step>
    ### El cliente canjea [#el-cliente-canjea]

    Cambia sus puntos por un premio y tu equipo lo valida con un código.
  </Step>
</Steps>

<Callout type="info" title="Todo es configurable por marca">
  Cada marca define sus propias reglas de puntos, sus modos de vencimiento y
  su catálogo de premios. Nada está fijo: el sistema se adapta a cómo querés
  premiar a tus clientes.
</Callout>


# Ganar puntos (https://docs.loybox.com.ar/puntos-y-premios/ganar-puntos)



Cada compra genera puntos automáticamente. Cómo se traduce el monto de la
compra en puntos lo definís vos.

## La regla principal: dinero por punto [#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 )
```

<Callout title="Ejemplo">
  Si configurás $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.
</Callout>

Es un solo valor para ajustar: bajás el "dinero por punto" para que los puntos
se acumulen más rápido, o lo subís para que cuesten más.

## Conversión automática por moneda [#conversión-automática-por-moneda]

Si no definís 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 |

<Callout type="info">
  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 definís tu propia regla de "dinero por punto", esta conversión deja de
  aplicar.
</Callout>

## Multiplicadores [#multiplicadores]

Sobre el cálculo base, dos ajustes pueden aumentar los puntos de una compra:

<Cards>
  <Card title="Puntos dobles" description="Activá una promoción de puntos dobles y cada compra otorga el doble de puntos mientras esté vigente. Ideal para fechas especiales o para impulsar un período flojo." />

  <Card title="Bonus por nivel" href="/niveles/beneficios-de-nivel" description="Si usás niveles VIP, cada nivel puede sumar un porcentaje extra de puntos. Un nivel con +10% hace que una compra de 100 puntos otorgue 110." />
</Cards>

<Callout title="Cómo se combinan">
  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 bonus porcentual del nivel del cliente. El bonus de nivel se
  aplica según el nivel que el cliente tiene en el momento de la compra.
</Callout>

## Otras formas de sumar puntos [#otras-formas-de-sumar-puntos]

La compra es la fuente principal, pero no la única. Loybox puede otorgar
puntos también por:

<Cards>
  <Card title="Referidos" icon="UserPlus" href="/referidos" description="Cuando un cliente invita a otro y el invitado hace su primera compra, ambos ganan puntos. Vos definís cuántos." />

  <Card title="Cumpleaños" icon="Cake" description="Un regalo de puntos automático en el cumpleaños del cliente para reactivarlo." />

  <Card title="Bienvenida" icon="Handshake" description="Puntos de arranque al sumarse al club, para que empiece con saldo y sienta el valor desde el día uno." />

  <Card title="Alcanzar un nivel" icon="Crown" description="Al llegar por primera vez a un nivel VIP, el cliente puede recibir un premio de puntos por única vez." />
</Cards>


# Vencimiento de puntos (https://docs.loybox.com.ar/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 [#los-tres-modos]

<Cards>
  <Card title="Sin vencimiento" description="Los puntos no vencen nunca. El saldo del cliente se mantiene mientras siga en tu club. Es el modo por defecto." />

  <Card title="Acumulado" description="Todo el saldo comparte una única fecha de vencimiento, que se renueva con cada nueva compra." />

  <Card title="Por transacción" description="Cada compra tiene su propia fecha de vencimiento independiente. Los puntos vencen por lotes, según cuándo se ganaron." />
</Cards>

## El período de vencimiento [#el-período-de-vencimiento]

Cuando activás el vencimiento, definís un período en días. Los puntos de
una compra vencen una vez transcurrido ese período desde que se ganaron.

<Callout type="info" title="Sin días, no hay vencimiento">
  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.
</Callout>

## Acumulado vs. por transacción [#acumulado-vs-por-transacción]

La diferencia clave es qué pasa cuando el cliente vuelve a comprar:

<Cards>
  <Card title="Acumulado: “se reinicia el reloj”" description="Cada compra nueva empuja la fecha de vencimiento de TODO el saldo hacia adelante. Mientras el cliente siga comprando, no pierde puntos; si deja de comprar, todo su saldo vence junto." />

  <Card title="Por transacción: “cada consumo su reloj”" description="Los puntos de cada compra vencen a su propio ritmo, sin importar las compras siguientes. Es más estricto: los puntos viejos vencen aunque el cliente siga activo." />
</Cards>

<Callout title="Cuál elegir">
  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
  arrancás y no querés fricción, empezá sin vencimiento y sumá una regla más
  adelante.
</Callout>

## Cómo lo ve el cliente [#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.


# Premios (https://docs.loybox.com.ar/puntos-y-premios/premios)





Los premios son las recompensas que tus clientes obtienen a cambio de puntos.
Tu catálogo de premios es lo que le da sentido a acumular: cuanto más deseable
sea, más fuerte es el incentivo para volver.

<img alt="Catálogo de premios en el panel de Loybox" src="__img0" />

<Callout title="¿Querés crear uno ahora?">
  Seguí la guía paso a paso: [Crear un premio](https://docs.loybox.com.ar/puntos-y-premios/crear-un-premio).
</Callout>

## Qué configurás en un premio [#qué-configurás-en-un-premio]

Cada premio se define con un puñado de campos:

<Cards>
  <Card title="Tipo y valor" description="Qué recibe el cliente: un producto gratis, un descuento, un vale, envío gratis, etc. El tipo y su valor son el corazón del premio." />

  <Card title="Costo en puntos" description="Cuántos puntos cuesta canjearlo. Definís si es un premio fácil de alcanzar o uno más ambicioso." />

  <Card title="Límite de canjes" description="Cuántas veces puede canjearse en total. Dejalo en cero para que sea ilimitado, o poné un tope para premios de edición limitada." />

  <Card title="Vencimiento" description="La fecha hasta la que el premio está disponible para canjear. Ideal para promociones por tiempo limitado." />

  <Card title="Imagen" description="Una foto opcional para que se vea atractivo. Si no subís ninguna, se usa un ícono según el tipo." />
</Cards>

<Callout type="info" title="El nombre se arma solo">
  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 elegís. Menos
  campos, menos fricción.
</Callout>

## Tipos de premio [#tipos-de-premio]

Un premio puede entregar distintos tipos de recompensa:

<Cards>
  <Card title="Producto gratis" icon="Package" description="Un producto de tu catálogo, sin cargo." />

  <Card title="Vale de dinero ($)" icon="Banknote" description="Un monto fijo de descuento, por ejemplo $500." />

  <Card title="Descuento porcentual (%)" icon="Percent" description="Un % de descuento sobre la compra, por ejemplo 20% off." />

  <Card title="2x1" icon="Layers" description="Una promoción dos por uno." />

  <Card title="Envío gratis" icon="Truck" description="El envío sin costo." />

  <Card title="Otro" icon="Sparkles" description="Cualquier beneficio que definas con texto libre." />
</Cards>

## El estado de un premio [#el-estado-de-un-premio]

En cada momento, un premio 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.     |

<Callout type="info">
  Sólo los premios activos (vigentes, con stock y sin pausar) aparecen
  disponibles para que el cliente los canjee.
</Callout>

## Premios para ocasiones especiales [#premios-para-ocasiones-especiales]

Además de los premios de catálogo general, podés reservar premios para
momentos concretos del recorrido del cliente:

<Cards>
  <Card title="Bienvenida" description="Un premio pensado para quien recién se suma al club." />

  <Card title="Cumpleaños" description="Una recompensa especial para la fecha del cliente." />

  <Card title="Top del mes" description="Para reconocer a tu mejor cliente del período." />

  <Card title="Por nivel" description="Premios exclusivos desbloqueados por alcanzar un nivel VIP." />
</Cards>


# Crear un premio (https://docs.loybox.com.ar/puntos-y-premios/crear-un-premio)





Crear un premio toma menos de un minuto. En esta guía lo hacemos de punta a
punta desde el panel.

<img alt="Modal Nuevo premio en el panel de Loybox" src="__img0" />

## Paso a paso [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Premios** [#entrá-a-premios]

    En el menú lateral, dentro de **Fidelización**, tocá **Premios**. Vas a ver tu
    **Catálogo de premios**.
  </Step>

  <Step>
    ### Tocá **Nuevo premio** [#tocá-nuevo-premio]

    El botón está arriba a la derecha del catálogo. Se abre una ventana para
    armar el premio. (Si todavía no tenés ninguno, el botón dice **Crear premio**.)
  </Step>

  <Step>
    ### Elegí el **Tipo de premio** [#elegí-el-tipo-de-premio]

    En el desplegable **Tipo de premio**, elegí qué va a recibir el cliente:

    | Tipo                         | Qué entrega                                      |
    | ---------------------------- | ------------------------------------------------ |
    | **Producto gratis**          | Un producto de tu catálogo, sin cargo.           |
    | **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. |
  </Step>

  <Step>
    ### Completá el valor del premio [#completá-el-valor-del-premio]

    Según el tipo, aparece un campo distinto:

    * **Vale de dinero** → &#x2A;*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 podés sumar un &#x2A;*Detalle (opcional)** para
    afinar el texto que ve el cliente (por ejemplo, “en tu próxima compra”).
  </Step>

  <Step>
    ### Subí una imagen &#x2A;(opcional)* [#subí-una-imagen-opcional]

    En &#x2A;*Imagen del premio (opcional)** podés subir una foto (PNG, JPG o WEBP, hasta
    5 MB). Si no subís ninguna, Loybox usa un ícono según el tipo de premio.
  </Step>

  <Step>
    ### Poné el &#x2A;*Precio (puntos)** [#poné-el-precio-puntos]

    Es cuántos puntos cuesta canjear el premio. Es obligatorio y tiene que ser
    mayor a cero: hasta que lo completes, el botón de guardar queda deshabilitado.
  </Step>

  <Step>
    ### Ajustá los límites &#x2A;(opcional)* [#ajustá-los-límites-opcional]

    * **Límite de canjes (opcional)**: cuántas veces puede canjearse en total.
      Dejalo 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”).
  </Step>

  <Step>
    ### Revisá la **Vista previa** [#revisá-la-vista-previa]

    A un costado vas a ver una **Vista previa** que muestra el premio tal como lo
    verá el cliente en su app, y se actualiza a medida que completás los campos.
  </Step>

  <Step>
    ### Tocá **Crear premio** [#tocá-crear-premio]

    Listo: el premio se guarda y aparece en tu **Catálogo de premios**, disponible
    para canje. Podés crear todos los que quieras.
  </Step>
</Steps>

## Dos cosas que conviene saber [#dos-cosas-que-conviene-saber]

<Callout title="No le pongas nombre: se arma solo">
  No hay un campo de nombre ni de descripción. El título y el texto del premio se
  generan automáticamente a partir del tipo y el valor que elegís, y podés
  verlos en la vista previa.
</Callout>

<Callout type="info" title="El estado se calcula solo">
  No hay un interruptor de “activo” al crear. Si el premio está disponible,
  agotado o vencido surge de su configuración (precio, límite de canjes y
  vencimiento). Podés ver el estado de cada premio en el catálogo.
</Callout>

## Si tenés Tiendanube conectado [#si-tenés-tiendanube-conectado]

Si tu tienda de Tiendanube está conectada, al crear un premio aparece un
interruptor **Cupón Tiendanube**. Al activarlo, el premio genera un cupón
real en tu tienda cuando el cliente lo canjea, y elegís 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.

<Callout>
  Con el cupón de Tiendanube activado, el premio 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.
</Callout>


# Canje (https://docs.loybox.com.ar/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
el premio y le da a tu equipo una forma simple de validarlo.

## El flujo, paso a paso [#el-flujo-paso-a-paso]

<Steps>
  <Step>
    ### El cliente elige un premio [#el-cliente-elige-un-premio]

    Desde la app ve el catálogo de premios disponibles y cuánto cuesta cada uno en
    puntos.
  </Step>

  <Step>
    ### Loybox valida el saldo [#loybox-valida-el-saldo]

    El canje sólo procede si el cliente tiene puntos suficientes para cubrir el
    costo del premio. Si no llega, se le avisa cuántos le faltan.
  </Step>

  <Step>
    ### Se descuentan los puntos [#se-descuentan-los-puntos]

    Al confirmar, se registra el canje y el costo del premio se resta del saldo.
    El cliente queda con el premio a su nombre y un código de validación.
  </Step>

  <Step>
    ### Tu equipo valida el código [#tu-equipo-valida-el-código]

    En el local (o en el checkout de tu tienda), tu equipo ingresa el código para
    confirmar el premio y marcarlo como usado.
  </Step>
</Steps>

## El código de validación [#el-código-de-validación]

Cada premio canjeado lleva un código corto y único que el cliente presenta
al momento de usarlo.

<Callout title="Cómo funciona la validación">
  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 el mismo premio se use dos
  veces.
</Callout>

## Canje y saldo [#canje-y-saldo]

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

## Vigencia del premio canjeado [#vigencia-del-premio-canjeado]

Un premio ya canjeado mantiene la fecha de vigencia del premio original: el
cliente lo tiene reservado, pero debe usarlo antes de que venza. Esto
mantiene el catálogo sano y evita premios "eternos" acumulados sin usar.


# Fundamentos (https://docs.loybox.com.ar/niveles)





Los niveles son la herramienta con la que reconocés 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 fidelidad sostenida, más allá de cada
compra puntual.

<img alt="Sección Niveles en el panel de Loybox" src="__img0" />

## Qué es un nivel [#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:

<Cards>
  <Card title="Un nombre" icon="Tag" description="Cómo lo ve el cliente (por ejemplo, Plata, Oro, Platino). El nombre comunica estatus." />

  <Card title="Un umbral" icon="TrendingUp" description="Cuánto necesita acumular para alcanzarlo: puntos o monto gastado." />

  <Card title="Beneficios propios" icon="Gift" description="Un multiplicador de puntos, un premio al llegar y recompensas exclusivas del nivel." />

  <Card title="Un ícono" icon="Crown" description="Un distintivo visual que refuerza el logro dentro de la app." />
</Cards>

## El nivel base [#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 [#cómo-funciona-de-un-vistazo]

<Steps>
  <Step>
    ### El cliente se suma [#el-cliente-se-suma]

    Entra automáticamente en el nivel base.
  </Step>

  <Step>
    ### Acumula y avanza [#acumula-y-avanza]

    Con cada compra suma hacia el umbral del próximo nivel. Al alcanzarlo, sube.
  </Step>

  <Step>
    ### Desbloquea beneficios [#desbloquea-beneficios]

    Cada nivel mejora lo que recibe: más puntos por compra, premios exclusivos y
    reconocimiento.
  </Step>

  <Step>
    ### Mantiene su estatus [#mantiene-su-estatus]

    Mientras siga activo, conserva (y sigue subiendo) su nivel.
  </Step>
</Steps>

<Callout title="Un incentivo para volver">
  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.
</Callout>


# Cómo suben de nivel (https://docs.loybox.com.ar/niveles/como-suben-de-nivel)



Cada nivel tiene un umbral: lo que el cliente necesita acumular para
alcanzarlo. Vos elegís en qué se mide ese umbral.

## Dos formas de medir el avance [#dos-formas-de-medir-el-avance]

<Cards>
  <Card title="Por puntos acumulados" description="El cliente sube según el total de puntos que ganó a lo largo del tiempo. Premia la actividad y el compromiso con el programa." />

  <Card title="Por monto gastado" description="El cliente sube según cuánto gastó en total. Premia el valor real que aporta a tu marca." />
</Cards>

Cada nivel se mide con su propio criterio, así que podés combinar ambos dentro
de la misma escalera si tiene sentido para tu marca.

## Se mide sobre el historial completo [#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.

<Callout type="info" title="Canjear no baja de nivel">
  Cuando un cliente gasta sus puntos en un premio, 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 premios sin miedo a
  perder su estatus.
</Callout>

## Cómo se calcula el nivel [#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.

<Callout title="Los umbrales siempre son crecientes">
  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.
</Callout>


# Beneficios de cada nivel (https://docs.loybox.com.ar/niveles/beneficios-de-nivel)



Cada nivel puede mejorar lo que el cliente recibe de tres formas.

## Multiplicador de puntos [#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.

<Callout title="Cómo se lee el multiplicador">
  El multiplicador es un bonus porcentual: 0 % = sin bonus, 10 % = +10 %,
  100 % = el doble de puntos. Un cliente “Oro” con +20 % que hace una compra
  de 100 puntos, se lleva 120.
</Callout>

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.

## Premio al alcanzar el nivel [#premio-al-alcanzar-el-nivel]

Podés otorgar un premio 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.

<Callout type="info" title="Se entrega una sola vez">
  El premio 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.
</Callout>

## Recompensas exclusivas del nivel [#recompensas-exclusivas-del-nivel]

Además del premio de llegada, un nivel puede tener recompensas que sólo
disfrutan quienes están en él:

<Cards>
  <Card title="Premios exclusivos" description="Beneficios reservados para el nivel, que no aparecen en el catálogo general." />

  <Card title="Recompensas por ocasión" description="Regalos recurrentes atados a momentos (cumpleaños, cliente del mes, bienvenida) que aplican mientras el cliente esté en ese nivel." />
</Cards>

## Más allá de los puntos [#más-allá-de-los-puntos]

Un nivel no tiene por qué basarse sólo en más puntos. También podés sumar
beneficios que no dependen de un descuento:

<Cards>
  <Card title="Acceso anticipado" description="A lanzamientos, preventas y ediciones limitadas antes que el resto." />

  <Card title="Experiencias" description="Eventos, degustaciones o encuentros reservados para los niveles altos." />

  <Card title="Reconocimiento" description="Un distintivo visible o un trato preferencial dentro del club." />
</Cards>

<Callout title="Cómo combinarlos">
  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.
</Callout>


# Vencimiento y descenso (https://docs.loybox.com.ar/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 [#niveles-que-se-mantienen]

Podés 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.

<Callout type="info" title="El descenso es de a un escalón">
  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.
</Callout>

## Se puede volver a subir [#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 [#dónde-aplica]

<Callout title="El nivel base nunca vence">
  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.
</Callout>

## Cuándo conviene [#cuándo-conviene]

<Cards>
  <Card title="Con vencimiento" description="El nivel se mantiene con actividad. Útil para marcas de compra frecuente, donde tiene sentido pedir constancia para conservar el nivel." />

  <Card title="Sin vencimiento" description="El nivel alcanzado es permanente. Útil si preferís que, una vez logrado, el cliente no lo pierda." />
</Cards>

<Callout title="Cómo calibrar el período">
  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.
</Callout>


# Armá tus niveles (https://docs.loybox.com.ar/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 [#los-pasos]

<Steps>
  <Step>
    ### Definí el nivel base [#definí-el-nivel-base]

    Es el escalón de entrada, sin requisitos: todos empiezan ahí. No lleva umbral
    ni vencimiento.
  </Step>

  <Step>
    ### Agregá tus niveles VIP [#agregá-tus-niveles-vip]

    Creá 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.
  </Step>

  <Step>
    ### Elegí cómo se mide cada uno [#elegí-cómo-se-mide-cada-uno]

    Definí si el umbral es por puntos acumulados o por monto gastado, y el
    valor a alcanzar. Recordá: cada nivel superior debe pedir más que el anterior.
  </Step>

  <Step>
    ### Cargá los beneficios [#cargá-los-beneficios]

    Para cada nivel, definí el multiplicador de puntos, el premio al alcanzarlo y
    las recompensas exclusivas. Que cada escalón se sienta mejor que el anterior.
  </Step>

  <Step>
    ### Ponele nombre e ícono [#ponele-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.
  </Step>
</Steps>

## Reglas que conviene tener en cuenta [#reglas-que-conviene-tener-en-cuenta]

<Cards>
  <Card title="El nivel base no vence ni pide umbral" description="Es el punto de partida de todos: siempre existe, con umbral cero y sin vencimiento." />

  <Card title="Los umbrales van de menor a mayor" description="Un nivel más alto no puede exigir menos que uno más bajo. Loybox mantiene la escalera ordenada." />

  <Card title="Cada nivel, mejor que el anterior" description="El progreso tiene que notarse. Si un escalón no aporta nada nuevo, sobra." />
</Cards>

## Niveles propios o los de Loybox [#niveles-propios-o-los-de-loybox]

Podés usar una escalera de niveles propia, diseñada a medida de tu marca, o
partir de la configuración por defecto de Loybox para arrancar rápido.
Cuando definís tus propios niveles, tu marca usa esa escalera completa en lugar
de la default.

<Callout title="Cómo pensar los nombres">
  Un nombre descriptivo se entiende mejor que uno genérico: “Oro” comunica más
  que “Nivel 3”. Elegí una progresión clara y fácil de recordar.
</Callout>

## Un consejo para empezar [#un-consejo-para-empezar]

<Callout type="info">
  No hace falta lanzar con la escalera perfecta. Empezá con dos o tres niveles
  claros, con beneficios genuinamente deseables, y ajustá con el tiempo según
  cómo se mueven tus clientes reales entre escalones.
</Callout>

<Callout title="¿Listo para crearlos?">
  Seguí la guía paso a paso: [Crear un nivel](https://docs.loybox.com.ar/niveles/crear-un-nivel).
</Callout>


# Crear un nivel (https://docs.loybox.com.ar/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.

<img alt="Modal Nuevo nivel en el panel de Loybox" src="__img0" />

## Paso a paso [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Niveles** [#entrá-a-niveles]

    En el menú lateral, dentro de **Fidelización**, tocá **Niveles**.
  </Step>

  <Step>
    ### Tocá **Nuevo nivel** [#tocá-nuevo-nivel]

    Se abre una ventana para configurar el nivel. Si todavía no tenés ninguno,
    empezá por el nivel base (por ejemplo, *Bronce*): es el punto de partida de
    todos los clientes.
  </Step>

  <Step>
    ### Poné el **Nombre** [#poné-el-nombre]

    El nombre que ve el cliente, por ejemplo *Oro*.
  </Step>

  <Step>
    ### Elegí un **Ícono** [#elegí-un-ícono]

    Buscá y seleccioná un ícono para el nivel. Es el distintivo visual que se
    muestra en la app.
  </Step>

  <Step>
    ### Elegí la **Métrica** [#elegí-la-métrica]

    Cómo se mide el avance hacia el nivel:

    * **Puntos**: por puntos acumulados.
    * **Monto ($)**: por monto gastado.
  </Step>

  <Step>
    ### Definí el **Umbral** [#definí-el-umbral]

    Cuánto necesita acumular el cliente para alcanzar el nivel (en puntos o en
    dinero, según la métrica).

    <Callout type="info">
      El nivel base no tiene umbral ni expiración: es el escalón de entrada, así
      que estos campos no aparecen al configurarlo.
    </Callout>
  </Step>

  <Step>
    ### Ajustá la &#x2A;*Expiración (días)*&#x2A; &#x2A;(opcional)* [#ajustá-la-expiración-días-opcional]

    Si querés que el nivel se mantenga con actividad, indicá en cuántos días vence.
    Dejalo vacío para que el nivel no venza.
  </Step>

  <Step>
    ### Cargá los **Premios** del nivel [#cargá-los-premios-del-nivel]

    Podés combinar los que quieras:

    * **Multiplicador (%)**: el porcentaje extra de puntos por compra (0 = sin
      bonus, 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**: premios existentes que se entregan al llegar al
      nivel.
  </Step>

  <Step>
    ### Tocá **Crear nivel** [#tocá-crear-nivel]

    El nivel se guarda y aparece en tu escalera de niveles.
  </Step>
</Steps>

## Ordenar los niveles [#ordenar-los-niveles]

En la lista, arrastrá 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 [#tres-cosas-que-conviene-saber]

<Callout title="La métrica es común a todos los niveles">
  Puntos o monto es una elección de toda la escalera, no de un nivel suelto. Si
  cambiás la métrica, se aplica a todos los niveles y los umbrales se
  reinician a cero: revisalos antes de guardar.
</Callout>

<Callout type="info" title="Los premios exclusivos se agregan después">
  Los premios exclusivos del nivel (al alcanzarlo o por evento, como
  cumpleaños) se cargan una vez que el nivel está guardado. Creá el nivel
  primero y después editalo para sumarlos.
</Callout>

<Callout title="Empezá simple">
  No hace falta lanzar con la escalera completa. Con el nivel base y dos o tres
  niveles por encima alcanza para arrancar; siempre podés sumar más y reordenar.
</Callout>


# Fundamentos (https://docs.loybox.com.ar/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
vos, y el premio recién se paga cuando esa recomendación se convierte en una
compra real.

## Cómo funciona [#cómo-funciona]

<Steps>
  <Step>
    ### Activás el programa [#activás-el-programa]

    Definís cuántos puntos se otorgan por cada referido efectivo.
  </Step>

  <Step>
    ### Cada cliente comparte su enlace [#cada-cliente-comparte-su-enlace]

    Desde su app, cada cliente tiene un enlace de invitación propio para
    compartir con quien quiera.
  </Step>

  <Step>
    ### Un nuevo cliente se suma [#un-nuevo-cliente-se-suma]

    La persona invitada abre el enlace y se suma a tu club.
  </Step>

  <Step>
    ### Ambos ganan puntos [#ambos-ganan-puntos]

    Cuando ese invitado hace su primera compra, los puntos se acreditan a los
    dos: a quien invitó y al invitado.
  </Step>
</Steps>

## Los puntos del referido [#los-puntos-del-referido]

Configurás 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 el premio siempre acompaña a una venta real.

## Las reglas [#las-reglas]

Para que un referido sume, Loybox valida algunas condiciones:

<Cards>
  <Card title="Tiene que ser un cliente nuevo" description="El invitado no puede estar ya suscrito a tu club. Los referidos suman clientes nuevos, no reactivan existentes." />

  <Card title="No vale autoinvitarse" description="Nadie puede usar su propio enlace de invitación." />

  <Card title="Un enlace por persona" description="Cada invitado puede usar un enlace de referido una sola vez." />

  <Card title="Recién en la primera compra" description="El registro no alcanza: los puntos se otorgan cuando el invitado efectivamente compra por primera vez." />
</Cards>


# Activar los referidos (https://docs.loybox.com.ar/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.

<img alt="Configuración del premio por invitar amigos en el panel de Loybox" src="__img0" />

## Paso a paso [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Premios** [#entrá-a-premios]

    En el menú lateral, dentro de **Fidelización**, tocá **Premios**.
  </Step>

  <Step>
    ### Bajá a **Premios especiales** [#bajá-a-premios-especiales]

    Debajo del catálogo vas a encontrar la sección **Premios especiales**, con las
    recompensas automáticas.
  </Step>

  <Step>
    ### En **Invitar amigos**, tocá **Configurar** [#en-invitar-amigos-tocá-configurar]

    Es el recuadro que dice &#x2A;“Cuando un amigo invitado compra por primera vez,
    ambos ganan puntos.”* Si todavía no lo configuraste, aparece como
    **Sin configurar**.
  </Step>

  <Step>
    ### Definí los **Puntos para cada uno** [#definí-los-puntos-para-cada-uno]

    Ingresá cuántos puntos gana cada referido. Ese mismo valor se otorga a quien
    invita y al invitado, cuando el invitado hace su primera compra.
  </Step>

  <Step>
    ### Tocá **Guardar** [#tocá-guardar]

    Listo: el programa queda activo y tus clientes empiezan a ganar puntos por
    invitar.
  </Step>
</Steps>

## Editar o desactivar [#editar-o-desactivar]

<Cards>
  <Card title="Editar" description="Volvé a Invitar amigos y tocá Editar para cambiar los puntos cuando quieras." />

  <Card title="Quitar" description="Tocá Quitar para desactivar el programa. Tus clientes dejan de ganar puntos por invitar." />
</Cards>

<Callout type="info">
  El valor que cargás es el mismo para ambas partes: no se configuran por
  separado los puntos de quien invita y los del invitado.
</Callout>


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

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

## Los tipos de reseña [#los-tipos-de-reseña]

<Cards>
  <Card title="Reseñas del negocio (Google)" icon="Star" description="Después de la compra, invitás al cliente a dejar una reseña de tu negocio en Google. Necesitás conectar tu ficha de Google." />

  <Card title="Reseñas de productos nativas de Loybox" icon="MessageSquare" description="Por WhatsApp, el cliente responde con estrellas (1 a 5) y un comentario opcional. No necesitás un sistema de reseñas propio: Loybox las guarda." />

  <Card title="Reseñas de productos externas" icon="ExternalLink" description="Usás tu propio sistema de reseñas. Cargás un link por producto y Loybox se lo envía al cliente por WhatsApp." />
</Cards>

## Cómo funciona el pedido [#cómo-funciona-el-pedido]

<Steps>
  <Step>
    ### El cliente recibe su compra [#el-cliente-recibe-su-compra]

    El pedido de reseña se apoya en la entrega de una compra de tu tienda.
  </Step>

  <Step>
    ### Loybox espera la demora que definiste [#loybox-espera-la-demora-que-definiste]

    Configurás cuántas horas esperar desde la entrega (por ejemplo, 24 = un día
    después de recibir el pedido).
  </Step>

  <Step>
    ### Se envía la solicitud por WhatsApp [#se-envía-la-solicitud-por-whatsapp]

    El cliente recibe el mensaje para reseñar tu negocio y/o los productos que
    compró.
  </Step>

  <Step>
    ### El cliente responde [#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).
  </Step>
</Steps>

## La reseña nativa [#la-reseña-nativa]

Cuando usás 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 [#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:

<Cards>
  <Card title="Reseña de producto" description="No se le vuelve a pedir la reseña del mismo producto al mismo cliente antes de 90 días." />

  <Card title="Reseña de Google" description="Se pide una sola vez por cliente: si ya se la pediste, no se repite." />
</Cards>


# Configurar reseñas (https://docs.loybox.com.ar/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 hacés.

<Callout type="info">
  La sección **Reseñas** requiere tu tienda online conectada, porque los pedidos
  de reseña se disparan con la entrega de cada compra.
</Callout>

<img alt="Sección Reseñas en el panel de Loybox" src="__img0" />

## Reseñas del negocio (Google) [#reseñas-del-negocio-google]

<Steps>
  <Step>
    ### Entrá a **Reseñas** [#entrá-a-reseñas]

    En el menú lateral, tocá **Reseñas**.
  </Step>

  <Step>
    ### Activá **Pedir reseña en Google** [#activá-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.
  </Step>

  <Step>
    ### Conectá tu ficha de Google [#conectá-tu-ficha-de-google]

    Buscá y seleccioná tu negocio. Hasta que lo elijas, Loybox no puede enviar el
    pedido de reseña.
  </Step>

  <Step>
    ### Ajustá la &#x2A;*Demora del envío (horas)** [#ajustá-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).
  </Step>
</Steps>

## Reseñas de productos [#reseñas-de-productos]

<Steps>
  <Step>
    ### Activá **Pedir reseña de productos** [#activá-pedir-reseña-de-productos]

    Con esto, se le pide al cliente que reseñe los productos que compró.
  </Step>

  <Step>
    ### Elegí el **Tipo de reseña** [#elegí-el-tipo-de-reseña]

    <Cards>
      <Card title="Nativas de Loybox" description="Le llega un WhatsApp y responde con las estrellas (1 a 5) y un comentario opcional. No necesitás un sistema de reseñas propio." />

      <Card title="Externas (tu propio sistema)" description="Cargás un link de reseña por producto y Loybox se lo envía al cliente por WhatsApp." />
    </Cards>
  </Step>

  <Step>
    ### Ajustá la &#x2A;*Demora del envío (horas)** [#ajustá-la-demora-del-envío-horas-1]

    Igual que en Google: cuánto esperar desde la entrega para pedir la reseña.
  </Step>

  <Step>
    ### Si elegiste **Externas**, cargá los links [#si-elegiste-externas-cargá-los-links]

    En la sección **Links de reseña por producto**, buscá cada producto y pegá su
    link de reseña. Es lo que Loybox le va a mandar al cliente.
  </Step>
</Steps>

<Callout title="Se guarda solo">
  No hay un botón de guardar: cada cambio (interruptores, tipo de reseña, demora)
  se aplica al instante. Podés previsualizar cómo le llega el WhatsApp al cliente
  en **Así le llega al cliente**.
</Callout>


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

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

## Los tipos de recomendación [#los-tipos-de-recomendación]

<Cards>
  <Card title="Productos similares" description="Productos parecidos al que el cliente está viendo o agregó al carrito." />

  <Card title="Complementarios (cross-sell)" description="Productos que combinan con lo que el cliente compra o ya tiene en el carrito." />

  <Card title="Superiores (upsell)" description="Una opción mejor y algo más cara que el producto elegido, hasta el límite de precio que definas." />

  <Card title="Personalizadas" description="Sugerencias en base al historial de compras de cada cliente logueado." />
</Cards>

## Dónde aparecen [#dónde-aparecen]

Elegís en qué puntos de la tienda se muestran:

<Cards>
  <Card title="En el carrito" icon="ShoppingCart" description="Recomendaciones en base a lo que el cliente ya tiene agregado." />

  <Card title="En la ficha de producto" icon="Package" description="Al agregar un producto, un popup con productos similares." />

  <Card title="En el home" icon="House" description="Recomendaciones personalizadas para el cliente logueado." />

  <Card title="En el checkout" icon="CreditCard" description="Sugerencias sobre la pantalla de pago, antes de cerrar la compra." />
</Cards>

## Recomendaciones por WhatsApp [#recomendaciones-por-whatsapp]

Además de la tienda, las recomendaciones pueden llegar por WhatsApp en dos
momentos:

<Cards>
  <Card title="Post-compra" description="Después de una compra, le sugerimos al cliente productos que combinan con lo que compró (con la demora que definas, para no ser invasivos)." />

  <Card title="Reactivación de inactivos" description="A los clientes que dejaron de comprar les enviamos recomendaciones para volver a engancharlos." />
</Cards>

## Cómo se mide el impacto [#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í podés ver el
retorno real de la herramienta.

## Qué necesitás configurar [#qué-necesitás-configurar]

Muy poco: la IA hace el trabajo de elegir qué mostrar. Vos definís si está
activa, en qué lugares aparece y qué notificaciones enviar.


# Configurar recomendaciones (https://docs.loybox.com.ar/recomendaciones/configurar-recomendaciones)



La configuración está organizada en tres pestañas: **General**, **Ubicaciones**
y **Notificaciones**.

<Callout type="info">
  La sección **Recomendaciones** requiere tu tienda online conectada.
</Callout>

## General [#general]

<Steps>
  <Step>
    ### Entrá a **Recomendaciones** [#entrá-a-recomendaciones]

    En el menú lateral, tocá **Recomendaciones**.
  </Step>

  <Step>
    ### Activá **Recomendaciones activas** [#activá-recomendaciones-activas]

    Habilita el sistema de recomendaciones en toda la tienda.
  </Step>

  <Step>
    ### Ajustá **Upsell: % máximo más caro** [#ajustá-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.
  </Step>
</Steps>

## Ubicaciones [#ubicaciones]

En la pestaña **Ubicaciones** elegís en qué puntos de la tienda se muestran las
recomendaciones:

<Cards>
  <Card title="Recomendaciones en el carrito" description="En base a lo que el cliente ya tiene agregado." />

  <Card title="Productos similares (popup)" description="Al agregar un producto, salta un popup con similares." />

  <Card title="Recomendaciones personalizadas (popup)" description="Al cliente logueado, la primera vez que entra en el día, según sus compras anteriores." />

  <Card title="Recomendaciones en el checkout" description="Aparecen al momento de pagar." />
</Cards>

## Notificaciones [#notificaciones]

En la pestaña **Notificaciones** configurás los envíos por WhatsApp:

<Steps>
  <Step>
    ### Recomendación post-compra [#recomendación-post-compra]

    Activala para que, después de una compra, se le envíen al cliente productos que
    combinan con lo que compró. Definí la &#x2A;*Demora post-compra (horas)** para no
    ser invasivo.
  </Step>

  <Step>
    ### Reactivación de inactivos [#reactivación-de-inactivos]

    Activala para enviarles recomendaciones a los clientes que dejaron de comprar.
    Definí los **Días para considerar inactivo** a partir de los cuales aplica.
  </Step>

  <Step>
    ### Ventana de atribución (horas) [#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.
  </Step>
</Steps>

## Guardar [#guardar]

Cuando termines, tocá **Guardar configuración**. Los cambios quedan aplicados
en tu tienda.


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

<Callout type="info" title="Para tiendas online">
  Ambas herramientas requieren tu tienda online conectada.
</Callout>

## Dos herramientas [#dos-herramientas]

<Cards>
  <Card title="Recuperar carritos abandonados" icon="ShoppingCart" href="/carrito/recuperar-carritos" description="Si un cliente deja productos en el carrito sin comprar, Loybox le manda recordatorios por WhatsApp (y, si querés, un cupón)." />

  <Card title="Recompensas en el carrito" icon="Gift" href="/carrito/recompensas-en-carrito" description="Regalos que se desbloquean al superar un monto: un producto gratis o un descuento, con un mensaje que motiva a agregar más." />
</Cards>

## Cuándo usar cada una [#cuándo-usar-cada-una]

<Cards>
  <Card title="Recuperar" description="Para no perder ventas que estaban por cerrarse. El recordatorio le da al cliente el empujón (o el incentivo) que faltaba." />

  <Card title="Recompensar" description="Para aumentar el ticket promedio: “te falta poco para tu regalo” invita a sumar un producto más antes de pagar." />
</Cards>


# Recuperar carritos abandonados (https://docs.loybox.com.ar/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 [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Carrito** [#entrá-a-carrito]

    En el menú lateral, tocá **Carrito**. Arriba vas a ver **Carrito abandonado**.
  </Step>

  <Step>
    ### Activá los **Recordatorios** [#activá-los-recordatorios]

    Encendé **Recordatorios activos**. Con esto, si un cliente abandona su carrito,
    le llega un recordatorio por WhatsApp.
  </Step>

  <Step>
    ### Definí los tiempos de envío [#definí-los-tiempos-de-envío]

    En &#x2A;*Recordatorios (horas desde el abandono)** indicás cuántas horas después de
    abandonar el carrito se envía cada recordatorio. Podés poner varios: por
    ejemplo, `1, 24, 72` = a la hora, al día y a los 3 días.
  </Step>

  <Step>
    ### Sumá un cupón &#x2A;(opcional)* [#sumá-un-cupón-opcional]

    Si querés dar un incentivo extra, agregá un cupón de descuento
    (porcentaje sobre el total o monto fijo) y definí su validez en
    horas.
  </Step>

  <Step>
    ### Guardá [#guardá]

    Los cambios quedan aplicados y los recordatorios empiezan a enviarse.
  </Step>
</Steps>

<Callout type="info">
  Los recordatorios viajan por WhatsApp, así que necesitás WhatsApp Business
  conectado en Integraciones.
</Callout>

<Callout title="Cuántos recordatorios poner">
  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.
</Callout>


# Recompensas en el carrito (https://docs.loybox.com.ar/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 [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Carrito** [#entrá-a-carrito]

    En el menú lateral, tocá **Carrito**. Bajá hasta la sección de recompensas.
  </Step>

  <Step>
    ### Tocá **Nueva regla** [#tocá-nueva-regla]

    Se abre una ventana para configurar la regla.
  </Step>

  <Step>
    ### Poné un **Nombre** [#poné-un-nombre]

    Para identificarla en tu panel. Por ejemplo, *Regalo a partir de $20.000*.
  </Step>

  <Step>
    ### Definí el **Monto mínimo del carrito** [#definí-el-monto-mínimo-del-carrito]

    El subtotal a partir del cual se desbloquea la recompensa.
  </Step>

  <Step>
    ### Elegí el **Tipo de recompensa** [#elegí-el-tipo-de-recompensa]

    <Cards>
      <Card title="Producto gratis" description="Un producto de tu catálogo, sin cargo." />

      <Card title="Porcentaje" description="Un % de descuento sobre la compra." />

      <Card title="Absoluto" description="Un monto fijo de descuento." />
    </Cards>

    Según el tipo, completás el producto o el valor del descuento.
  </Step>

  <Step>
    ### Escribí el **Mensaje al cliente** [#escribí-el-mensaje-al-cliente]

    Es lo que ve en la tienda cuando desbloquea la recompensa (por ejemplo,
    “¡Ya podés acceder a tu regalo!”). Opcionalmente podés definir el texto del
    descuento en el checkout.
  </Step>

  <Step>
    ### Dejala **Activa** y tocá **Crear regla** [#dejala-activa-y-tocá-crear-regla]

    Solo las reglas activas se aplican en la tienda. Podés tener varias.
  </Step>
</Steps>

<Callout title="Cómo elegir el monto">
  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.
</Callout>


# Fundamentos (https://docs.loybox.com.ar/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 vos: no hay que definir reglas a
mano.

<Callout type="info" title="Para tiendas online">
  La segmentación se calcula sobre los pedidos de tu tienda online conectada.
</Callout>

## Cómo se arma: el modelo RFM [#cómo-se-arma-el-modelo-rfm]

Cada cliente se clasifica según tres señales de su comportamiento de compra:

<Cards>
  <Card title="Recencia" icon="Clock" description="Hace cuánto compró por última vez. Un cliente que compró ayer no es lo mismo que uno que no aparece hace meses." />

  <Card title="Frecuencia" icon="Repeat" description="Cuántas veces compró. Mide qué tan habitual es." />

  <Card title="Monto" icon="Banknote" description="Cuánto gastó en total. Mide el valor que aporta." />
</Cards>

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]

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 [#además-la-salud-de-tu-negocio]

El panel también resume el estado general de tu base con métricas clave:

<Cards>
  <Card title="Clientes activos" description="Cuántos clientes componen tu base en la ventana analizada." />

  <Card title="Órdenes" description="El total de pedidos del período." />

  <Card title="Ticket promedio" description="Lo que gasta en promedio cada compra." />

  <Card title="Repeat rate" description="Qué proporción de tus clientes vuelve a comprar." />

  <Card title="Top 20%" description="Cuánto de tus ventas concentra el 20% de tus mejores clientes (regla de Pareto)." />
</Cards>


# Usar tus segmentos (https://docs.loybox.com.ar/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 [#paso-a-paso]

<Steps>
  <Step>
    ### Entrá a **Segmentación** [#entrá-a-segmentación]

    En el menú lateral, tocá **Segmentación**.
  </Step>

  <Step>
    ### Revisá la salud de tu negocio [#revisá-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%).
  </Step>

  <Step>
    ### Explorá cada segmento [#explorá-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.
  </Step>

  <Step>
    ### Mirá los clientes de un segmento [#mirá-los-clientes-de-un-segmento]

    Abrí un segmento para ver la lista de clientes que lo componen. Podés ordenarla
    por mayor o menor monto gastado, más o menos compras y por fecha de
    compra (más antigua o más reciente).
  </Step>

  <Step>
    ### Accioná con una campaña [#accioná-con-una-campaña]

    Desde un segmento podés lanzar una campaña por WhatsApp dirigida a ese
    grupo, para hablarle distinto a cada tipo de cliente.
  </Step>
</Steps>

<Callout type="info" title="Para campañas por WhatsApp">
  Para crear campañas por WhatsApp necesitás tener WhatsApp Business conectado
  en Integraciones.
</Callout>

## Cómo pensar cada segmento [#cómo-pensar-cada-segmento]

La gracia está en tratar a cada grupo según lo que necesita:

<Cards>
  <Card title="Champions y Leales" description="Reconocelos y premiá su fidelidad para que sigan eligiéndote." />

  <Card title="En riesgo y Necesitan atención" description="Reactivalos antes de que se vayan, con un incentivo para volver." />

  <Card title="Hibernando y Perdidos" description="Intentá recuperarlos con una propuesta fuerte, sabiendo que son los más difíciles." />
</Cards>

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


# Fundamentos (https://docs.loybox.com.ar/campanas)



Las campañas te permiten enviar un mensaje a un grupo de clientes por
WhatsApp o email. Se apoyan en la [segmentación](https://docs.loybox.com.ar/segmentacion): en vez
de escribirle a toda tu base, le hablás distinto a cada grupo según su
comportamiento.

<Callout type="info" title="Se crean desde un segmento">
  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.
</Callout>

## Cómo funciona [#cómo-funciona]

<Steps>
  <Step>
    ### Elegís la audiencia [#elegís-la-audiencia]

    Un segmento (por ejemplo, *En riesgo*) o un cliente individual.
  </Step>

  <Step>
    ### Elegís el canal [#elegís-el-canal]

    WhatsApp o email, según cómo quieras llegar.
  </Step>

  <Step>
    ### Escribís el mensaje [#escribís-el-mensaje]

    Con variables de personalización como `{{first_name}}` para que cada cliente lo
    reciba con su nombre.
  </Step>

  <Step>
    ### Programás o enviás [#programás-o-enviás]

    Elegís fecha y hora, o lo enviás en el momento.
  </Step>

  <Step>
    ### Seguís los resultados [#seguís-los-resultados]

    Cada campaña muestra su estado y sus métricas.
  </Step>
</Steps>

## Los estados de una campaña [#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 [#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.

<Callout type="info">
  Para enviar por WhatsApp necesitás WhatsApp Business conectado en
  Integraciones.
</Callout>


# Crear una campaña (https://docs.loybox.com.ar/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 [#paso-a-paso]

<Steps>
  <Step>
    ### Abrí un segmento en **Segmentación** [#abrí-un-segmento-en-segmentación]

    Entrá a **Segmentación** y abrí el segmento al que le querés hablar (por
    ejemplo, *En riesgo* o *Champions*).
  </Step>

  <Step>
    ### Creá la campaña para ese grupo [#creá-la-campaña-para-ese-grupo]

    Desde el detalle del segmento, iniciá una campaña. La audiencia queda
    definida por ese segmento.
  </Step>

  <Step>
    ### Elegí el canal [#elegí-el-canal]

    WhatsApp o email. Para usar WhatsApp necesitás tener
    [WhatsApp Business conectado](https://docs.loybox.com.ar/integraciones/whatsapp) en Integraciones.
  </Step>

  <Step>
    ### Escribí el **Mensaje** [#escribí-el-mensaje]

    Redactá el texto. Usá variables como `{{first_name}}` para personalizarlo con
    el nombre de cada cliente.
  </Step>

  <Step>
    ### Previsualizá [#previsualizá]

    Revisá cómo va a llegar el mensaje antes de enviarlo.
  </Step>

  <Step>
    ### Programá el envío [#programá-el-envío]

    En **Fecha y hora**, elegí cuándo sale (tiene que ser a futuro) y tocá
    **Programar envío**. También podés guardarla como borrador.
  </Step>

  <Step>
    ### Seguí los resultados [#seguí-los-resultados]

    En **Campañas** vas a ver todas tus campañas con su estado (Borrador,
    Programada, Enviando, Enviada…) y sus métricas.
  </Step>
</Steps>

<Callout title="Un mensaje para cada grupo">
  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.
</Callout>


# Integraciones (https://docs.loybox.com.ar/integraciones)



Loybox se conecta con las herramientas que ya usás para que tu programa de
fidelidad funcione sin fricción: tu tienda online, WhatsApp y tu email
marketing. Todas las integraciones se gestionan desde la sección
**Integraciones** del panel.

## Disponibles [#disponibles]

<Cards>
  <Card title="Tiendanube" icon="ShoppingCart" href="/integraciones/tiendanube" description="Conectá tu tienda online: pedidos, productos y clientes se sincronizan con Loybox." />

  <Card title="WhatsApp Business" icon="MessageCircle" href="/integraciones/whatsapp" description="Enviá notificaciones y mensajes de fidelización por WhatsApp." />

  <Card title="Perfit" icon="Mail" href="/integraciones/perfit" description="Sincronizá tus contactos con Perfit para tus campañas de email." />
</Cards>

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


# Tiendanube (https://docs.loybox.com.ar/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 [#qué-habilita]

<Cards>
  <Card title="Puntos automáticos" icon="Coins" description="Cada compra en tu tienda suma puntos al cliente, sin cargarla a mano." />

  <Card title="Canje en el checkout" icon="BadgeCheck" description="Tus clientes pueden canjear premios directamente al momento de pagar." />

  <Card title="Reseñas y recomendaciones" icon="Star" description="Ambas herramientas se apoyan en los pedidos y el catálogo de tu tienda." />

  <Card title="Catálogo sincronizado" icon="RefreshCw" description="Tus productos quedan disponibles en Loybox para premios, recomendaciones y reseñas." />
</Cards>

## Cómo conectarla [#cómo-conectarla]

<Steps>
  <Step>
    ### Entrá a **Integraciones** [#entrá-a-integraciones]

    En el menú lateral del panel, abrí **Integraciones**.
  </Step>

  <Step>
    ### En **Tiendanube**, tocá **Conectar** [#en-tiendanube-tocá-conectar]

    Te redirige a Tiendanube para autorizar la conexión con tu tienda.
  </Step>

  <Step>
    ### Autorizá el acceso [#autorizá-el-acceso]

    Confirmá el permiso en Tiendanube. Al volver, la tienda queda conectada y
    empieza la sincronización.
  </Step>
</Steps>

<Callout type="info">
  Conectar Tiendanube es el primer paso para usar puntos automáticos, canje en el
  checkout, reseñas y recomendaciones.
</Callout>


# WhatsApp Business (https://docs.loybox.com.ar/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 [#qué-habilita]

<Cards>
  <Card title="Notificaciones" icon="Bell" description="Avisos automáticos cuando el cliente suma puntos o tiene premios para canjear." />

  <Card title="Reseñas por WhatsApp" icon="Star" description="El pedido de reseña post-compra le llega al cliente por WhatsApp." />

  <Card title="Recomendaciones" icon="Sparkles" description="Los mensajes de recomendación post-compra y de reactivación viajan por WhatsApp." />
</Cards>

## Cómo conectarla [#cómo-conectarla]

<Steps>
  <Step>
    ### Entrá a **Integraciones** [#entrá-a-integraciones]

    En el panel, abrí la sección **Integraciones**.
  </Step>

  <Step>
    ### En **WhatsApp Business**, tocá **Conectar** [#en-whatsapp-business-tocá-conectar]

    Se abre el flujo de Meta para vincular tu cuenta de WhatsApp Business.
  </Step>

  <Step>
    ### Completá la conexión con Meta [#completá-la-conexión-con-meta]

    Seguí los pasos de Meta para autorizar. Al terminar, WhatsApp Business queda
    conectado.
  </Step>
</Steps>

<Callout type="info">
  La conexión se hace a través de Meta (Facebook), el proveedor oficial de la API
  de WhatsApp Business.
</Callout>


# Perfit (https://docs.loybox.com.ar/integraciones/perfit)



La integración con Perfit sincroniza los contactos de tu club con tu cuenta
de Perfit, para que puedas sumar el email marketing a tu estrategia de
fidelización.

## Qué habilita [#qué-habilita]

<Cards>
  <Card title="Contactos sincronizados" icon="Users" description="Los clientes de tu club se sincronizan como contactos en Perfit." />

  <Card title="Campañas de email" icon="Mail" description="Usás la base de tu programa de fidelidad para tus campañas de email en Perfit." />
</Cards>

## Cómo conectarla [#cómo-conectarla]

<Steps>
  <Step>
    ### Entrá a **Integraciones** [#entrá-a-integraciones]

    En el panel, abrí la sección **Integraciones**.
  </Step>

  <Step>
    ### En **Perfit**, tocá **Conectar** [#en-perfit-tocá-conectar]

    Vinculá tu cuenta de Perfit siguiendo los pasos en pantalla.
  </Step>

  <Step>
    ### Listo [#listo]

    Al conectarse, Loybox empieza a sincronizar tus contactos con Perfit.
  </Step>
</Steps>


# Referencia técnica (https://docs.loybox.com.ar/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 necesitás el detalle completo.

## Entidades [#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 premios 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 local o en la tienda online. Es lo que dispara el cálculo de puntos.                                            |
| **Punto**   | La unidad de fidelidad. Se gana con consumos y otras acciones, y se gasta canjeando premios.                                                  |
| **Premio**  | La recompensa que el cliente obtiene a cambio de puntos.                                                                                      |

## Cálculo 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 [#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 [#orden-de-los-multiplicadores]

El orden importa, porque los ajustes se aplican en cascada:

<Steps>
  <Step>
    ### Punto base [#punto-base]

    Según la regla de dinero por punto, o la conversión por moneda.
  </Step>

  <Step>
    ### Puntos dobles [#puntos-dobles]

    Si la promoción está vigente, duplica el resultado anterior.
  </Step>

  <Step>
    ### Bonus porcentual del nivel [#bonus-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)).
  </Step>
</Steps>

### Otras fuentes de puntos [#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 [#saldo]

<Callout title="El saldo se calcula, no se almacena">
  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.
</Callout>

Los puntos vencidos no se borran del historial: dejan de sumar cuando se
calcula el saldo disponible.

## Vencimiento de puntos [#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.   |

<Callout type="info" title="La condición de los días">
  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.
</Callout>

## Niveles [#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.

## Premios [#premios]

Un premio se define por tipo y valor, costo en puntos, límite de canjes,
vencimiento e imagen opcional ([Premios](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 los premios activos aparecen disponibles para el cliente. Un límite de
canjes en cero significa ilimitado.

## Canje [#canje]

El flujo valida saldo antes de descontar ([Canje](https://docs.loybox.com.ar/puntos-y-premios/canje)):

<Steps>
  <Step>
    ### Validación de saldo [#validación-de-saldo]

    El canje procede sólo si el cliente cubre el costo en puntos del premio.
  </Step>

  <Step>
    ### Descuento y emisión [#descuento-y-emisión]

    Se registra el canje, el costo se resta del saldo y el premio queda a nombre
    del cliente con un código de validación corto y único.
  </Step>

  <Step>
    ### Validación del código [#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.
  </Step>
</Steps>

Un premio ya canjeado conserva la fecha de vigencia del premio original.

## Segmentación [#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.

<Callout type="info">
  La segmentación se calcula sobre los pedidos de la tienda online conectada.
</Callout>

## Canales e integraciones [#canales-e-integraciones]

Una misma marca puede operar el club en locales físicos (app PWA con su
marca) y en su tienda online (integrada al checkout). Las reglas de puntos
y el catálogo de premios 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 email).

Las reseñas y las recomendaciones dependen de tener la tienda online conectada.


# Sobre la API (https://docs.loybox.com.ar/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 premios, 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 [#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 [#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). Exportala 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 [#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, pasale esa URL.

## Las dos formas de integrarse [#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.

<Cards>
  <Card title="Desde tu servidor" icon="Building2" description="Tu backend opera sobre todos los clientes del comercio. Se autentica con la API key. Es la integración clásica: caja, ERP, e-commerce propio." href="/api-reference/credenciales" />

  <Card title="Desde tu web" icon="Smartphone" description="El usuario final inicia sesión con un código que le llega por email y consulta sus propios puntos. Loybox como motor de fidelidad del frontend." href="/api-reference/credenciales" />
</Cards>

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) | —                 | Login del usuario final por email      |
| [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 login            |

<Callout type="warn" title="La API key nunca va en el frontend">
  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 browser es el token de acceso
  del usuario final, que sólo ve lo suyo.
</Callout>

## Cómo se ven las respuestas [#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. Podés leerlos
sin chequear si existen, pero sí hay que chequear si son `null`.

## Paginación [#paginación]

Hay dos esquemas, y cada uno vive en un solo endpoint:

### Límite y desplazamiento [#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 [#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 [#por-dónde-empezar]

<Cards>
  <Card title="Primeros pasos" icon="Rocket" description="La integración completa de punta a punta: de la primera compra que suma puntos hasta el canje." href="/api-reference/primeros-pasos" />

  <Card title="Credenciales" icon="BadgeCheck" description="Cómo se autentica cada una de las dos integraciones y qué headers van en cada llamada." href="/api-reference/credenciales" />

  <Card title="Objetos" icon="Boxes" description="Los objetos que devuelve la API y la diferencia entre un beneficio y un beneficio canjeable." href="/api-reference/objetos" />

  <Card title="Errores" icon="TriangleAlert" description="Los códigos de estado que puede devolver la API y qué hacer con cada uno." href="/api-reference/errores" />

  <Card title="Referencia técnica" icon="Braces" description="Cómo funciona Loybox por dentro: fórmulas de puntos, vencimientos y reglas de niveles." href="/referencia-tecnica" />
</Cards>


# Primeros pasos (https://docs.loybox.com.ar/api-reference/primeros-pasos)



Esta página es la integración completa de punta a punta. Si venís a implementar
y querés 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 [#antes-de-empezar]

Necesitás dos cosas, y las dos te las damos nosotros: escribinos a
[hola@loybox.com.ar](mailto:hola@loybox.com.ar).

<Fields>
  <Field name="LOYBOX_API_KEY" type="secreta" required="true">
    La API key del comercio. Va sólo en tu servidor.
  </Field>

  <Field name="commerce_id" type="pública" required="true">
    El id de tu comercio. Es el que viaja en el header `X-Commerce-Id` y puede
    ir en el frontend.
  </Field>
</Fields>

Los ejemplos de acá 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 [#camino-1-sumar-puntos-desde-tu-servidor]

Es la integración mínima de un programa de fidelidad: una sola llamada, en el
lugar donde tu sistema confirma una venta.

<Steps>
  <Step>
    ### Registrá la compra [#registrá-la-compra]

    En el checkout online ya tenés el email, así que
    [por email](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 una caja física, 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`.

    <Callout type="warn" title="El monto va en entero">
      `amount` son unidades enteras de la moneda del comercio. Una compra de
      `$1.750,50` se manda como `1750`.
    </Callout>

    Cuántos puntos suma no lo decide tu llamada: lo decide la configuración del
    comercio. Mandás el monto y Loybox aplica la regla de dinero por punto, los
    puntos dobles si están vigentes y el bonus del nivel, en ese orden
    ([la fórmula](https://docs.loybox.com.ar/referencia-tecnica#cálculo-de-puntos)).
  </Step>

  <Step>
    ### Mostrale el saldo [#mostrale-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 tenés un programa funcionando: las compras suman y el cliente tiene
    un saldo.
  </Step>

  <Step>
    ### Consultá el código que trae el cliente [#consultá-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. Usá
    [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 aplicás 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` acá significa que el código ya se usó: no apliques nada.
  </Step>

  <Step>
    ### Canjealo cuando la venta se cerró [#canjealo-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
      }'
    ```

    <Callout type="warn" title="El orden importa">
      Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeás
      antes de cerrar la venta y la venta se cae, el cliente perdió el premio y no hay
      forma de devolvérselo por API.
    </Callout>
  </Step>
</Steps>

## Camino 2: el club en tu frontend [#camino-2-el-club-en-tu-frontend]

Acá Loybox funciona como motor de fidelidad debajo de tu producto: el usuario
inicia sesión con un código que le llega por email y desde ahí ve sus puntos,
compra beneficios y muestra sus códigos. Todo esto puede correr en el browser.

<Callout type="warn" title="La API key no entra en este camino">
  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.
</Callout>

<Steps>
  <Step>
    ### Pedile el código [#pedile-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 email no tiene cuenta. En la UI mostrás
    siempre el mismo mensaje ("te mandamos un código a tu email"), porque no podés
    saber si la cuenta existía.
  </Step>

  <Step>
    ### Verificalo y guardá la sesión [#verificalo-y-guardá-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`. Guardá 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 email no tenía cuenta, se crea, y en ambos casos el usuario
    queda adherido a tu programa.
  </Step>

  <Step>
    ### Pintá la pantalla con una sola llamada [#pintá-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, mostrá el llamado a adherirse
    ```

    Un `401` acá quiere decir que el `access` venció:
    [renovalo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintentá la llamada.
  </Step>

  <Step>
    ### Mostrá el catálogo y comprá [#mostrá-el-catálogo-y-comprá]

    [El catálogo](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) viene sin filtrar
    por saldo: comparás el `cost` de cada beneficio con los `points` del usuario y
    decidís 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"
      }'
    ```

    <Callout title="Comprar y canjear no son lo mismo">
      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)).
    </Callout>
  </Step>

  <Step>
    ### Mostrale el código [#mostrale-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 local es lo que muestra en el mostrador.

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

## El circuito completo [#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 [#antes-de-salir-a-producción]

* La **API key vive sólo en tu servidor**. Si se filtró, escribinos y la
  rotamos.
* **Nunca reintentes un `400`** a ciegas: es el beneficio ya usado, el vencido o
  los puntos que no alcanzan. Leé el `message` y cortá.
* **Comprar un beneficio lleva `Idempotency-Key`**. Es lo que evita cobrar los
  puntos dos veces cuando se corta la red.
* Un &#x2A;*`401`** en Mi cuenta es la señal de renovar el token, no de sacar al
  usuario de la sesión.
* El &#x2A;*`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"`. Chequeá el `mode` antes de mostrar el aviso.

## Si estás implementando con un agente [#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/api-reference/credenciales)



La API tiene **dos credenciales distintas**, y no son intercambiables. Cuál usás
depende de dónde corre tu código y de qué datos necesita ver.

## API key del comercio [#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.

<Callout type="warn" title="Es secreta">
  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ó, escribinos
  a [hola@loybox.com.ar](mailto:hola@loybox.com.ar) para rotarla.
</Callout>

## Token del usuario final [#token-del-usuario-final]

Pensada para conectar Loybox directo al frontend y usarlo como motor de
fidelidad: el usuario inicia sesión con un código que le llega por email 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 browser**: sólo ve los datos de ese usuario en tu
comercio.

## El header X-Commerce-Id [#el-header-x-commerce-id]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

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 login [#el-flujo-de-login]

<Steps>
  <Step>
    ### Pedir el código [#pedir-el-código]

    [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
    email del usuario. Le llega un código de 6 dígitos.
  </Step>

  <Step>
    ### Verificarlo [#verificarlo]

    [`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) con
    el email y el código. Devuelve un token de acceso (`access`) y uno de refresco
    (`refresh`). Si el email no tenía cuenta en Loybox se crea, y en ambos casos el
    usuario queda adherido al programa de tu comercio.
  </Step>

  <Step>
    ### Usar la sesión [#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}`.
  </Step>

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

El código vence a los **10 minutos** y admite **5 intentos**. Pedir un código
nuevo invalida el anterior.

## Resumen [#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 browser                          |
| **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/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 acá en lugar de
repetir las listas.

## Los tres códigos [#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)         |

<Callout title="Beneficio y beneficio canjeable no son lo mismo">
  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 local, o pega en el checkout de la tienda online.
</Callout>

## Cliente [#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).

<Fields>
  <Field name="code" type="integer" required="true">
    El código del cliente.
  </Field>

  <Field name="username" type="string" required="true">
    Nombre del cliente.
  </Field>

  <Field name="email" type="string" required="true">
    Email del cliente.
  </Field>

  <Field name="points" type="integer | null">
    Puntos que tiene en el comercio.
  </Field>
</Fields>

## Beneficio [#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).

<Fields>
  <Field name="id" type="string" required="true">
    El `benefit_id`.
  </Field>

  <Field name="type" type="string" required="true">
    Qué clase de premio es: `percentage_discount`, `absolute_discount` o
    `free_product`.
  </Field>

  <Field name="description" type="string" required="true">
    Descripción del beneficio.
  </Field>

  <Field name="cost" type="number" required="true">
    Cuántos puntos cuesta comprarlo.
  </Field>

  <Field name="expiration" type="date-time | null" required="true">
    Hasta cuándo está vigente. `null` si no vence.
  </Field>

  <Field name="benefit_type" type="string">
    `normal` para los del catálogo; `welcome`, `birthday`, `monthly_top` o
    `level` para las recompensas especiales. Por defecto, `normal`.
  </Field>

  <Field name="color" type="string | null">
    Color de marca del comercio, en hexadecimal.
  </Field>

  <Field name="buy_limit" type="integer | null">
    Cantidad total de canjes permitidos para este beneficio. `0` significa sin
    límite.
  </Field>

  <Field name="prize" type="Premio | null">
    El detalle del premio. Ver [Premio](#premio).
  </Field>

  <Field name="tiendanube_coupon" type="Cupón de Tiendanube | null">
    El cupón, si el beneficio se aplica en una tienda de Tiendanube. Ver
    [Cupón de Tiendanube](#cupón-de-tiendanube).
  </Field>
</Fields>

### Beneficio (v2) [#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:

<Fields>
  <Field name="title" type="string" required="true">
    Título del beneficio. En la v1 sólo estaba dentro de `prize`.
  </Field>

  <Field name="value" type="number | null">
    El valor del descuento: el porcentaje si es `percentage_discount`, el monto
    si es `absolute_discount`.
  </Field>

  <Field name="product" type="Producto | null">
    El producto, si es `free_product`. Ver [Producto](#producto).
  </Field>
</Fields>

El resto de los campos son los mismos que en [Beneficio](#beneficio).

## Beneficio canjeable [#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).

<Fields>
  <Field name="client_benefit_code" type="integer" required="true">
    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.
  </Field>

  <Field name="issue_date" type="date-time" required="true">
    Cuándo lo compró.
  </Field>

  <Field name="due_date" type="date-time | null">
    Hasta cuándo puede canjearlo. `null` si no vence.
  </Field>

  <Field name="used" type="boolean">
    Si ya fue canjeado. Por defecto, `false`.
  </Field>

  <Field name="benefit" type="Beneficio" required="true">
    El beneficio comprado. Ver [Beneficio](#beneficio).
  </Field>
</Fields>

## Premio [#premio]

El detalle de lo que gana el cliente. Va dentro de `prize`.

<Fields>
  <Field name="type" type="string" required="true">
    `percentage_discount`, `absolute_discount` o `free_product`.
  </Field>

  <Field name="title" type="string | null">
    Título del premio.
  </Field>

  <Field name="description" type="string | null">
    Descripción del premio.
  </Field>

  <Field name="value" type="number | null">
    El porcentaje o el monto del descuento, según el `type`.
  </Field>

  <Field name="product" type="Producto | null">
    El producto de regalo. Ver [Producto](#producto).
  </Field>

  <Field name="expiration" type="date-time | null">
    Vencimiento del premio.
  </Field>

  <Field name="image" type="string | null">
    URL de la imagen del premio.
  </Field>
</Fields>

## Producto [#producto]

<Fields>
  <Field name="id" type="integer | string | null">
    Id del producto en Loybox.
  </Field>

  <Field name="name" type="string | null">
    Nombre del producto.
  </Field>

  <Field name="external_id" type="string | null">
    Id del producto en el sistema del comercio.
  </Field>
</Fields>

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

<Fields>
  <Field name="id" type="integer" required="true">
    El `commerce_id`, el mismo que va en el header `X-Commerce-Id`.
  </Field>

  <Field name="name" type="string" required="true">
    Nombre del comercio.
  </Field>

  <Field name="logo" type="string | null">
    URL del logo.
  </Field>

  <Field name="color" type="string | null">
    Color de marca en hexadecimal, para la UI del programa.
  </Field>

  <Field name="category_name" type="string | null">
    Rubro del comercio, por ejemplo `Tienda de comics`.
  </Field>

  <Field name="currency" type="string | null">
    Moneda del comercio.
  </Field>
</Fields>

## Mi cuenta [#mi-cuenta]

La respuesta de [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).

<Fields>
  <Field name="username" type="string | null">
    Nombre del usuario.
  </Field>

  <Field name="email" type="string | null">
    Email del usuario.
  </Field>

  <Field name="phone" type="string | null">
    Teléfono del usuario.
  </Field>

  <Field name="points" type="integer">
    Puntos del usuario en este comercio. Por defecto, `0`.
  </Field>

  <Field name="subscribed" type="boolean">
    Si el usuario está adherido al programa de este comercio. Por defecto,
    `false`.
  </Field>

  <Field name="commerce" type="Comercio | null">
    Datos del comercio, para pintar la marca del programa. Ver
    [Comercio](#comercio).
  </Field>

  <Field name="points_expiration" type="Vencimiento de puntos | null">
    Puntos que están por vencer. Ver
    [Vencimiento de puntos](#vencimiento-de-puntos).
  </Field>
</Fields>

## Vencimiento de puntos [#vencimiento-de-puntos]

<Fields>
  <Field name="points" type="integer">
    Puntos que están por vencer. Por defecto, `0`.
  </Field>

  <Field name="expiration_date" type="date-time | null">
    Cuándo vencen.
  </Field>

  <Field name="days_left" type="integer | null">
    Días que faltan.
  </Field>

  <Field name="months_left" type="integer | null">
    Meses que faltan.
  </Field>

  <Field name="mode" type="string | null">
    Cómo vencen los puntos en este comercio: `none`, `rolling` o `accumulated`.
    `none` significa que no vencen.
  </Field>
</Fields>

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

## Nivel [#nivel]

La respuesta de [`GET /v1/me/level`](https://docs.loybox.com.ar/api-reference/mi-cuenta/nivel).

<Fields>
  <Field name="name" type="string | null">
    Nombre del nivel.
  </Field>

  <Field name="rank" type="integer | null">
    Posición del nivel en la escalera.
  </Field>

  <Field name="points_multiplier" type="number | null">
    Multiplicador de puntos que da el nivel.
  </Field>

  <Field name="icon_url" type="string | null">
    URL del icono del nivel.
  </Field>

  <Field name="reached_at" type="date-time | null">
    Cuándo alcanzó el nivel.
  </Field>

  <Field name="expiration_date" type="date-time | null">
    Cuándo vence el nivel.
  </Field>

  <Field name="is_expired" type="boolean | null">
    Si el nivel ya venció.
  </Field>

  <Field name="next_level" type="Próximo nivel | null">
    El nivel siguiente y qué falta para alcanzarlo. Ver
    [Próximo nivel](#próximo-nivel).
  </Field>

  <Field name="total_earned_points" type="integer | null">
    Puntos ganados en total, el acumulado histórico.
  </Field>

  <Field name="total_spent_amount" type="number | null">
    Monto gastado en total.
  </Field>

  <Field name="total_consumptions_count" type="integer | null">
    Cantidad de consumos registrados.
  </Field>
</Fields>

### Próximo nivel [#próximo-nivel]

<Fields>
  <Field name="name" type="string | null">
    Nombre del próximo nivel.
  </Field>

  <Field name="rank" type="integer | null">
    Posición del próximo nivel.
  </Field>

  <Field name="threshold_type" type="string | null">
    Con qué se mide el umbral: por puntos acumulados o por monto gastado.
  </Field>

  <Field name="threshold" type="number | null">
    El valor del umbral a alcanzar.
  </Field>
</Fields>

## Movimiento [#movimiento]

Cada item de [mi historial](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial).

<Fields>
  <Field name="type" type="string" required="true">
    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).
  </Field>

  <Field name="date" type="date-time | null">
    Cuándo pasó.
  </Field>

  <Field name="points" type="integer | null">
    Puntos que sumó o restó el movimiento.
  </Field>

  <Field name="benefit" type="Beneficio | null">
    El beneficio involucrado, en los movimientos de beneficio. Ver
    [Beneficio](#beneficio).
  </Field>

  <Field name="amount" type="number | null">
    Monto de la compra, en los movimientos de tipo `consumption`.
  </Field>

  <Field name="event" type="string | null">
    El evento que disparó la recompensa, en los `points_special_reward`.
  </Field>

  <Field name="additional_note" type="string | null">
    Nota adicional del movimiento.
  </Field>
</Fields>

## Recompensa automática [#recompensa-automática]

Cada item de [recompensas del programa](https://docs.loybox.com.ar/api-reference/mi-cuenta/recompensas).

<Fields>
  <Field name="event" type="string" required="true">
    Evento que la dispara: `welcome`, `birthday` o `monthly_top`.
  </Field>

  <Field name="reward_type" type="string" required="true">
    `benefit` si entrega un beneficio, `points` si entrega puntos.
  </Field>

  <Field name="benefit" type="Beneficio | null">
    El beneficio que entrega, cuando `reward_type` es `benefit`. Ver
    [Beneficio](#beneficio).
  </Field>

  <Field name="points" type="integer | null">
    Los puntos que entrega, cuando `reward_type` es `points`.
  </Field>
</Fields>

## Sesión [#sesión]

La respuesta de
[verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo).

<Fields>
  <Field name="access" type="string" required="true">
    Token de acceso. Se manda como `Authorization: Bearer {access}` en los
    endpoints de Mi cuenta.
  </Field>

  <Field name="refresh" type="string" required="true">
    Token de refresco, para obtener un nuevo `access` sin volver a pedir un
    código.
  </Field>

  <Field name="expires_in" type="integer" required="true">
    Segundos de validez del token de acceso.
  </Field>

  <Field name="user_id" type="integer" required="true">
    Id del usuario.
  </Field>

  <Field name="username" type="string | null">
    Nombre del usuario.
  </Field>

  <Field name="email" type="string | null">
    Email del usuario.
  </Field>

  <Field name="phone" type="string | null">
    Teléfono del usuario.
  </Field>
</Fields>

## Cupón de Tiendanube [#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).

<Fields>
  <Field name="type" type="string" required="true">
    `percentage`, `absolute` o `shipping`.
  </Field>

  <Field name="value" type="number" required="true">
    El valor del cupón.
  </Field>

  <Field name="category" type="string | null">
    Id de la categoría de Tiendanube a la que aplica el cupón.
  </Field>

  <Field name="category_name" type="string | null">
    Nombre de esa categoría.
  </Field>

  <Field name="end_date" type="date-time | null">
    Hasta cuándo vale el cupón.
  </Field>

  <Field name="product" type="Producto de Tiendanube | null">
    El producto al que aplica el cupón, si aplica a uno solo. Ver
    [Producto de Tiendanube](#producto-de-tiendanube).
  </Field>
</Fields>

### Producto de Tiendanube [#producto-de-tiendanube]

<Fields>
  <Field name="tiendanube_id" type="integer | null">
    Id del producto en Tiendanube.
  </Field>

  <Field name="name" type="string | null">
    Nombre del producto.
  </Field>

  <Field name="url" type="string | null">
    URL del producto en la tienda.
  </Field>

  <Field name="available" type="boolean | null">
    Si hay stock.
  </Field>

  <Field name="published" type="boolean | null">
    Si está publicado en la tienda.
  </Field>

  <Field name="brand" type="string | null">
    Marca del producto.
  </Field>

  <Field name="categories" type="array de categorías">
    Categorías del producto, cada una con `id` y `name`. Por defecto, vacío.
  </Field>
</Fields>


# Errores (https://docs.loybox.com.ar/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ó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 [#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"
    }
  ]
}
```

<Fields title="Cada item de detail">
  <Field name="loc" type="array" required="true">
    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.
  </Field>

  <Field name="msg" type="string" required="true">
    Qué tiene de malo.
  </Field>

  <Field name="type" type="string" required="true">
    El tipo de error de validación.
  </Field>
</Fields>

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 [#dos-casos-que-no-son-errores]

<Callout title="Pedir un código siempre responde 200">
  [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo)
  responde `200` incluso si el email no tiene cuenta en Loybox. Es a propósito:
  si respondiera distinto, cualquiera podría usar el endpoint para averiguar qué
  emails están registrados. No lo uses para validar si un usuario existe.
</Callout>

<Callout title="Sin nivel asignado es un 404">
  [`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.
</Callout>

## Reintentos [#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 mandás el mismo valor otra vez, la compra
no se repite.

```
Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b
```

Usá 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/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 fidelidad. Si sólo vas a llamar un
endpoint de toda esta API, es alguno de estos dos.

## Los dos endpoints [#los-dos-endpoints]

Hacen lo mismo y se diferencian sólo en cómo identifican al cliente:

|                               | Por código                               | Por email                                      |
| ----------------------------- | ---------------------------------------- | ---------------------------------------------- |
| **Identifica al cliente con** | Su `client_code`                         | Su email                                       |
| **Si el cliente no existe**   | Devuelve `404`                           | Registra el consumo igual y lo invita por mail |
| **Cuándo usarlo**             | Caja o app donde el cliente da su código | Checkout online, donde ya tenés el email       |

<Cards>
  <Card title="Crear consumo por código" icon="User" description="Cuando el cliente se identifica con su código de Loybox." href="/api-reference/consumos/crear-por-codigo" />

  <Card title="Crear consumo por email" icon="Mail" description="Cuando ya tenés el email, aunque el cliente no esté registrado." href="/api-reference/consumos/crear-por-email" />
</Cards>

## Cuántos puntos suma [#cuántos-puntos-suma]

Eso no lo decide la llamada: lo decide la configuración del comercio. Vos mandás
el **monto** de la compra y Loybox aplica la regla de dinero por punto, los
puntos dobles si están vigentes y el bonus 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).

<Callout type="warn" title="El monto va en entero">
  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`.
</Callout>

## Credencial [#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/api-reference/consumos/crear-por-codigo)



<Endpoint method="POST" path="/v1/consumptions/client-code" auth="api-key" />

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 preferís que el consumo se
registre igual, usá
[crear consumo por email](https://docs.loybox.com.ar/api-reference/consumos/crear-por-email).

## Cuerpo [#cuerpo]

<Fields>
  <Field name="client_code" type="integer" required="true">
    El código del cliente que hizo la compra.
  </Field>

  <Field name="amount" type="integer" required="true">
    Monto de la compra, en unidades enteras de la moneda del comercio.
  </Field>

  <Field name="counter_id" type="integer">
    Id de la caja donde se hizo la compra.
  </Field>

  <Field name="id_suc" type="integer">
    Id de la sucursal donde se hizo la compra.
  </Field>
</Fields>

## Ejemplo [#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, consultá al cliente con
[`GET /v1/clients/{client_code}`](https://docs.loybox.com.ar/api-reference/clientes/obtener).

## Errores [#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 email (https://docs.loybox.com.ar/api-reference/consumos/crear-por-email)



<Endpoint method="POST" path="/v1/consumptions/email" auth="api-key" />

Registra un nuevo consumo usando el email del cliente. Es el que conviene en un
checkout online, donde el email ya lo tenés y pedirle un código al cliente
sobraría.

<Callout title="Funciona aunque el cliente no tenga cuenta">
  Si el email no corresponde a ninguna cuenta de Loybox, el consumo **se crea
  igual** y automáticamente le llega un mail 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.
</Callout>

## Cuerpo [#cuerpo]

<Fields>
  <Field name="client_email" type="string" required="true">
    Email del cliente que hizo la compra.
  </Field>

  <Field name="amount" type="integer" required="true">
    Monto de la compra, en unidades enteras de la moneda del comercio.
  </Field>
</Fields>

## Ejemplo [#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 [#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 email 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/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 de caja, 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 acá.

## Los dos listados de beneficios [#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 |

<Cards>
  <Card title="Listar clientes" icon="Users" description="El listado completo del comercio, paginado." href="/api-reference/clientes/listar" />

  <Card title="Obtener un cliente" icon="User" description="Un cliente por su código, con su saldo de puntos." href="/api-reference/clientes/obtener" />

  <Card title="Beneficios que puede comprar" icon="Gift" description="El catálogo que le alcanza con los puntos que tiene." href="/api-reference/clientes/beneficios-disponibles" />

  <Card title="Beneficios comprados" icon="Tag" description="Los que ya compró, con el código de canje de cada uno." href="/api-reference/clientes/beneficios-comprados" />
</Cards>

## Credencial [#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}
```

<Callout type="warn" title="Devuelve datos de todos tus clientes">
  Estos endpoints exponen nombre, email y puntos de las personas del club. No los
  llames desde el frontend: si necesitás 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.
</Callout>


# Listar clientes (https://docs.loybox.com.ar/api-reference/clientes/listar)



<Endpoint method="GET" path="/v1/clients/list" auth="api-key" />

Trae el listado de clientes del comercio, paginado en formato límite y
desplazamiento.

## Parámetros [#parámetros]

<Fields>
  <Field name="limit" type="integer" location="query">
    Cuántos clientes traer por página. De `1` a `100`. Por defecto, `20`.
  </Field>

  <Field name="offset" type="integer" location="query">
    Desde qué posición arrancar. Por defecto, `0`.
  </Field>
</Fields>

## Respuesta [#respuesta]

<Fields>
  <Field name="items" type="array de clientes" required="true">
    Los clientes de esta página. Ver [Cliente](https://docs.loybox.com.ar/api-reference/objetos#cliente).
  </Field>

  <Field name="total" type="integer | null" required="true">
    Cantidad total de clientes del comercio, sin paginar.
  </Field>

  <Field name="limit" type="integer | null" required="true">
    El límite aplicado.
  </Field>

  <Field name="offset" type="integer | null" required="true">
    El desplazamiento aplicado.
  </Field>
</Fields>

## Ejemplo [#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, andá sumando `limit` al `offset` hasta que la
suma llegue a `total`.

## Errores [#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/api-reference/clientes/obtener)



<Endpoint method="GET" path="/v1/clients/{client_code}" auth="api-key" />

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 la caja y el que se usa
para [registrar un consumo](https://docs.loybox.com.ar/api-reference/consumos/crear-por-codigo).

## Parámetros [#parámetros]

<Fields>
  <Field name="client_code" type="string" location="path" required="true">
    El código del cliente.
  </Field>
</Fields>

## Respuesta [#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 [#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/api-reference/clientes/beneficios-disponibles)



<Endpoint method="GET" path="/v1/clients/{client_code}/available-benefits" auth="api-key" />

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 [#parámetros]

<Fields>
  <Field name="client_code" type="string" location="path" required="true">
    El código del cliente.
  </Field>
</Fields>

## Respuesta [#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, comparalo con el `points` de
[obtener un cliente](https://docs.loybox.com.ar/api-reference/clientes/obtener).

## Errores [#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/api-reference/clientes/beneficios-comprados)



<Endpoint method="GET" path="/v1/clients/{client_code}/benefits" auth="api-key" />

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, acá los que ya son suyos.

<Callout title="De acá sale el código de canje">
  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 local o pega en el checkout.
</Callout>

## Parámetros [#parámetros]

<Fields>
  <Field name="client_code" type="string" location="path" required="true">
    El código del cliente.
  </Field>

  <Field name="used" type="boolean | null" location="query">
    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.
  </Field>
</Fields>

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 [#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 [#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/api-reference/beneficios)



Esta sección tiene las dos mitades de la vida de un premio: **el catálogo** que
armó el comercio, y **el canje** de un código que un cliente trae para usar.

<Callout title="Beneficio y beneficio canjeable no son lo mismo">
  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**.
</Callout>

## El flujo del canje [#el-flujo-del-canje]

Así se ve del lado de tu sistema cuando un cliente llega con un código:

<Steps>
  <Step>
    ### El cliente da su código [#el-cliente-da-su-código]

    Lo tiene en su app de Loybox. Es el `client_benefit_code`.
  </Step>

  <Step>
    ### Consultás qué es [#consultás-qué-es]

    [`GET /v1/benefits/preview/{client_benefit_code}`](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo)
    te dice qué premio es y, si corresponde, qué descuento aplicar. Todavía no
    canjea nada.
  </Step>

  <Step>
    ### Aplicás el descuento [#aplicás-el-descuento]

    En tu caja, tu e-commerce o donde corra la venta, con los datos del paso
    anterior.
  </Step>

  <Step>
    ### Lo marcás como usado [#lo-marcás-como-usado]

    [`POST /v1/benefits/redeem`](https://docs.loybox.com.ar/api-reference/beneficios/canjear). A partir de acá
    el código queda quemado y no se puede volver a usar.
  </Step>
</Steps>

<Callout type="warn" title="Canjeá recién cuando la venta se concretó">
  Consultar es inofensivo y se puede repetir; canjear es definitivo. Si canjeás
  antes de cerrar la venta y la venta se cae, el cliente perdió el premio.
</Callout>

## Los endpoints [#los-endpoints]

<Cards>
  <Card title="Listar beneficios" icon="Boxes" description="Todo el catálogo que creó el comercio." href="/api-reference/beneficios/listar" />

  <Card title="Obtener un beneficio" icon="Gift" description="Un beneficio del catálogo por su benefit_id." href="/api-reference/beneficios/obtener" />

  <Card title="Consultar un código" icon="Tag" description="Qué premio es un client_benefit_code, antes de canjearlo." href="/api-reference/beneficios/consultar-codigo" />

  <Card title="Consultar un código (v2)" icon="Sparkles" description="Lo mismo, con el título y el valor del descuento al nivel de arriba." href="/api-reference/beneficios/consultar-codigo-v2" />

  <Card title="Canjear un beneficio" icon="BadgeCheck" description="Marca el código como usado. Es definitivo." href="/api-reference/beneficios/canjear" />
</Cards>

## Credencial [#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/api-reference/beneficios/listar)



<Endpoint method="GET" path="/v1/benefits/list" auth="api-key" />

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 [#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
  }
]
```

<Callout type="info" title="Trae también las recompensas especiales">
  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 querés mostrar sólo lo que el cliente puede comprar con puntos,
  filtrá por `normal`, o usá
  [beneficios que puede comprar](https://docs.loybox.com.ar/api-reference/clientes/beneficios-disponibles),
  que ya viene filtrado.
</Callout>

## Errores [#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/api-reference/beneficios/obtener)



<Endpoint method="GET" path="/v1/benefits/{benefit_id}" auth="api-key" />

Trae información sobre un beneficio del catálogo usando su id.

<Callout type="info" title="Este endpoint no canjea nada">
  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).
</Callout>

## Parámetros [#parámetros]

<Fields>
  <Field name="benefit_id" type="string" location="path" required="true">
    El id del beneficio.
  </Field>
</Fields>

## Respuesta [#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 [#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/api-reference/beneficios/consultar-codigo)



<Endpoint method="GET" path="/v1/benefits/preview/{client_benefit_code}" auth="api-key" />

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 premio 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: podés llamarlo las veces que necesites.

<Callout type="info" title="Hay una versión 2">
  [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.
</Callout>

## Parámetros [#parámetros]

<Fields>
  <Field name="client_benefit_code" type="string" location="path" required="true">
    El código de canje que tiene el cliente.
  </Field>
</Fields>

## Respuesta [#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 [#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` acá 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/api-reference/beneficios/consultar-codigo-v2)



<Endpoint method="GET" path="/v2/benefits/preview/{client_benefit_code}" auth="api-key" />

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, usá esta.

## Qué cambia [#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
chequear que exista. El resto de los campos son los mismos.

## Parámetros [#parámetros]

<Fields>
  <Field name="client_benefit_code" type="string" location="path" required="true">
    El código de canje que tiene el cliente.
  </Field>
</Fields>

## Respuesta [#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 [#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 [#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/api-reference/beneficios/canjear)



<Endpoint method="POST" path="/v1/benefits/redeem" auth="api-key" />

Canjea el beneficio usando el código que tiene el cliente. Es el último paso del
flujo: a partir de acá el código queda quemado y no se puede volver a usar.

<Callout type="warn" title="No tiene vuelta atrás">
  Llamá a este endpoint recién cuando la venta esté cerrada y el descuento
  aplicado. Si lo llamás antes y la venta se cae, el cliente pierde el premio y no
  hay forma de devolvérselo por API.

  Para ver qué premio es sin quemarlo, usá
  [consultar un código](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo).
</Callout>

## Cuerpo [#cuerpo]

<Fields>
  <Field name="client_benefit_code" type="integer" required="true">
    El código de canje que tiene el cliente.
  </Field>
</Fields>

## Ejemplo [#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 [#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. |

<Callout type="info" title="El 400 es el caso a cubrir en la UI">
  Es lo que pasa cuando alguien intenta usar el mismo código dos veces. No es un
  error de tu integración: conviene mostrarle al cajero un mensaje claro de
  "este código ya se usó" en lugar de un error genérico.
</Callout>


# Autenticación (https://docs.loybox.com.ar/api-reference/autenticacion)



Login del **usuario final** con un código de un solo uso enviado por email. 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 email, recibe un código de 6 dígitos y con
eso queda logueado.

## El flujo [#el-flujo]

<Steps>
  <Step>
    ### Pedir el código [#pedir-el-código]

    [`POST /v1/auth/otp/request`](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo) con el
    email del usuario. Le llega un código de 6 dígitos. El endpoint responde `200`
    siempre, incluso si ese email no tiene cuenta.
  </Step>

  <Step>
    ### Verificarlo [#verificarlo]

    [`POST /v1/auth/otp/verify`](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo) con
    el email y el código. Devuelve un token de acceso (`access`) y uno de refresco
    (`refresh`). Si el email no tenía cuenta en Loybox, se crea; en ambos casos el
    usuario queda adherido al programa de tu comercio.
  </Step>

  <Step>
    ### Usar la sesión [#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}`.
  </Step>

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

## Reglas del código [#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 [#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.

<Callout type="warn" title="No confundas las dos credenciales">
  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 browser. No mandes
  nunca la API key desde el frontend. Ver
  [Credenciales](https://docs.loybox.com.ar/api-reference/credenciales).
</Callout>

## Los endpoints [#los-endpoints]

<Cards>
  <Card title="Pedir un código" icon="Mail" description="Le manda al usuario un código de 6 dígitos por email." href="/api-reference/autenticacion/pedir-codigo" />

  <Card title="Verificar el código" icon="BadgeCheck" description="Valida el código y devuelve los tokens de sesión." href="/api-reference/autenticacion/verificar-codigo" />

  <Card title="Renovar el token" icon="RefreshCw" description="Un access nuevo a partir del refresh, sin molestar al usuario." href="/api-reference/autenticacion/renovar-token" />
</Cards>


# Pedir un código (https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo)



<Endpoint method="POST" path="/v1/auth/otp/request" auth="none" />

Envía por email un código de 6 dígitos para que el usuario final inicie sesión.

Si el email 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 acá.

<Callout title="Siempre responde 200">
  Responde `200` incluso si el email no existe. Es **a propósito**: si respondiera
  distinto, cualquiera podría usar este endpoint para averiguar qué emails están
  registrados.

  En la UI esto significa que después de pedir el código mostrás siempre el mismo
  mensaje ("te mandamos un código a tu email") sin poder saber si la cuenta
  existía.
</Callout>

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

No lleva `Authorization`: es el endpoint con el que arranca la sesión.

## Cuerpo [#cuerpo]

<Fields>
  <Field name="email" type="string" required="true">
    Email del usuario. Tiene que tener formato de email válido.
  </Field>
</Fields>

## Ejemplo [#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 [#reglas-del-código]

* Vence a los **10 minutos**.
* Admite **5 intentos**.
* Pedir un código nuevo **invalida el anterior**.

## Errores [#errores]

| Código | Cuándo                                                   |
| ------ | -------------------------------------------------------- |
| `422`  | Falta el header `X-Commerce-Id`, o el email es inválido. |


# Verificar el código (https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo)



<Endpoint method="POST" path="/v1/auth/otp/verify" auth="none" />

Valida el código enviado por email y devuelve los tokens de sesión del usuario
final.

Si el email 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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Cuerpo [#cuerpo]

<Fields>
  <Field name="email" type="string" required="true">
    El mismo email con el que se
    [pidió el código](https://docs.loybox.com.ar/api-reference/autenticacion/pedir-codigo).
  </Field>

  <Field name="otp" type="string" required="true">
    Código de 6 dígitos recibido por email. Exactamente 6 caracteres.
  </Field>
</Fields>

## Respuesta [#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
}
```

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

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

## Errores [#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/api-reference/autenticacion/renovar-token)



<Endpoint method="POST" path="/v1/auth/refresh" auth="none" />

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`, renovás y reintentás.

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Cuerpo [#cuerpo]

<Fields>
  <Field name="refresh" type="string" required="true">
    El token de refresco que devolvió
    [verificar el código](https://docs.loybox.com.ar/api-reference/autenticacion/verificar-codigo).
  </Field>
</Fields>

## Respuesta [#respuesta]

<Fields>
  <Field name="access" type="string" required="true">
    El token de acceso nuevo.
  </Field>

  <Field name="expires_in" type="integer | null">
    Segundos de validez del token nuevo.
  </Field>
</Fields>

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

<Callout type="info" title="No devuelve un refresh nuevo">
  La respuesta trae sólo el `access`. El `refresh` que ya tenías sigue siendo el
  válido: guardalo y seguí usándolo.
</Callout>

## Errores [#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` acá 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/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 [#el-circuito-típico]

Así se arma una web de fidelidad con estos endpoints:

<Steps>
  <Step>
    ### El primer render [#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 pintás el header y el
    saldo.
  </Step>

  <Step>
    ### El catálogo [#el-catálogo]

    [`GET /v1/me/benefits/available`](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles)
    para mostrar qué puede canjear.
  </Step>

  <Step>
    ### El canje [#el-canje]

    [`POST /v1/me/benefits/exchange`](https://docs.loybox.com.ar/api-reference/mi-cuenta/comprar-beneficio)
    cambia puntos por un beneficio.
  </Step>

  <Step>
    ### Los códigos [#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.
  </Step>
</Steps>

## Al armar la UI [#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-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 [#los-endpoints]

<Cards>
  <Card title="Mi cuenta" icon="User" description="Puntos, marca del comercio y puntos por vencer, en una llamada." href="/api-reference/mi-cuenta/obtener" />

  <Card title="Beneficios que puedo comprar" icon="Gift" description="El catálogo vigente del comercio." href="/api-reference/mi-cuenta/beneficios-disponibles" />

  <Card title="Comprar un beneficio" icon="Coins" description="Cambia puntos por un beneficio. Acepta Idempotency-Key." href="/api-reference/mi-cuenta/comprar-beneficio" />

  <Card title="Mis beneficios" icon="Tag" description="Los que ya compró, con su código de canje." href="/api-reference/mi-cuenta/mis-beneficios" />

  <Card title="Mi historial" icon="Clock" description="Consumos, compras, canjes y recompensas. Paginado por cursor." href="/api-reference/mi-cuenta/historial" />

  <Card title="Mi nivel" icon="Crown" description="Nivel actual, multiplicador y progreso al siguiente." href="/api-reference/mi-cuenta/nivel" />

  <Card title="Recompensas del programa" icon="Sparkles" description="Bienvenida, cumpleaños y cliente del mes." href="/api-reference/mi-cuenta/recompensas" />

  <Card title="Adherirme al programa" icon="UserPlus" description="Sumarse al club. Devuelve la recompensa de bienvenida." href="/api-reference/mi-cuenta/adherirme" />

  <Card title="Darme de baja" icon="Repeat" description="Salirse del club sin perder los puntos." href="/api-reference/mi-cuenta/darme-de-baja" />
</Cards>

## El 401 en toda la sección [#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:
[renovalo](https://docs.loybox.com.ar/api-reference/autenticacion/renovar-token) y reintentá la llamada.


# Mi cuenta (https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener)



<Endpoint method="GET" path="/v1/me" auth="user-token" />

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, rubro) 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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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`, mostrá 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".                                                                     |

<Callout type="info" title="Cuando los puntos no vencen">
  `points_expiration` no viene en `null`: viene con `mode: "none"` y `points: 0`.
  Chequeá el `mode` antes de mostrar el aviso de vencimiento.
</Callout>

## Errores [#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/api-reference/mi-cuenta/beneficios-disponibles)



<Endpoint method="GET" path="/v1/me/benefits/available" auth="user-token" />

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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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).

<Callout type="info" title="Sin login, el mismo catálogo es público">
  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.
</Callout>

## Errores [#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/api-reference/mi-cuenta/comprar-beneficio)



<Endpoint method="POST" path="/v1/me/benefits/exchange" auth="user-token" />

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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>

  <Field name="Idempotency-Key" type="string | null" location="header">
    Clave para que un reintento no cobre los puntos dos veces.
  </Field>
</Fields>

<Callout title="Usá el Idempotency-Key">
  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.

  Generá un valor por cada compra que el usuario inicia (un UUID alcanza) y usá
  el mismo en todos los reintentos de esa compra.
</Callout>

## Cuerpo [#cuerpo]

<Fields>
  <Field name="benefit_id" type="string" required="true">
    Id del beneficio a comprar, tal como lo devuelve
    [beneficios que puedo comprar](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles).
  </Field>
</Fields>

## Respuesta [#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 [#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/api-reference/mi-cuenta/mis-beneficios)



<Endpoint method="GET" path="/v1/me/benefits" auth="user-token" />

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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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
    }
  }
]
```

<Callout title="El código es el cupón">
  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.
</Callout>

## Errores [#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/api-reference/mi-cuenta/historial)



<Endpoint method="GET" path="/v1/me/activity" auth="user-token" />

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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Parámetros [#parámetros]

<Fields>
  <Field name="cursor" type="string | null" location="query">
    Cursor de la página a traer. Se obtiene del `next_cursor` de la respuesta
    anterior. Sin especificar, trae la primera página.
  </Field>
</Fields>

## Respuesta [#respuesta]

<Fields>
  <Field name="results" type="array de movimientos" required="true">
    Los movimientos de esta página. Ver
    [Movimiento](https://docs.loybox.com.ar/api-reference/objetos#movimiento).
  </Field>

  <Field name="next_cursor" type="string | null">
    Se pasa como `?cursor=` para traer la página siguiente. `null` cuando no hay
    más.
  </Field>

  <Field name="previous_cursor" type="string | null">
    El cursor de la página anterior.
  </Field>
</Fields>

## Ejemplo [#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 [#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 [#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/api-reference/mi-cuenta/nivel)



<Endpoint method="GET" path="/v1/me/level" auth="user-token" />

Nivel actual del usuario en este comercio, con su multiplicador de puntos, el
progreso acumulado y cuál es el próximo nivel.

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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 [#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`  |

<Callout type="info" title="Canjear no baja de nivel">
  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).
</Callout>

## Errores [#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`.                                                           |

<Callout type="warn" title="El 404 es el caso normal de un cliente nuevo">
  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.
</Callout>


# Recompensas del programa (https://docs.loybox.com.ar/api-reference/mi-cuenta/recompensas)



<Endpoint method="GET" path="/v1/me/rewards" auth="user-token" />

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 [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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 [#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`, el premio está en `benefit`;
si es `points`, está en `points`. El otro campo viene en `null`.

<Callout type="info" title="Es una lista de lo que el programa ofrece">
  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`.
</Callout>

## Errores [#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/api-reference/mi-cuenta/adherirme)



<Endpoint method="POST" path="/v1/me/subscription" auth="user-token" />

Adhiere al usuario al programa de fidelidad del comercio. Si el comercio
configuró una recompensa de bienvenida, se devuelve en `welcome_benefit` o
`welcome_points`.

<Callout type="info" title="Verificar el código ya adhiere al usuario">
  [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**.
</Callout>

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

No lleva cuerpo.

## Respuesta [#respuesta]

<Fields>
  <Field name="message" type="string" required="true">
    Resultado de la operación.
  </Field>

  <Field name="welcome_benefit" type="Beneficio | null">
    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).
  </Field>

  <Field name="welcome_points" type="integer | null">
    Puntos de bienvenida, si el comercio configuró puntos en vez de un beneficio.
  </Field>
</Fields>

```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`, el premio; si vino `welcome_points`, los puntos que acaba de
ganar.

## Errores [#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/api-reference/mi-cuenta/darme-de-baja)



<Endpoint method="DELETE" path="/v1/me/subscription" auth="user-token" />

Da de baja al usuario del programa del comercio.

<Callout title="Los puntos no se pierden">
  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.
</Callout>

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

No lleva cuerpo.

## Respuesta [#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 [#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/api-reference/publico)



Endpoints que **no requieren ningún token**, sólo el header `X-Commerce-Id`.

Sirven para mostrarle tu programa de fidelidad a un visitante que todavía no
inició sesión: la marca en el header y el catálogo de premios, para que vea qué
gana si se suma.

```
X-Commerce-Id: {tu-commerce-id}
```

## Los endpoints [#los-endpoints]

<Cards>
  <Card title="Datos del comercio" icon="Building2" description="Nombre, logo, color de marca y rubro, para pintar el header." href="/api-reference/publico/comercio" />

  <Card title="Catálogo de beneficios" icon="Gift" description="Los beneficios vigentes del comercio." href="/api-reference/publico/beneficios" />
</Cards>

## Después del login, no hace falta volver a pedirlos [#después-del-login-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 login                                                      | Con login                                                                          |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`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: usá los públicos para la pantalla de bienvenida, y cambiá a los
de Mi cuenta en cuanto haya sesión.

<Callout type="info" title="X-Commerce-Id no es un secreto">
  Va en el frontend sin problema. Lo que hace es delimitar la respuesta a tu
  comercio, no autorizar el acceso.
</Callout>


# Datos del comercio (https://docs.loybox.com.ar/api-reference/publico/comercio)



<Endpoint method="GET" path="/v1/public/commerce" auth="none" />

Nombre, logo, color de marca y rubro del comercio, **sin necesidad de token**.

Sirve para pintar el header del programa antes de que el usuario inicie sesión.

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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"
}
```

<Callout type="info" title="Con sesión no hace falta llamarlo">
  Una vez logueado, 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.
</Callout>

## Errores [#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/api-reference/publico/beneficios)



<Endpoint method="GET" path="/v1/public/benefits" auth="none" />

Beneficios vigentes del comercio, **sin necesidad de token**.

Sirve para mostrarle el programa de fidelidad a un visitante que todavía no
inició sesión: es la vidriera de premios que responde "¿qué gano si me sumo?".

## Headers [#headers]

<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id del comercio que integra la API. Todas las respuestas quedan limitadas a
    este comercio.
  </Field>
</Fields>

## Respuesta [#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
  }
]
```

<Callout type="info" title="Con sesión, usá el de Mi cuenta">
  Una vez logueado 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.
</Callout>

## Errores [#errores]

| Código | Cuándo                                              |
| ------ | --------------------------------------------------- |
| `400`  | No se pudieron obtener los beneficios del comercio. |
| `422`  | Falta el header `X-Commerce-Id`.                    |