> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How and why Stigg's approach works

Stigg is a **hot-path usage runtime**. Entitlement, credit, and limit checks run inline in your request path and return an allow or block decision in real time from a local cache, with p95 latency under 10ms when using the [Sidecar](/documentation/high-availability-and-scale/sidecar/architecture#benchmarks). Billing systems ingest events and reconcile what happened after the fact; Stigg decides what's allowed before a request runs. It works alongside your existing billing provider (Stripe, Zuora, Airwallex, and others) rather than replacing it.

The runtime is built on five pillars: [metering](/documentation/getting-usage-data-into-stigg/overview), real-time enforcement, [entitlements](/documentation/managing-customers-and-subscriptions/entitlements/overview), [credits](/documentation/modeling-your-pricing-in-stigg/credits/overview), and [governance](/documentation/governance/overview). It's split into two planes:

* **Data plane**: the metering pipeline, credit engine, and entitlement and governance enforcement. It ingests usage at high volume and answers every check in under 10ms.
* **Control plane**: the product catalog and provisioning, workflows, and integrations. Your pricing model lives here, so plans, add-ons, credits, and promotional grants reach the data plane without code changes when pricing evolves.

Stigg runs as one logical system across three deployment models: **Cloud API** (fully managed by Stigg), **[BYOC](/documentation/high-availability-and-scale/byoc/overview)** (the data plane runs inside your own cloud), and **BYODB** (your own database and event queue). Each gives you the same catalog, entitlements, and credits engine, with the same decision latency.

<div className="welcome-sys welcome-split not-prose">
  <div className="welcome-zone">
    <span className="welcome-zone-tab">Your cloud</span>

    <div className="welcome-zone-body">
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="window-maximize" /></span><strong>Your application</strong></div>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="cube" /></span><span><strong>SDK / Sidecar</strong><span className="welcome-muted">local cache</span></span></div>
      <div className="welcome-box"><span className="welcome-icon welcome-icon-neutral"><Icon icon="database" /></span><span><strong>Persistent cache</strong><span className="welcome-muted">optional</span></span></div>
      <div className="welcome-box"><span className="welcome-icon welcome-icon-neutral"><Icon icon="bucket" /></span><span><strong>Events bucket</strong><span className="welcome-muted">optional</span></span></div>
    </div>
  </div>

  <div className="welcome-links">
    <div className="welcome-link"><span className="welcome-wire-label">Access checks, under 10ms</span><span className="welcome-wire welcome-wire-h welcome-wire-both" /></div>
    <div className="welcome-link"><span className="welcome-wire-label">Usage events, up to 100k/sec via API</span><span className="welcome-wire welcome-wire-h" /></div>
    <div className="welcome-link"><span className="welcome-wire-label">Bulk events, up to 1M/sec via object storage</span><span className="welcome-wire welcome-wire-h" /></div>
    <div className="welcome-link"><span className="welcome-wire-label">Updates pushed in real time</span><span className="welcome-wire welcome-wire-h welcome-wire-rev" /></div>
  </div>

  <div className="welcome-zone welcome-zone-key">
    <span className="welcome-zone-tab">Stigg's cloud</span>

    <div className="welcome-zone-body">
      <span className="welcome-label">Data plane</span>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="bolt" /></span><strong>Edge CDN</strong></div>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="chart-line" /></span><strong>Metering pipeline</strong></div>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="coins" /></span><strong>Credit engine</strong></div>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="key" /></span><strong>Entitlements and governance</strong></div>
      <span className="welcome-label">Control plane</span>
      <div className="welcome-box"><span className="welcome-icon"><Icon icon="layer-group" /></span><strong>Catalog, workflows, integrations</strong></div>
    </div>
  </div>
</div>

## High throughput metering

Stigg's [metering pipeline](/documentation/getting-usage-data-into-stigg/overview) is built for high-volume, real-time usage:

* **Batching and parallel reporting.** Report up to 1,000 events per batch, from as many distributed reporters as you need, with no coordination between them.
* **Built-in idempotency.** Every usage report and credit deduction accepts an idempotency key, so retries are safe and duplicates are counted once.
* **Two reporting paths.** Synchronous calls return the updated usage and credit consumption immediately for strict enforcement. Asynchronous events are aggregated by the pipeline for high-volume streams.
* **Flexible aggregation.** [Meters](/documentation/getting-started/core-concepts#meters) turn raw events into the values your pricing uses (count, count unique, sum, and more), filtered and broken down by dimensions.
* **Durability.** Raw events are stored in their original format with [99.999999999% durability](/documentation/getting-usage-data-into-stigg/metering-scalability-and-durability), so usage can be audited and rebuilt at any point.
* **Scale beyond the cloud limits.** [BYOC](/documentation/high-availability-and-scale/byoc/overview) deploys the metering service in your own cloud for up to 1,000,000 events per second.

## Low latency entitlement checks

[Entitlement checks](/documentation/managing-customers-and-subscriptions/entitlements/overview) are designed to sit in the hot path without slowing it down, on a [high availability architecture](/documentation/high-availability-and-scale/high-availability-architecture):

* **Pre-calculated entitlements.** Stigg computes each customer's effective entitlements whenever their subscription or the catalog changes, so a check is a read, not a calculation.
* **Edge-replicated cache.** Entitlement, usage, and catalog data are served from a distributed cache replicated across regions and [accessible from anywhere](/documentation/high-availability-and-scale/accessible-from-everywhere).
* **Local caching in the SDKs.** Backend SDKs keep entitlements in an in-memory cache that's kept up to date by polling or real-time streaming updates, so most checks are answered locally with sub-millisecond latency and no network call.
* **Persistent caching and the Sidecar.** Share a cache across instances with [persistent caching](/documentation/high-availability-and-scale/persistent-caching), or run the [Sidecar](/documentation/high-availability-and-scale/sidecar/overview) next to your services.
* **Hard and soft limits.** With a [hard limit](/documentation/modeling-your-pricing-in-stigg/plans/assigning-features-plans) (the default), checks deny access once a metered feature reaches its limit. With a soft limit, access continues past the limit, for example to charge for overages or start an upsell conversation.
* **Fallback strategy.** If Stigg is unreachable, checks fall back to [values you configure](/documentation/high-availability-and-scale/local-caching-and-fallback-strategy) instead of failing your request.
* **Checks inside your own cloud.** With [BYOC](/documentation/high-availability-and-scale/byoc/overview), the data plane that answers entitlement checks runs inside your VPC, so checks never leave your network.

## Financial-grade credits

Stigg's [credit engine](/documentation/modeling-your-pricing-in-stigg/credits/credits-core-concepts) keeps balances correct under high-volume, concurrent consumption:

* **Credit pools and grants.** Each customer has a credit pool per currency, or per resource, made up of individual grants such as recurring, prepaid, and promotional credits.
* **Deterministic consumption order.** Grants are [consumed](/documentation/modeling-your-pricing-in-stigg/credits/credit-consumption-logic) by priority, then by expiration date, then by category, so expiring and promotional credits are used first.
* **Real-time balance.** Each deduction is reflected in the balance immediately, so the next check already accounts for it, even when many requests consume credits at once.
* **Hard and soft limits.** With a hard limit (the default), checks deny access once the balance can't cover the request. With a soft limit, consumption continues and the deficit is tracked as an overdraft that's settled automatically from the next grant.
* **Auditability.** Every grant, deduction, expiration, and revocation is recorded in an append-only ledger.

## Governance

[Governance](/documentation/governance/overview) extends the same real-time checks from the customer account down to the people and agents inside it:

* **Entity hierarchies.** Model your customers' org structure, such as organization, department, team, user, and AI agent, as entity types and hierarchies.
* **Budgets and limits at any level.** Distribute credits or restrict usage of metered features for any entity in the hierarchy.
* **Real-time enforcement.** Operations are [blocked the moment a limit is reached](/documentation/governance/check-and-ingest), at call time rather than on the next invoice.
* **Automatic cost attribution.** A single usage event updates balances at every level of the hierarchy, so you report usage once.
* **Hard and soft limits.** Hard limits block on breach; soft limits allow overage and trigger alerts.
* **Self-service management.** Build your own admin experience on Stigg's [governance APIs and SDK](/documentation/governance/setting-up), so your customers' admins can allocate budgets and set limits themselves.

## Usage retrieval and history

Outside the hot path, Stigg keeps usage and credit data queryable for reporting, auditing, and analysis:

* **Consumption over time.** [Query usage](/api-and-sdks/integration/backend/usage-and-billing#query-credit-usage) of metered features or credits as a time series over any date range, broken down by dimensions such as user, model, or workspace.
* **Credit ledger.** Every grant, deduction, expiration, and revocation is recorded in an append-only [ledger](/api-and-sdks/integration/backend/usage-and-billing#query-credit-ledger), in chronological order, ready for [revenue recognition](/documentation/modeling-your-pricing-in-stigg/credits/recognize-credit-revenue).
* **Governance query.** A [paginated, sortable view of each entity's budget and current usage](/documentation/governance/query), to power dashboards and admin UIs.
* **Billing sync.** Usage of metered features is synced to your billing provider, such as [Stripe](/documentation/native-integrations/billing/stripe/overview), [Zuora](/documentation/native-integrations/billing/zuora/overview), or [Airwallex](/documentation/native-integrations/billing/airwallex), for invoicing.
* **Data export.** [Export](/documentation/importing-and-exporting-data/export/overview) usage, credits, and the rest of your Stigg data to your data warehouse, database, or cloud storage.

<CardGroup cols={2}>
  <Card title="Check, act, track" icon="arrows-rotate" href="/documentation/introduction/the-problem#common-patterns-for-solving-it-check--act--track">
    See the runtime pattern behind every check.
  </Card>

  <Card title="Core concepts" icon="cubes" href="/documentation/getting-started/core-concepts">
    Learn the entities behind Stigg's pricing model.
  </Card>
</CardGroup>


## Related topics

- [What problem Stigg solves](/documentation/introduction/the-problem.md)
- [BYOC architecture](/documentation/high-availability-and-scale/byoc/architecture.md)
- [How entitlement checks work](/documentation/managing-customers-and-subscriptions/entitlements/how-entitlement-checks-work.md)
- [How overages work](/documentation/modeling-your-pricing-in-stigg/plans/overages/working-principle.md)
- [Migrate to Stigg from a legacy or in-house system](/guides/i-want-to/migrate-from-legacy-systems.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.