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.
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.
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.
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.
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 handle payment; QuotaStack grants the credits.
Subscriptions are state machines for recurring billing. QuotaStack tracks the cycle and credits; you handle the payment. Prepaid: you drive renewal. Postpaid: QuotaStack auto-advances and sends you a usage summary.
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.
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.
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.
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 concept