Buy a benefit

POST/v1/me/benefits/exchangeEnd-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 call that moves points.

Headers

X-Commerce-Idintegerheaderrequired

Id of the commerce integrating the API. Every response is scoped to this commerce.

Idempotency-Keystring | nullheader

A key so a retry does not charge the points twice.

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.

Body

benefit_idstringrequired

Id of the benefit to buy, exactly as benefits I can buy returns it.

Response

A Redeemable benefit object.

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

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.

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.

Headers

Body

Response

Errors

On this page