> Toden documentation. For the full index fetch /llms.txt. Every page is available as Markdown by appending .md to its URL. Identity verification uses /api/kyc, Risk Intelligence uses /api/v1; they are separate contracts with different error shapes. Never invent an endpoint, field or enum value: read the API reference page for the operation first.

# Billing

> Track credit balance changes and API-key lifecycle events.

Billing events describe posted credit changes. API-key events provide a security audit signal but never expose the secret key.

## Events and payloads

| Event                   | When it fires                             | Recommended handling                                           |
| ----------------------- | ----------------------------------------- | -------------------------------------------------------------- |
| `credits.deducted`      | Billable verification usage is posted.    | Reconcile by `verificationId`.                                 |
| `credits.low`           | Balance crosses the configured threshold. | Notify billing owners once per logical event ID.               |
| `credits.topped_up`     | A top-up posts successfully.              | Reconcile the new balance.                                     |
| `credits.granted`       | Promotional credit is granted.            | Record the grant and expiry policy.                            |
| `credits.promo_expired` | Unused promotional credit expires.        | Reconcile the reduction without treating it as usage.          |
| `api_key.created`       | A key is created.                         | Audit the name, environment, type and prefix.                  |
| `api_key.revoked`       | A key is revoked.                         | Remove dependent access and investigate unexpected revocation. |

```json
{
  "version": "2026-08-11",
  "id": "evt_credit_deducted_01",
  "type": "credits.deducted",
  "createdAt": "2026-08-15T18:00:00.000Z",
  "deliveryId": "del_credit_deducted_01",
  "data": { "verificationId": "ver_01", "amount": "0.2000", "currency": "USD" }
}
```

```json
[
  { "type": "credits.low", "data": { "orgId": "org_01", "balance": "20.0000", "threshold": "25.0000", "currency": "USD" } },
  { "type": "credits.topped_up", "data": { "orgId": "org_01", "amount": "500.0000", "balanceAfter": "1020.0000", "currency": "USD" } },
  { "type": "credits.granted", "data": { "orgId": "org_01", "amount": "50.0000", "balanceAfter": "1070.0000", "currency": "USD", "grantId": "grt_01" } },
  { "type": "credits.promo_expired", "data": { "orgId": "org_01", "amount": "10.0000", "balanceAfter": "1060.0000", "currency": "USD", "grantId": "grt_01" } },
  { "type": "api_key.created", "data": { "apiKeyId": "key_01", "name": "Production server", "environment": "PRODUCTION", "keyType": "SECRET", "keyPrefix": "sk_live_8p4" } },
  { "type": "api_key.revoked", "data": { "apiKeyId": "key_01", "name": "Production server", "environment": "PRODUCTION" } }
]
```

## Field reference

| Field                                            | Type   |             Nullable | Meaning                                                                                                                                                 |
| ------------------------------------------------ | ------ | -------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orgId`, `verificationId`, `grantId`, `apiKeyId` | string |      Event-dependent | Related organisation, usage, grant and key IDs.                                                                                                         |
| `amount`, `balance`, `balanceAfter`, `threshold` | string |      Event-dependent | Fixed-scale decimal currency amounts with four fractional digits. Parse with a decimal library; do not use binary floating-point for ledger arithmetic. |
| `currency`                                       | string | No for credit events | ISO 4217 currency code such as `USD`.                                                                                                                   |
| `name`                                           | string |    No for key events | Customer-visible key name.                                                                                                                              |
| `environment`                                    | string |    No for key events | `SANDBOX` or `PRODUCTION`.                                                                                                                              |
| `keyType`                                        | string |       No on creation | Public key classification, for example `SECRET` or `PUBLISHABLE`.                                                                                       |
| `keyPrefix`                                      | string |       No on creation | Non-secret prefix for identifying the key. The full secret is never delivered.                                                                          |

Use billing ledger and API-key read endpoints for authoritative current state. Financial side effects must be idempotent by envelope `id`, while reconciliation should also use the referenced verification, grant or top-up record.