> ## 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

> Hold credits before an operation runs, then settle its real cost when it finishes, so concurrent requests can never overdraw a balance.

A reservation holds credits for an operation before it runs. When the operation finishes, you settle the reservation with its real cost: Stigg consumes that amount and returns the rest to the customer's credit balance.

Use reserve and settle when:

* The cost is known only after the operation finishes, such as an LLM call or an agent task.
* The operation runs long, and the credits must still be there when it ends.
* Many requests draw on the same balance at once, and together they must never spend more than it holds.

## Why reserve

In the [check, act, track](https://docs.stigg.io/documentation/introduction/the-problem.md#common-patterns-for-solving-it-check--act--track) pattern, the check confirms the balance and the report deducts the usage afterward. Requests that check in between see the same balance. If ten requests each check a 100-credit balance for 50 credits at the same moment, all ten pass, and together they spend 500.

A reservation decides the check and holds the credits in one atomic step, so held credits are no longer available to any other request. For example, 20 simultaneous reservations of 75 credits against a 500-credit balance grant exactly 6 (450 credits held) and deny the other 14. The same holds when releases and new reservations race each other.

## How it works

```mermaid theme={null}
sequenceDiagram
    participant App as Your application
    participant Stigg

    App->>Stigg: Check with reserveAmount=100, reservationId=job-123
    alt Granted
        Stigg-->>App: isGranted=true, reservation (100 held)
        App->>App: Run the operation
        App->>Stigg: Release job-123 with consumedAmount=40
        Stigg-->>App: 40 consumed, 60 returned to the balance
    else Denied
        Stigg-->>App: isGranted=false, InsufficientCredits (nothing held)
    end
```

1. **Reserve.** Call the [entitlement check](https://docs.stigg.io/api-and-sdks/api-reference/rest/entitlements-check) for a credit type with `reserveAmount` and a `reservationId` that you choose. If the balance covers the amount, Stigg holds it and returns the `reservation`. If not, the check is denied with `InsufficientCredits` and nothing is held.
2. **Run the operation.** The held credits are yours until you settle the reservation or it expires.
3. **Settle.** Call `POST /api/v1/credits/reservations/{reservationId}/release` with the `consumedAmount`. Stigg charges that amount to the grants that backed the reservation and returns the rest to the balance.

> [!NOTE]
>
> The settle endpoint, `release`, consumes the amount you pass and returns the rest in one call. If the operation fails, release with `consumedAmount: 0` to return everything.

### Example

A customer has a 500-credit grant.

| Step | Used | Reserved | Available |
| - | - | - | - |
| Start | 0 | 0 | 500 |
| Reserve 100 as `job-1` | 0 | 100 | 400 |
| Reserve 50 as `job-2` | 0 | 150 | 350 |
| Release `job-1` with `consumedAmount: 40` | 40 | 50 | 410 |

## Availability

Reserve and settle is available through the REST API and these REST SDK versions or later:

| SDK | Version |
| - | - |
| [TypeScript](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/typescript) | `0.1.0-beta.62` |
| [Python](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/python) | `0.1.0-beta.53` |
| [Go](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/go) | `0.1.0-beta.54` |
| [Java](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/java) | `0.1.0-beta.54` |
| [Ruby](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/ruby) | `0.1.0-beta.59` |
| [C#](https://docs.stigg.io/api-and-sdks/references/sdk/backend/rest/csharp) | `0.11.0` |

## Expiry

A reservation holds its credits for one hour by default. To change that, pass either:

* `reservationTtlSeconds`, from 1 to 86400 seconds.
* `reservationExpiresAt`, an ISO 8601 time at most 24 hours ahead.

When a reservation expires before you release it, all its credits return to the balance and no usage is recorded. Set the expiry to cover the longest your operation can run.

## Retries

The `reservationId` makes both steps safe to retry:

* **Reserve.** Retrying with the same ID returns the same result and holds the credits once. Reusing an ID with different parameters is rejected as a conflict.
* **Release.** Retrying a release with the same ID applies it once.

Use an ID that identifies the operation, such as a job or request ID, so a retry from any server maps to the same reservation.

## Settling more than you reserved

If the operation used more than it reserved, the reserved amount is charged to the grants that backed the reservation, and the extra is consumed like any other usage. The **Reservation released** ledger event then shows a negative amount. If the balance cannot cover the extra, it can go [negative](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/credits-core-concepts.md#negative-credit-balance). Reserve the most the operation can cost to avoid this.

## Ledger

Every step is recorded in the customer's [credit ledger](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/credits-core-concepts.md#credit-ledger):

| Event | Amount | When | In the API |
| - | - | - | - |
| **Credits reserved** | Minus the held amount | A reservation is granted | `CREDITS_RESERVED` |
| **Reservation released** | The net change: the held amount minus the consumed amount | A reservation is released. Expand it to see its parts. | `CREDITS_RESERVATION_RELEASED` |
| ↳ **Hold returned** | Plus the held amount | The hold is lifted | `holdReturnedAmount` |
| ↳ **Usage** | Minus the consumed amount | The consumed amount is charged, one entry per grant | `breakdown` |

A reservation that expires before it is released is recorded as `CREDITS_RESERVATION_EXPIRED`.

In the Stigg app, click a reservation ID in the ledger to show only that reservation's events, and use the **Event type** filter to show one or more kinds of event. The REST ledger endpoint, `GET /api/v1/credits/ledger`, takes the same filters as `reservationId` and `eventType`. The usage overview on the customer's **Credits** tab shows reserved credits next to used credits.

To label a reservation, pass `reservationMetadata` on the check, a JSON-encoded object of string values. It is returned as `metadata` on the reservation's ledger events.

## Balance fields

A check on a credit type returns these fields:

| Field | Description |
| - | - |
| `currentUsage` | Credits consumed plus credits held by open reservations. `usageLimit - currentUsage` is the available balance. |
| `reserved` | Credits held by open reservations. Already included in `currentUsage`. |
| `reservedOnExpiredGrants` | Credits held on grants that expired during the hold. See [Grants that expire during a hold](#grants-that-expire-during-a-hold). |
| `reservation` | The reservation this request created: `id`, `amount`, `status` (`ACTIVE` or `RELEASED`) and `expiresAt`. Empty when the request did not reserve or was denied. |

## Edge cases

### Grants that expire during a hold

A grant can expire while a reservation holds some of its credits. Those credits stay held, so the operation can still settle. They move from `reserved` to `reservedOnExpiredGrants`, and they are no longer part of `currentUsage` or the balance, so do not subtract them from it.

When you release the reservation, the consumed amount, up to the reserved amount, is charged to the expired grant. The grant's expiry therefore never pushes the balance into overdraft.

### Resource-specific pools

To reserve from a [resource-specific pool](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/resource-specific-pools.md), pass `resourceId` on the check, and the same `resourceId` on the release.


## Related topics

- [Reserve and settle credits](https://docs.stigg.io/guides/i-want-to/reserve-and-settle-credits.md)
- [Credit consumption logic](https://docs.stigg.io/documentation/modeling-your-pricing-in-stigg/credits/credit-consumption-logic.md)


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