The 60-second tour
QuotaStack in 17 mental models
No API, no code — just the core ideas, one at a time. Each model links to the full concept when you're ready to go deeper.
Credits
Think of credits like layered deposits in a bank account. Each deposit (credit block) has its own terms — when it expires, whether it burns first, where it came from. The balance is just the sum of what's left in each deposit.
Read the full conceptEntitlement Management
An entitlement check is the bouncer at the door. Before your app starts an expensive operation, it asks QuotaStack "can this customer afford this?" — answer comes back in milliseconds, cached and ready.
Read the full conceptMetering
Metering is the bridge between "something happened" and "credits got spent". You define the price list (metering rules), report what happened (usage events), and QuotaStack does the math.
Read the full conceptReservations
Think of reservations like putting items in a hotel safe. The credits are held, not spent. When you're done: commit (you really used them), release (you didn't), or let the TTL auto-release so nothing leaks.
Read the full conceptTopups and Wallets
Wallets and credit packs are stacked fuel tanks with different rules. The system drains the tank that expires soonest first, saving the customer's paid wallet for last. You can confirm payment and call the manual grant API, or let a payment connector apply a mapped package after verified provider success.
Read the full conceptSubscriptions
Subscriptions are state machines for recurring billing. QuotaStack tracks the cycle and credits. With manual prepaid billing you collect payment and call renew; with a connector the provider collects and QuotaStack advances only after its verified event. Postpaid stays tenant-invoiced.
Read the full conceptPayment Connectors
A payment connector is a verified bridge between a cashier and your billing ledger. The selected provider owns money movement and recurring collection; QuotaStack owns product mapping, subscription state, credits, metering, and entitlements.
Read the full conceptIdempotency
Every POST/PATCH request includes a receipt number (the Idempotency-Key). Retry with the same key and QuotaStack returns the cached response, not a double-charge. This is how your system survives network failures and webhook re-deliveries.
Read the full conceptWebhooks
Webhooks are QuotaStack's postal service — they tell your app "something happened." Every delivery is signed (you know it's real), retried 7 times if you're offline, and ordered per-customer.
Read the full conceptCustomer Identification
Customers have two names: the one you already use (external_customer_id) and the one QuotaStack generates (customer_id UUID). Use either. Most apps only ever need the one they already have.
API Conventions
Cross-cutting rules every endpoint inherits. API key prefix picks the environment. Pagination, errors, and rate limits all follow a single standard shape — learn it once, apply it everywhere.
Read the full conceptOverage
Overage is a tab at the bar. When the customer's prepaid card runs dry, your policy decides what happens: refuse the round (block), or pour it and write the difference on the tab (allow). The tab is a separate record — the card never goes negative.
Plans & Variants
A plan is the name on the box; a variant is one way to buy what is inside. Customers never subscribe to a plan — they subscribe to a variant, and every commercial term they get (cycle, trial, credits, entitlements) hangs off that variant.
Read the full conceptPlan-Variant Entitlements
Think of plan-variant entitlements as the feature matrix row for a pricing tier. Each cell says what that tier gets for a specific metric — on/off, a cap, a config blob, or credit-metered access.
Read the full conceptSubscription Overrides
An override is a sticky note on one customer's contract. The plan still says 10 seats; the note says 50 for this account only. Everything else on the contract is unchanged, and when the note comes off, the plan's number applies again.
Read the full conceptEnvironments & the Shared Catalog
Think of it as two warehouses that share one product catalogue. Sandbox and live each hold their own stock, customers, and paperwork — but there is a single price list on the wall, and both warehouses read it. Reprice an item while playing in sandbox and the live warehouse charges the new price.
Read the full conceptAudit Log
The audit log is the ship's logbook. Every change is written down as it happens, with who made it and what the entry looked like before and after. Pages are never torn out — the log is append-only.
Read the full conceptThat's the whole model. Ready to build?
Start the quickstart →