Reserve and settle

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

1. Reserve. Call the entitlement 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.

​

Example

A customer has a 500-credit grant.

​

Availability

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

​

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. Reserve the most the operation can cost to avoid this.

​

Ledger

Every step is recorded in the customer’s credit ledger: 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:

​

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, pass resourceId on the check, and the same resourceId on the release.