# Créditos y facturación

Una verificación cuesta un crédito, y solo cuando te aporta algo. Cada resultado dice lo que ha cobrado en `credits_charged`.

## Dos saldos

Cada `mode` tiene su propio saldo. Uno nunca paga por el otro.

| | Créditos `basic` | Créditos `mailbox` |
| --- | --- | --- |
| Los usa | `"mode": "basic"` | `"mode": "mailbox"` |
| De dónde salen | Asignación mensual de tu plan | Packs de pago único |
| Caducidad | Se renuevan en `resets_at`. No se acumulan | Consulta `next_expiry` en `GET /usage`. Primero se gastan los créditos que antes caducan |

| Plan | Créditos `basic` al mes |
| --- | --- |
| Gratis | 1.000 |
| Básico | 20.000 |
| Básico+ | 150.000 |

Una cuenta nueva empieza con 100 créditos de buzón. Los packs de buzón son de 2.500, 10.000, 50.000 y 100.000 verificaciones. Los precios vigentes están en la [página de precios](https://salchimail.com/es/#precios) y las condiciones de los packs, en los [términos](https://salchimail.com/es/terminos). Planes y packs se compran en el panel, en [app.salchimail.com](https://app.salchimail.com), donde también están tus facturas.

## Qué se cobra

| Modo | Se cobra | Gratis |
| --- | --- | --- |
| `basic` | 1 crédito basic por verificación terminada, sea cual sea el veredicto | Los resultados `dns_temporary`. Las repeticiones de la misma dirección en 30 días |
| `mailbox` | 1 crédito mailbox **solo cuando el veredicto no es `unknown`** | Todos los `unknown`. Las repeticiones de la misma dirección en 24 horas. Los duplicados dentro de un lote |

También es gratis, siempre:

- Las peticiones que terminan en error (`4xx`, `5xx`), incluido `503 verification_timeout`.
- Las repeticiones de una petición con la misma [`Idempotency-Key`](https://docs.salchimail.com/es/idempotencia.md).
- Todo lo que se hace con una clave `sk_test_` ([Entorno de pruebas](https://docs.salchimail.com/es/entorno-de-pruebas.md)).

## Créditos en los lotes

Un lote **reserva** un crédito por dirección única al crearse, cobra cada fila cuando alcanza un resultado final y devuelve lo que sobra al terminar o al cancelarse. Los créditos reservados no están disponibles para otras peticiones mientras el lote está en curso. Detalles en [Limpieza de listas por lotes](https://docs.salchimail.com/es/lotes.md).

## Consulta tu saldo

```bash
curl https://api.salchimail.com/v1/usage \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY"
```

```json
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 18760,
      "reserved": 0,
      "granted": 20000,
      "resets_at": "2026-12-01T00:00:00Z"
    },
    "mailbox": {
      "remaining": 2311,
      "reserved": 1,
      "next_expiry": null
    }
  },
  "period": {
    "start": "2026-11-01T00:00:00Z",
    "end": "2026-12-01T00:00:00Z"
  },
  "usage": {
    "basic": {
      "verifications": 1302,
      "credits_charged": 1240
    },
    "mailbox": {
      "verifications": 214,
      "credits_charged": 188
    }
  }
}
```

| Campo | Significado |
| --- | --- |
| `credits.*.remaining` | Lo que puedes gastar ahora |
| `credits.*.reserved` | Retenido por lotes en curso |
| `credits.basic.granted` | Asignación mensual del periodo actual |
| `credits.basic.resets_at` | Cuándo se renueva la asignación basic |
| `credits.mailbox.next_expiry` | Los próximos créditos mailbox que caducan (`amount` y `at`), o `null` cuando ninguno caduca |
| `period` | Periodo de facturación actual de la asignación basic |
| `usage` | Verificaciones terminadas y créditos cobrados en el periodo, por modo |

## Cuando se acaban los créditos

Sin créditos del tipo que necesita una petición, la API responde `402`:

```json
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "This request needs 3 mailbox credits and the account has 0.",
    "request_id": "req_4b5c6d7e8f9a0b1f"
  }
}
```

Un `402` no bloquea el otro modo: sin créditos mailbox, las verificaciones `basic` siguen funcionando.

Para enterarte antes de que ocurra, suscríbete al [webhook `credits.low`](https://docs.salchimail.com/es/webhooks.md). Se dispara cuando un saldo cruza el umbral configurado en el panel (por defecto, el 10 % de la última concesión).
