Comprar un beneficio
Cambia los puntos del usuario por un beneficio del catálogo y devuelve el código de canje.
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 que mueve puntos.
Headers
X-Commerce-IdintegerheaderrequeridoId del comercio que integra la API. Todas las respuestas quedan limitadas a este comercio.
Idempotency-Keystring | nullheaderClave para que un reintento no cobre los puntos dos veces.
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.
Cuerpo
benefit_idstringrequeridoId del beneficio a comprar, tal como lo devuelve beneficios que puedo comprar.
Respuesta
Un objeto Beneficio canjeable.
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"
}'// 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.
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.