Reserve and settle credits

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 for how reservations work. The examples use the REST API and the Typescript and 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.
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 for other languages.

import Stigg from '@stigg/typescript';

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

import os
from stigg import Stigg

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

Reserve credits

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

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"

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

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.

{
  "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).

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.

if (!data.isGranted) {
  return showTopUp(data.accessDeniedReason);
}

if not response.data.is_granted:
    return show_top_up(response.data.access_denied_reason)

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.

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

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

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:

{
  "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.

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.

Quick start

Credits

AI agents

Entitlements and access enforcement

Pricing and packaging

Subscriptions and billing

Migration