# Buy a benefit (https://docs.loybox.com.ar/en/api-reference/mi-cuenta/comprar-beneficio)



<Endpoint method="POST" path="/v1/me/benefits/exchange" auth="user-token" />

Trades the user's points for a catalog benefit. It returns the purchased benefit
with its `client_benefit_code`, which is the code later redeemed at the commerce.

It is the only [My account](https://docs.loybox.com.ar/api-reference/mi-cuenta) call that moves points.

## Headers
<Fields>
  <Field name="X-Commerce-Id" type="integer" location="header" required="true">
    Id of the commerce integrating the API. Every response is scoped to this
    commerce.
  </Field>

  <Field name="Idempotency-Key" type="string | null" location="header">
    A key so a retry does not charge the points twice.
  </Field>
</Fields>

<Callout title="Use the Idempotency-Key">
  If the network drops after the server processed the purchase, your retry can
  charge the points again. With the `Idempotency-Key`, sending the same key again
  does not repeat the purchase.

  Generate one value per purchase the user starts (a UUID is enough) and use the same
  one across every retry of that purchase.
</Callout>

## Body
<Fields>
  <Field name="benefit_id" type="string" required="true">
    Id of the benefit to buy, exactly as
    [benefits I can buy](https://docs.loybox.com.ar/api-reference/mi-cuenta/beneficios-disponibles) returns
    it.
  </Field>
</Fields>

## Response
A
[Redeemable benefit](https://docs.loybox.com.ar/api-reference/objetos#beneficio-canjeable) object.

```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
  }
}
```

The `client_benefit_code` is what to show the user: it is their redemption code and
also the coupon code in an online store. After buying, it is worth refreshing the
`points` with [`GET /v1/me`](https://docs.loybox.com.ar/api-reference/mi-cuenta/obtener).

## Errors
| Code  | When                                                                       |
| ----- | -------------------------------------------------------------------------- |
| `400` | The benefit does not exist, is not valid, or the user's points fall short. |
| `401` | The access token is missing, expired, or does not belong to an end user.   |
| `422` | The `X-Commerce-Id` header is missing, or the `benefit_id` is missing.     |

The `400` bundles all three cases, so it is worth preventing them in the UI: do not
offer to buy a benefit whose `cost` exceeds the user's points.