# Clientes

Lista y consulta las personas que te compraron, con lo que pagaron, sus ventas y sus suscripciones.

> [!WARNING]
> El SDK `vexor` de npm (Stripe, MercadoPago, PayPal, Square, Talo) está **deprecado**: ya no se mantiene y no debe usarse. vexorpay es hoy una **API REST de links de pago en USD, sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

Fuente: <https://developers.staging.vexorpay.com/docs/api/customers>

Cada persona que te compra por uno de tus links es un `customer`. La API te devuelve tus
clientes con sus totales y, en el detalle, sus [ventas](/docs/api/orders) y sus
[suscripciones](/docs/api/subscriptions). Los clientes se arman a partir de tus ventas: un
cliente es una persona (un email) que compró al menos una vez.

## El objeto Customer

```json
{
  "id": "cliente@ejemplo.com",
  "email": "cliente@ejemplo.com",
  "name": "Ana Pérez",
  "ordersCount": 3,
  "totalSpentCents": 6400,
  "activeSubscriptions": 1,
  "firstPurchaseAt": "2026-10-24T01:47:49.220Z",
  "lastPurchaseAt": "2026-10-26T18:41:11.098Z"
}
```

- `id` identifica al cliente (el email normalizado o un id interno). Trátalo como un valor
  opaco y úsalo tal cual, codificado en la URL, en `GET /api/v1/customers/{id}`.
- `totalSpentCents` es lo que pagó el cliente, en centavos de USD, **neto de reembolsos**.
- `ordersCount` cuenta las ventas pagadas, incluidas las reembolsadas.
- `activeSubscriptions` cuenta las suscripciones `active`, `trialing` o `past_due`.
- `firstPurchaseAt` / `lastPurchaseAt`: la primera y la última compra.

## Listar clientes

`GET /api/v1/customers`

| Parámetro | Descripción |
| --- | --- |
| `email` | Email exacto (sin distinguir mayúsculas). |
| `query` | Busca en el email o el nombre. |
| `limit` / `starting_after` / `ending_before` | Paginación por cursor (default 10, máximo 100). |

De la compra más reciente a la más vieja.

```bash
curl "https://api.vexorpay.com/api/v1/customers?query=ana" \
  -H "Authorization: Bearer vxp_live_tu_clave"
```

## Ver un cliente

`GET /api/v1/customers/{id}`

Devuelve el cliente con dos campos más: `orders` (sus ventas, hasta 100, más nuevas
primero, con el formato de [Ventas](/docs/api/orders)) y `subscriptions` (sus
suscripciones, con el formato de [Suscripciones](/docs/api/subscriptions)). Para
reembolsar una de sus ventas usa `POST /api/v1/orders/{id}/refund`.

```bash
curl "https://api.vexorpay.com/api/v1/customers/cliente%40ejemplo.com" \
  -H "Authorization: Bearer vxp_live_tu_clave"
```

## Errores

| Error | HTTP | Causa |
| --- | --- | --- |
| `validation_error` | 400 | `limit` inválido. |
| `customer_not_found` | 404 | No existe ese cliente en tu cuenta (o es de otro modo). |