# Credits and billing

One verification costs one credit, and only when it gives you something. Every result says what it charged in `credits_charged`.

## Two balances

Each `mode` has its own balance. One never pays for the other.

| | `basic` credits | `mailbox` credits |
| --- | --- | --- |
| Used by | `"mode": "basic"` | `"mode": "mailbox"` |
| Where they come from | Monthly allowance of your plan | One-off packs |
| Expiry | Reset at `resets_at`. They do not roll over | See `next_expiry` in `GET /usage`. Credits closest to expiring are spent first |

| Plan | `basic` credits per month |
| --- | --- |
| Free | 1,000 |
| Basic | 20,000 |
| Basic+ | 150,000 |

A new account starts with 100 mailbox credits. Mailbox packs come in 2,500, 10,000, 50,000 and 100,000 verifications. Current prices are on the [pricing page](https://salchimail.com/#pricing), and the conditions that apply to packs are in the [terms](https://salchimail.com/terms). Plans and packs are bought in the dashboard at [app.salchimail.com](https://app.salchimail.com), where you also find your invoices.

## What is charged

| Mode | Charged | Free |
| --- | --- | --- |
| `basic` | 1 basic credit per completed verification, whatever the verdict | `dns_temporary` results. Repeats of the same address within 30 days |
| `mailbox` | 1 mailbox credit **only when the verdict is not `unknown`** | Every `unknown`. Repeats of the same address within 24 hours. Duplicates inside a batch |

Also free, always:

- Requests that end in an error (`4xx`, `5xx`), including `503 verification_timeout`.
- Replays of a request with the same [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md).
- Everything done with a `sk_test_` key ([Test mode](https://docs.salchimail.com/test-mode.md)).

## Credits in batches

A batch **reserves** one credit per unique address when it is created, charges each row as it reaches a final result, and returns what is left when it finishes or is canceled. Reserved credits are not available to other requests while the batch runs. Details in [Clean a list in batches](https://docs.salchimail.com/batches.md).

## Check your balance

```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
    }
  }
}
```

| Field | Meaning |
| --- | --- |
| `credits.*.remaining` | What you can spend now |
| `credits.*.reserved` | Held by running batches |
| `credits.basic.granted` | Monthly allowance of the current period |
| `credits.basic.resets_at` | When the basic allowance resets |
| `credits.mailbox.next_expiry` | The next mailbox credits to expire (`amount` and `at`), or `null` when none expire |
| `period` | Current billing period of the basic allowance |
| `usage` | Verifications completed and credits charged in the period, by mode |

## When credits run out

With no credits of the type a request needs, the API answers `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"
  }
}
```

A `402` does not block the other mode: with no mailbox credits left, `basic` verifications keep working.

To hear about it before it happens, subscribe to the [`credits.low` webhook](https://docs.salchimail.com/webhooks.md). It fires when a balance crosses the threshold set in the dashboard (default: 10% of the last grant).
