# Clientes

Lista y consulta las personas que te compraron por Polar, 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 sobre Stripe, siempre en USD, sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

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

Cada persona que te compra por un link cobrado con **Polar** 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). También aparecen los clientes que te
compraron antes de que conectaras tu cuenta: vexorpay los importa de Polar.

## El objeto Customer

```json
{
  "id": "66f1c1e2c8a4b0d1f2e3a4c7",
  "provider": "polar",
  "polarCustomerId": "8b2f4c1e-7d3a-4e8b-9c1d-2a3b4c5d6e7f",
  "email": "cliente@ejemplo.com",
  "name": "Ana Pérez",
  "country": "AR",
  "externalId": null,
  "stats": {
    "ordersCount": 3,
    "totalSpentCents": 6400,
    "refundedCents": 0,
    "currency": "usd",
    "activeSubscriptions": 1,
    "lastOrderAt": "2026-10-26T18:41:11.098Z"
  },
  "sandbox": false,
  "createdAt": "2026-10-24T01:47:49.220Z"
}
```

- `stats.totalSpentCents` es lo que pagó el cliente (impuesto incluido), **neto de
  reembolsos**; `stats.refundedCents`, lo que se le devolvió, también con el impuesto
  (Polar lo devuelve en proporción).
- `stats.ordersCount` cuenta las ventas pagadas, incluidas las reembolsadas.
- `stats.activeSubscriptions` cuenta las suscripciones `active`, `trialing` o `past_due`.
- `country` es el país de facturación (ISO 3166-1 alfa-2) y `createdAt`, el alta del
  cliente en Polar.

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

Del más nuevo al más viejo.

```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 de Polar](/docs/api/orders)) y `subscriptions` (sus
suscripciones, con el formato de [Suscripciones](/docs/api/subscriptions)). Para
reembolsar una de sus ventas usá `POST /api/v1/orders/{id}/refund`.

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