--- title: "The 60-Second Tour" description: "QuotaStack's core concepts in 60 seconds — one mental model at a time." --- # The 60-Second Tour QuotaStack's core concepts, one mental model at a time. The interactive tour is a slideshow; this is the same content as text. Each concept links to its full agent-readable page. ## 01. 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. How QuotaStack stores, grants, debits, and tracks credits using millicredits, credit blocks, and an append-only ledger. → [Read the concept](/docs/concepts/credits.md) ## 02. Entitlement 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. Entitlement management for usage-based products — check whether a customer can perform an action with sub-millisecond, cached checks on the hot path. → [Read the concept](/docs/concepts/entitlements.md) ## 03. Metering > 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. How to define billable metrics, configure metering rules with flat/per-unit/tiered pricing, and record usage events that debit credits. → [Read the concept](/docs/concepts/metering.md) ## 04. Reservations > 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. How to hold credits during long-running operations using the reserve/commit/release lifecycle, with TTL-based auto-expiry and concurrency safety. → [Read the concept](/docs/concepts/reservations.md) ## 05. Topups 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. How to grant credits after payment, model wallets and credit packs, configure topup packages, and control burn order with priority. → [Read the concept](/docs/concepts/topups-and-wallets.md) ## 06. Subscriptions > 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. Optional recurring billing state management with prepaid and postpaid modes, scheduled credit grants, rollover, and contract lifecycle. → [Read the concept](/docs/concepts/subscriptions.md) ## 07. Payment 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. Connect hosted payment gateways to QuotaStack while keeping money movement, subscription state, credits, usage, and entitlements under explicit ownership. → [Read the concept](/docs/concepts/payment-connectors.md) ## 08. Idempotency > 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. How QuotaStack prevents duplicate operations using the Idempotency-Key header, server-side locks, and deterministic key conventions. → [Read the concept](/docs/concepts/idempotency.md) ## 09. Webhooks > 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. Event delivery from QuotaStack to your application, with HMAC-SHA256 signing, retry schedule, and event catalog. → [Read the concept](/docs/concepts/webhooks.md) ## 10. Customer 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. Two identifier types and two URL forms for customers — when to use each, and how to avoid mixing them. → [Read the concept](/docs/concepts/customer-identification.md) ## 11. 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. Environments, authentication, rate limits, pagination, error format, and retention — the cross-cutting details every integration needs. → [Read the concept](/docs/concepts/conventions.md) ## 12. Overage > 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. What happens when a customer spends past their balance — the three policies, the overage record, and how to reconcile arrears. → [Read the concept](/docs/concepts/overage.md) ## 13. 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. How a sellable plan is put together — variants, credit grants, and what retiring one actually does. → [Read the concept](/docs/concepts/plans-and-variants.md) ## 14. Plan-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. How to attach billable metrics to plan variants with type-shaped values, giving each tier different feature access, caps, and configurations. → [Read the concept](/docs/concepts/plan-variant-entitlements.md) ## 15. Subscription 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. Give one customer a different entitlement value from the rest of their plan, without building a plan for one person. → [Read the concept](/docs/concepts/subscription-overrides.md) ## 16. Environments & 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. What sandbox and live keep apart, what they share, and why editing a plan in sandbox can change a live customer's bill. → [Read the concept](/docs/concepts/environments.md) ## 17. Audit 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. Every mutation, who did it, and what the record looked like before and after — plus the dashboard stats endpoint. → [Read the concept](/docs/concepts/audit-log.md)