> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lavendly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reserve credits

> Hold credits before spending. Returns a token to commit or refund.

The reserve / commit / refund pattern keeps the ledger honest even when
generation can fail mid-flight: you reserve before kicking off work,
commit on success, refund on failure.

### Body

<ParamField body="amount" type="number" required>Credits to hold.</ParamField>
<ParamField body="label" type="string">Human-readable purpose (shown in `transactions`).</ParamField>
<ParamField body="meta" type="object">Free-form structured metadata.</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.lavendly.ai/v1/ledger/reserve \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer $LAVENDLY_API_KEY' \
    -d '{ "amount": 10, "label": "video / 5s" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "token":     "rsv_lq3z9m_8fa1c0",
    "balance":   742,
    "available": 714
  }
  ```
</ResponseExample>

Returns `402 insufficient_credits` with `{ needed, have }` if the reserve
would drive `available` below zero.