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

# Reserve and settle credits

> Hold credits before an operation runs, then consume what it actually used and return the rest.

This guide reserves credits for an operation whose cost you know only after it finishes, such as an LLM call or an agent task, and then settles the reservation with the real cost. See [Reserve and settle](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/reserve-and-settle.md) for how reservations work.

The examples use the REST API and the [Typescript](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/typescript) and [Python](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/python) REST SDKs.

**Before you start:**

* A Stigg server API key.
* A credit type `currency-ai-credits` and a customer `customer-demo-01` with a credit grant. See [Set up credits](https://docs.stigg.io/guides/i-want-to/set-up-credits.md).
* A client, if you use an SDK. Reservations need TypeScript SDK `0.1.0-beta.62` or Python SDK `0.1.0-beta.53` or later. See [Availability](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/reserve-and-settle.md#availability) for other languages.

```typescript Typescript theme={null}
import Stigg from '@stigg/typescript';

const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'] });
```

```python Python theme={null}
import os
from stigg import Stigg

client = Stigg(api_key=os.environ.get("STIGG_API_KEY"))
```

**1. Reserve credits**

Call the [entitlement check](https://docs.stigg.io/api-and-sdks/api-reference/rest/entitlements-check) with `reserveAmount`, the most the operation can cost, and a `reservationId` that identifies the operation. Stigg checks the balance and holds the credits in one step.

```bash cURL theme={null}
curl "https://api.stigg.io/api/v1/customers/customer-demo-01/entitlements/check?currencyId=currency-ai-credits&reserveAmount=100&reservationId=job-123" \
  -H "X-API-KEY: $STIGG_API_KEY"
```

```typescript Typescript theme={null}
const { data } = await client.v1.customers.checkEntitlement('customer-demo-01', {
  currencyId: 'currency-ai-credits',
  reserveAmount: 100,
  reservationId: 'job-123',
});
```

```python Python theme={null}
response = client.v1.customers.check_entitlement(
    id="customer-demo-01",
    currency_id="currency-ai-credits",
    reserve_amount=100,
    reservation_id="job-123",
)
```

When the balance covers the amount, the response grants access and includes the reservation. `currentUsage` now includes the 100 held credits. The response below is abbreviated.

```json theme={null}
{
  "data": {
    "isGranted": true,
    "type": "CREDIT",
    "accessDeniedReason": null,
    "usageLimit": 500,
    "currentUsage": 100,
    "reserved": 100,
    "reservation": {
      "id": "job-123",
      "amount": 100,
      "status": "ACTIVE",
      "expiresAt": "2026-10-20T13:59:27.842Z"
    }
  }
}
```

The reservation expires after one hour by default. If the operation can take longer, pass `reservationTtlSeconds` (up to 86400) or `reservationExpiresAt` (up to 24 hours ahead).

**2. Handle denied access**

When the balance does not cover the amount, `isGranted` is `false`, `accessDeniedReason` is `InsufficientCredits`, and nothing is held. Block the operation or offer a [top-up](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/self-service-top-up.md).

```typescript Typescript theme={null}
if (!data.isGranted) {
  return showTopUp(data.accessDeniedReason);
}
```

```python Python theme={null}
if not response.data.is_granted:
    return show_top_up(response.data.access_denied_reason)
```

**3. Run the operation and settle**

Run the operation, calculate the credits it used, and release the reservation with that amount. The release endpoint settles the reservation: Stigg consumes the amount and returns the rest to the customer's credit balance. If the operation fails, release with `consumedAmount: 0`.

```bash cURL theme={null}
curl -X POST "https://api.stigg.io/api/v1/credits/reservations/job-123/release" \
  -H "X-API-KEY: $STIGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "customer-demo-01", "currencyId": "currency-ai-credits", "consumedAmount": 40 }'
```

```typescript Typescript theme={null}
const released = await client.v1.credits.reservations.release('job-123', {
  customerId: 'customer-demo-01',
  currencyId: 'currency-ai-credits',
  consumedAmount: 40,
});
```

```python Python theme={null}
released = client.v1.credits.reservations.release(
    reservation_id="job-123",
    customer_id="customer-demo-01",
    currency_id="currency-ai-credits",
    consumed_amount=40,
)
```

The response returns the released reservation and the updated balance:

```json theme={null}
{
  "data": {
    "reservation": {
      "id": "job-123",
      "amount": 100,
      "status": "RELEASED",
      "expiresAt": "2026-10-20T13:59:27.842Z",
      "consumedAmount": 40
    },
    "credit": {
      "currencyId": "currency-ai-credits",
      "currentUsage": 40,
      "usageLimit": 500,
      "timestamp": "2026-10-20T13:00:12.000Z",
      "usagePeriodEnd": "2026-11-20T12:57:15.000Z"
    }
  }
}
```

If a request fails, retry it with the same `reservationId`. Both the reservation and the release are applied once.

**4. Review the ledger**

In the Stigg app, go to **Customers → customer-demo-01 → Credits** and open the **Ledger** tab. The reservation appears as **Credits reserved** (-100), followed by **Reservation released** (+60). Expand the release to see the **Hold returned** (+100) and **Usage** (-40) entries, or click `job-123` to show only this reservation's events.


## Related topics

- [Reserve and settle](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/reserve-and-settle.md)
- [Deduct credits directly](https://docs.stigg.io/guides/i-want-to/deduct-credits-directly.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.