---
title: "QuotaStack Concepts"
description: "The core concepts behind QuotaStack — credits, metering, entitlements, reservations, subscriptions, and the cross-cutting conventions."
---

# QuotaStack Concepts

The mental models behind QuotaStack. Each concept has a full agent-readable page at the same URL + `.md`.

- [Credits](/docs/concepts/credits.md): How QuotaStack stores, grants, debits, and tracks credits using millicredits, credit blocks, and an append-only ledger.
- [Entitlement Management](/docs/concepts/entitlements.md): Entitlement management for usage-based products — check whether a customer can perform an action with sub-millisecond, cached checks on the hot path.
- [Metering](/docs/concepts/metering.md): How to define billable metrics, configure metering rules with flat/per-unit/tiered pricing, and record usage events that debit credits.
- [Reservations](/docs/concepts/reservations.md): How to hold credits during long-running operations using the reserve/commit/release lifecycle, with TTL-based auto-expiry and concurrency safety.
- [Topups and Wallets](/docs/concepts/topups-and-wallets.md): How to grant credits after payment, model wallets and credit packs, configure topup packages, and control burn order with priority.
- [Subscriptions](/docs/concepts/subscriptions.md): Optional recurring billing state management with prepaid and postpaid modes, scheduled credit grants, rollover, and contract lifecycle.
- [Payment Connectors](/docs/concepts/payment-connectors.md): Connect hosted payment gateways to QuotaStack while keeping money movement, subscription state, credits, usage, and entitlements under explicit ownership.
- [Idempotency](/docs/concepts/idempotency.md): How QuotaStack prevents duplicate operations using the Idempotency-Key header, server-side locks, and deterministic key conventions.
- [Webhooks](/docs/concepts/webhooks.md): Event delivery from QuotaStack to your application, with HMAC-SHA256 signing, retry schedule, and event catalog.
- [Customer Identification](/docs/concepts/customer-identification.md): Two identifier types and two URL forms for customers — when to use each, and how to avoid mixing them.
- [API Conventions](/docs/concepts/conventions.md): Environments, authentication, rate limits, pagination, error format, and retention — the cross-cutting details every integration needs.
- [Overage](/docs/concepts/overage.md): What happens when a customer spends past their balance — the three policies, the overage record, and how to reconcile arrears.
- [Plans & Variants](/docs/concepts/plans-and-variants.md): How a sellable plan is put together — variants, credit grants, and what retiring one actually does.
- [Plan-Variant Entitlements](/docs/concepts/plan-variant-entitlements.md): How to attach billable metrics to plan variants with type-shaped values, giving each tier different feature access, caps, and configurations.
- [Subscription Overrides](/docs/concepts/subscription-overrides.md): Give one customer a different entitlement value from the rest of their plan, without building a plan for one person.
- [Environments & the Shared Catalog](/docs/concepts/environments.md): What sandbox and live keep apart, what they share, and why editing a plan in sandbox can change a live customer's bill.
- [Audit Log](/docs/concepts/audit-log.md): Every mutation, who did it, and what the record looked like before and after — plus the dashboard stats endpoint.