> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.singularityapi.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.singularityapi.dev/_mcp/server.

# Receipts & Billing

## Receipts

Every response — including error responses after admission, and streamed responses — carries two headers:

* `x-singularity-request-id`
* `x-singularity-receipt-id`

Fetch the receipt any time with `GET /v1/receipts/{id}`. There's no SDK helper for this endpoint — call it directly.

**`cURL`**

```bash title="cURL"
curl https://api.singularityapi.dev/v1/receipts/RECEIPT_ID \
  -H "Authorization: Bearer $SINGULARITY_API_KEY"
```

**`Python`**

```python title="Python"
import httpx

api_key = "YOUR_API_KEY"
receipt = httpx.get(
    "https://api.singularityapi.dev/v1/receipts/RECEIPT_ID",
    headers={"Authorization": f"Bearer {api_key}"},
).json()
```

**`JavaScript`**

```javascript title="JavaScript"
const apiKey = "YOUR_API_KEY";
const receipt = await fetch(
  "https://api.singularityapi.dev/v1/receipts/RECEIPT_ID",
  { headers: { Authorization: `Bearer ${apiKey}` } },
).then((r) => r.json());
```

A full receipt looks like this:

```json
{
  "id": "rcpt_...", "object": "route_receipt", "request_id": "req_...",
  "requested_model": "deepseek-v4-flash", "served_model": "deepseek-v4-flash",
  "surface": "chat_completions", "requested_contract": null, "contract_passed": false,
  "state": "settled", "fallbacks_attempted": 0, "attempts_count": 1,
  "request_transformed": true, "transformed_fields": ["model", "max_tokens"],
  "usage": {"input_tokens": 123, "output_tokens": 45, "estimated": false},
  "latency_ms": 812, "total_cost_usd": "0.000123456789",
  "created_at": "2026-08-03T00:00:00.000000Z", "terminal_at": "2026-08-03T00:00:01.000000Z"
}
```

### Field glossary

* `state` — the request's lifecycle state; `settled` once billing is final.
* `served_model` vs `requested_model` — what actually ran the request vs what you asked for. These differ on [contract](/platform/contracts) calls.
* `transformed_fields` — which fields in your request the gateway modified or injected, such as an omitted output-limit field.
* `usage.estimated` — `true` if token counts are estimated rather than exact.
* `total_cost_usd` — the exact charge, as a 12-decimal string.
* `contract` — present only on contract calls: `{"slug": "...", "revision": 3}`.

> **Note**
>
> `usage` and `total_cost_usd` are `null` until the request reaches a terminal state.

## Credits

Credits are prepaid. Buy them in the dashboard at `https://app.singularityapi.dev` via Stripe Checkout.

* New accounts start with a \$0.00 balance — add credit in the dashboard to get started.
* **Deposit-match promotion**: purchases are matched 100% with promotional credit, capped at \$1,000 lifetime per account.
* Promotional credit is spent before paid credit, and can expire.

## Reserve-then-settle

Each request reserves its maximum possible cost up front — computed from the model's list price and the request's token bounds — then settles to the exact amount at completion. The receipt's `total_cost_usd` reflects the final, settled charge.

If you don't have enough credit to cover the reservation, the request fails with 402 `insufficient_credit`. See [Errors & Rate Limits](/api/errors-rate-limits) for the full error envelope.

> **Note**
>
> A price change never affects an in-flight or already-settled request.