# About the API (https://docs.loybox.com.ar/en/api-reference)



The Loybox API does the same things the dashboard does, but from your code:
recording purchases that earn points, showing the reward catalog, redeeming codes
and looking up a member's state.

It is a **REST API over HTTPS**. Everything goes back and forth as JSON, field
names are in `snake_case` and dates are ISO 8601 with a time zone
(`2026-03-14T18:30:00Z`).

## Base URL
Every route in this reference hangs off:

```
https://loybox-public-api-752998171300.southamerica-west1.run.app
```

The version goes in the first path segment (`/v1/...`). When an endpoint changes
in a non-compatible way, a new version appears alongside the old one, and the old
one keeps working: that is the case with
[looking up a code](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo) and its
[version 2](https://docs.loybox.com.ar/api-reference/beneficios/consultar-codigo-v2).

## The examples
Every endpoint page carries the whole call in `curl`, ready to paste into a
terminal. Three things are variables and apply to every example:

| In the example      | What to put                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `$LOYBOX_API_KEY`   | Your [API key](https://docs.loybox.com.ar/api-reference/credenciales#api-key-del-comercio). Export it in the environment; do not paste it into the command. |
| `$ACCESS_TOKEN`     | The [end-user token](https://docs.loybox.com.ar/api-reference/credenciales#token-del-usuario-final) that the login returned.                                |
| `X-Commerce-Id: 87` | **Your** commerce id.                                                                                                             |

## Machine format
The API is also published as a specification, so you can generate a client
instead of writing one:

```
https://docs.loybox.com.ar/openapi.json
```

It is OpenAPI 3.1 and covers all 25 endpoints, the response schemas and the two
credentials. If you are integrating with the help of an agent, hand it that URL.

<Callout type="info" title="The specification is in Spanish">
  There is one `openapi.json` for all three languages, and its field descriptions
  are in Spanish. Field names, endpoint paths and schemas are language-neutral, so a
  generated client is identical either way.
</Callout>

## The two ways to integrate
This is the most important decision, and it is worth making before writing code,
because it changes the credential, the available endpoints and where your code
runs.

<Cards>
  <Card title="From your server" icon="Building2" description="Your backend operates across every member of the commerce. It authenticates with the API key. This is the classic integration: point of sale, ERP, your own ecommerce." href="/api-reference/credenciales" />

  <Card title="From your website" icon="Smartphone" description="The end user signs in with a code emailed to them and looks up their own points. Loybox as the loyalty engine behind your frontend." href="/api-reference/credenciales" />
</Cards>

Every section of this reference uses one of the two, and every endpoint page says
which at the top:

| Section                                        | Credential     | What for                                 |
| ---------------------------------------------- | -------------- | ---------------------------------------- |
| [Consumptions](https://docs.loybox.com.ar/api-reference/consumos)        | API key        | Recording purchases that earn points     |
| [Clients](https://docs.loybox.com.ar/api-reference/clientes)             | API key        | Looking up members and their benefits    |
| [Benefits](https://docs.loybox.com.ar/api-reference/beneficios)          | API key        | Catalog, code lookup and redemption      |
| [Authentication](https://docs.loybox.com.ar/api-reference/autenticacion) | —              | End-user sign-in by email                |
| [My account](https://docs.loybox.com.ar/api-reference/mi-cuenta)         | End-user token | The user's points, purchases and history |
| [Public](https://docs.loybox.com.ar/api-reference/publico)               | —              | Brand and catalog, without signing in    |

<Callout type="warn" title="The API key never goes in the frontend">
  The commerce API key grants access to the data of **all** your members. It lives
  on your server only. What can live in the browser is the end user's access token,
  which only sees their own data.
</Callout>

## What responses look like
Responses have no envelope: the object comes at the root, and lists come back as
a plain array.

```json
// GET /v1/clients/12345
{
  "code": 12345,
  "username": "Ana Pérez",
  "email": "ana@example.com",
  "points": 340
}
```

Optional fields are present and set to `null`, not absent. You can read them
without checking whether they exist, but you do have to check whether they are
`null`.

## Pagination
There are two schemes, and each one lives in a single endpoint:

### Limit and offset
[Listing clients](https://docs.loybox.com.ar/api-reference/clientes/listar) uses `limit` and `offset`, and
returns the total so you can build page numbers.

```json
// GET /v1/clients/list?limit=20&offset=40
{
  "items": [],
  "total": 1875,
  "limit": 20,
  "offset": 40
}
```

`limit` goes from 1 to 100 and defaults to 20. `offset` starts at 0.

### Cursor
[My history](https://docs.loybox.com.ar/api-reference/mi-cuenta/historial) uses a cursor, because it is a
list that grows at the top and page numbers would shift under you. You request
the next page by passing the previous response's `next_cursor` in `?cursor=`.

```json
// GET /v1/me/activity
{
  "results": [],
  "next_cursor": "eyJkIjoiMjAyNi0wMy0xNCJ9",
  "previous_cursor": null
}
```

When `next_cursor` comes back `null`, there are no more pages.

## Where to start
<Cards>
  <Card title="Getting started" icon="Rocket" description="The complete integration end to end: from the first purchase that earns points through to redemption." href="/api-reference/primeros-pasos" />

  <Card title="Credentials" icon="BadgeCheck" description="How each of the two integrations authenticates, and which headers go on each call." href="/api-reference/credenciales" />

  <Card title="Objects" icon="Boxes" description="The objects the API returns, and the difference between a benefit and a redeemable benefit." href="/api-reference/objetos" />

  <Card title="Errors" icon="TriangleAlert" description="The status codes the API can return and what to do with each one." href="/api-reference/errores" />

  <Card title="Technical reference" icon="Braces" description="How Loybox works under the hood: point formulas, expirations and tier rules." href="/referencia-tecnica" />
</Cards>