---
title: "Credits model"
description: "Learn exactly when booked-seat credits are granted, spent, replayed, refunded, and allowed to go negative."
---

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

# Credits model

SeatLayer keeps one append-only credit ledger per organization. The current
balance is the fast read; ledger deltas are the reconstructable history.

## Metering boundary

A credit is spent only when inventory is newly booked. The charge is recorded
asynchronously with a stable occurrence id, so at-least-once queue delivery
cannot double-debit the wallet.

```text title="credit-lifecycle.txt"
free -> held        no credit
held -> released    no credit
free -> blocked     no credit
blocked -> free     no credit
held/free -> booked debit newly sold guest quantity
booked -> free      credit is not returned
free -> booked again no second debit for already-metered inventory
```

An idempotent retry with the same booking reference is not a new sale.

## Wallet lifetime

Purchased credits remain in the organization wallet until used; they do not
expire at a month or contract boundary. If no inventory is newly booked, no
sold-seat credits are consumed. Any future promotional grant must state its own
eligibility and expiry terms and is not part of the standard pricing contract.

## Ledger entry kinds

| Kind | Meaning |
|---|---|
| `spend` | Newly sold guest capacity |
| `free_grant` | The 100-credit monthly allowance, granted once per calendar month |
| `purchase` | Verified prepaid-pack purchase |
| `refund` | Explicit credit reversal |
| `admin_adjust` | Controlled account correction |
| `subscription_grant` | Legacy grant retained for historical ledgers |

Spend entries include event id and guest quantity. Purchase entries include the
Stripe reference. Each entry snapshots `balanceAfter`.

## Negative balances

A sale that has already committed is not rolled back because of billing. The
wallet may become negative after a burst of bookings.

Creating a new live event requires a positive balance. Existing events continue
selling. Test-mode event creation and booking do not consume credits.

> **Monitor before on-sale**
>
> A low balance does not act as a strict per-booking circuit breaker. Alert and
> top up before a large on-sale rather than relying on an automatic stop.

## Cancellation and a later ordinary sale

For Platform/SDK events, `unbook` changes event inventory and can reduce current
booked value in inventory reports, but it does not refund the credit. Refund
customer money in your payment system. Managed Ticketing events instead use
the coordinated SeatLayer Order/refund workflow; generic `unbook` is not
available for them.

The same inventory can later be sold through a new ordinary booking without
another credit because metering remembers that guest unit has already left
free inventory through a successful sale. This is not a first-class resale
listing: SeatLayer does not model a seller, listing ownership, resale price,
buyer-to-buyer transfer, or payout workflow in the current Platform SDK.

## Billing API boundary

Billing endpoints are dashboard-session authenticated rather than general
secret-key Server API endpoints:

| Route | Purpose |
|---|---|
| `GET /v1/billing` | Balance, sold count, and recent ledger |
| `GET /v1/billing/packs` | Current server-authoritative pack catalog |
| `POST /v1/billing/checkout` | Admin-only hosted purchase for a `packId` |
| `GET /v1/billing/purchases/:stripeRef/invoice-url` | Org-scoped hosted invoice |

Do not expose internal development adjustment tools as a production
integration.

## Reconciliation checklist

- [ ] Count guest quantity for groups, GA, booths, and variable-occupancy tables.
- [ ] Keep booking references stable across retries.
- [ ] Separate SeatLayer credit spend from ticket money and payment settlement.
- [ ] Expect cancellation to leave the original credit spent.
- [ ] Group financial reporting by currency and source.
- [ ] Store event and workspace ids with host tenant records.
- [ ] Monitor low and negative balance before provisioning the next live event.

See [pricing](/billing/pricing),
[booking idempotency](/server-api/idempotency-and-conflicts), and
[reports](/server-api/reports).

Source: https://docs.seatlayer.io/billing/credits/index.mdx