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