Credit Consumption

Understand how credits are consumed against invoices and usage

Credits are consumed when invoices are produced and, for gated usage, in realtime as work happens. This guide explains the consumption mechanics and how to track credit usage.

---

How Credits Are Consumed

Monetary Credits

Monetary credits are applied while the invoice is priced:

1. Invoice is generated with line items
2. System calculates the total for each line
3. Available credits are applied in consumption order
4. Remaining balance is charged to a payment method

Invoice Total:     $500.00
Credits Applied:  -$300.00
Amount Due:        $200.00

Unit Credits

Unit credits cover metered usage. They are drawn in two places:

• At invoice time, against the metered lines the grant is allowed to pay for
• In realtime, when a metric has a credit consumption configuration and the grant funds the gate — see The Realtime Gate

API Calls Made:    15,000
Credits Available: 10,000
Credits Used:     -10,000
Billable Usage:     5,000

Usage sent to POST /events is metered but never draws credit. Only the gate endpoints charge credit for usage.

---

Consumption Order

When several grants can pay for the same charge, they are drawn in this order:

1. Priority — lowest number first
2. Expiring grants before non-expiring ones
3. Earliest expiry first
4. Oldest grant first

Priority is a dashboard setting on a subscription’s credit allocation, not an API field. Grants created manually or through the API are priority 0, so for those the order comes down to expiry and then age.

Example

Grant A: $200, priority 10, expires 2026-06-30
Grant B: $150, priority 5,  expires 2026-12-31
Grant C: $100, priority 10, expires 2026-03-31

Invoice: $350

Consumption order:
1. Grant B: $150 (lowest priority number)
2. Grant C: $100 (same priority as A, but expires sooner)
3. Grant A: $100 (remainder)

Result: B and C fully consumed, A partially consumed

A grant is only a candidate if it is eligible for the charge in the first place: it must belong to the customer, be within its validity window, and pass the product and price filters on the line being paid. See Credit Grants.

---

Invoice-Time Consumption

Credits are applied automatically as part of pricing an invoice; there is no opt-in and no separate “apply credits” call.

While the invoice is a draft, each draw is written to the credit ledger as a pending entry, and re-pricing the draft re-synchronises those entries. When the invoice is finalized, the pending entries become final consumption. Voiding a draft removes them again, returning the credits to the grants they came from.

Once an invoice closes, its consumption is frozen against that billing period. Settlement that arrives after the close is carried forward into the open period rather than reopening the closed one.

Ledger Entry Types

Every movement on a credit ledger records what caused it:

Type	Description
allocation_grant	Credits provisioned by a subscription’s credit allocation
manual_credit	Credits granted manually or through the API
manual_debit	An operator-initiated deduction
invoice_consumption	Credits applied to an invoice, pending while it is a draft
immediate_consumption	A direct realtime draw
capture	A realtime reservation settled against the ledger
allocation_rollover_adjustment	Rollover of an allocation into a new period
credit_expiry	Credits removed at expiry

Credit activity is visible per customer and per subscription in the dashboard.

---

The Realtime Gate

For work you want to authorise before doing it — an expensive inference run, a long job — the gate is a two-phase flow: reserve on POST /credits/check, settle on POST /credits/track.

Neither request carries a credit amount. You describe the work as the events it will produce, and the response prices it per metric.

1. Reserve

   POST /credits/check with reserve opens a hold and returns a reservation_id. An Idempotency-Key is required whenever reserve is set.

2. Do the work

   The hold expires after 15 minutes unless ttl_seconds asks for longer, up to 4 hours. Each accepted settle slides the expiry forward.

3. Settle

   POST /credits/track with the reservation_id, the events that actually happened, and close to say whether this is the final call.

Reserving

Send reserve: {} to hold exactly what the sampled events price to, or reserve: {"max_quantity": "..."} with an event_name for an open-ended ceiling in metric units.

curl -X POST https://api.alguna.io/credits/check \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run_88f_reserve" \
  -d '{
    "account": "cust_abc123",
    "reserve": {},
    "events": [
      {
        "event_name": "agent_step",
        "unique_id": "run_88f_step1",
        "properties": { "tokens": 1200 }
      }
    ]
  }'

Response:

{
  "allowed": true,
  "at_zero_action": "stop",
  "reservation_id": "crt_abc123",
  "expires_at": "2026-04-01T10:15:00Z",
  "charges": [
    {
      "metric_id": "mtr_tokens",
      "quantity": "1200",
      "credits": "12",
      "covered": "12",
      "overflow": "0",
      "uncovered_quantity": "0",
      "ledger_id": "crl_abc"
    }
  ],
  "balances": [
    {
      "metric_ids": ["mtr_tokens"],
      "credit_type": "units",
      "available": "988",
      "filtered": true,
      "ledger_id": "crl_abc"
    }
  ],
  "totals": {
    "used": "12",
    "covered": "12",
    "overflow": "0",
    "uncovered_metric_quantity": "0"
  }
}

Omit reserve for a cost-free quote: nothing is recorded, no credit moves, and charges still tells you what the work would price to.

Insufficient credit is not an error. The call returns 200 with allowed: false, and at_zero_action says what to do about it: stop for a hard deny, overflow to fall through to metered billing.

Settling

curl -X POST https://api.alguna.io/credits/track \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_id": "crt_abc123",
    "close": true,
    "events": [
      {
        "event_name": "agent_step",
        "unique_id": "run_88f_step1",
        "properties": { "tokens": 1180 }
      }
    ]
  }'

Response:

{
  "allowed": true,
  "reservation_id": "crt_abc123",
  "reservation_open": false,
  "reservation_remaining": "0",
  "events_accepted": 1,
  "events_priced": 1,
  "envelope_exceeded": false,
  "charges": [
    {
      "metric_id": "mtr_tokens",
      "quantity": "1180",
      "credits": "11.8",
      "covered": "11.8",
      "overflow": "0",
      "uncovered_quantity": "0",
      "ledger_id": "crl_abc"
    }
  ],
  "balances": [
    {
      "metric_ids": ["mtr_tokens"],
      "credit_type": "units",
      "available": "988.2",
      "filtered": false,
      "ledger_id": "crl_abc"
    }
  ],
  "totals": {
    "used": "11.8",
    "covered": "11.8",
    "overflow": "0",
    "uncovered_metric_quantity": "0"
  }
}

close is required whenever reservation_id is set — there is no default. Send close: false to report progress and keep the hold open, then close: true on the final call.

Events sent to /credits/track are both metered and charged, so do not also send them to POST /events.

Drawing Without a Reservation

Send account instead of reservation_id to charge the account’s current credit directly, with no hold in between. close is not valid on a direct draw.

curl -X POST https://api.alguna.io/credits/track \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "cust_abc123",
    "events": [
      {
        "event_name": "agent_step",
        "unique_id": "run_91a_step1",
        "properties": { "tokens": 400 }
      }
    ]
  }'

Reading a Reservation

curl https://api.alguna.io/credits/reservations/crt_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

The response reports the hold’s status, what it still has remaining, the metrics it covers, and every close already committed against it. It is a read: it cannot settle anything. Use it when a client has lost its Idempotency-Key and needs to discover what already landed instead of resending and burning twice.

Releasing Abandoned Work

If the work never happens, close the reservation with no events. Nothing is charged and the whole hold is released.

curl -X POST https://api.alguna.io/credits/track \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_id": "crt_abc123",
    "close": true,
    "events": []
  }'

An abandoned hold that is never closed expires on its own.

---

Webhooks

Event	Description
account.credits.granted	Credits granted to a customer
account.credits.balance_depleted	Credit balance reached zero

Payload shapes are on the Credits Overview.

---

Next Steps

Wallets

Learn about prepaid wallets.

Credit Grants

Create and manage grants.