Credits and Sold-Seat Usage

Learn exactly when booked-seat credits are granted, spent, replayed, refunded, and allowed to go negative.

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.

credit-lifecycle.txttext

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.

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, booking idempotency, and reports.