# Transacciones de saldo

> `GET https://api.cfdi.express/v1/billing/transactions` — El ledger completo de tu saldo: cada recarga, consumo, reembolso y ajuste con el saldo resultante.

URL de esta página: https://cfdi.express/docs/api/transacciones
Autenticación: requiere API key (`Authorization: Bearer sk_test_…` o `sk_live_…`)

Cada movimiento incluye `deltaCentavos` (positivo o negativo) y `balanceAfterCentavos`, para que puedas auditar el saldo sin recalcular nada.

Paginación por cursor: toma el `id` del último elemento y pásalo como `starting_after` mientras `has_more` sea `true`.

### Query string

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | integer | no | Elementos por página. Entre 1 y 100. Default 10. |
| `starting_after` | string | no | Id de la última transacción de la página anterior (cursor). |
| `type` | string | no | Filtra por tipo: purchase, consume, refund, recharge, adjustment o seed. |

## Ejemplos

### cURL

```bash
curl "https://api.cfdi.express/v1/billing/transactions?limit=2&type=consume" \
  -H "Authorization: Bearer sk_live_..."
```

## Respuesta

### 200 OK

```json
{
  "object": "list",
  "data": [
    {
      "id": "txn3k9x2m6q4v1p8d7n5c0br",
      "object": "transaction",
      "livemode": true,
      "type": "consume",
      "deltaCentavos": -100,
      "balanceAfterCentavos": 48200,
      "referenceType": "invoice",
      "referenceId": "inv7k3q9x2m4v1t8p6d0n5cb",
      "note": null,
      "createdAt": "2026-08-18T17:42:11.918Z"
    },
    {
      "id": "txn8m2x6q4k1v3p9d7n5c0bt",
      "object": "transaction",
      "livemode": true,
      "type": "purchase",
      "deltaCentavos": 50000,
      "balanceAfterCentavos": 48300,
      "referenceType": "purchase",
      "referenceId": "pur5m9x2q7v1p8d3t6n0c4br",
      "note": "Stripe checkout",
      "createdAt": "2026-08-17T09:05:44.201Z"
    }
  ],
  "has_more": true
}
```

## Errores

| Status | code | Cuándo aparece |
|---|---|---|
| 401 | `unauthorized` | Falta el header Authorization o la llave es inválida. |
| 429 | `rate_limited` | Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After. |

## Relacionados

- [GET /v1/balance](https://cfdi.express/docs/api/saldo) — Consultar saldo
- [GET /v1/billing/usage](https://cfdi.express/docs/api/uso-mensual) — Uso mensual
- [POST /v1/billing/checkout_sessions](https://cfdi.express/docs/api/recargar-saldo) — Recargar saldo

---

Referencia completa: https://cfdi.express/docs/api · OpenAPI: https://api.cfdi.express/openapi.json · Llaves: https://dash.cfdi.express