Core concepts

​

Credit pool

A credit pool is a customer’s live balance of a specific credit currency. The pool is funded by grants or top-ups and reduced by metered usage in real time, with every change recorded in an append-only ledger for audit, analytics, billing sync, and revenue recognition. The pool is made up of credit blocks (also called a “grant” or “allocation”), each of which represents a separate deposit of credits into the balance. These blocks can come from different sources such as recurring plan allocations, prepaid packages, promotional credits, or manual adjustments. Each block carries its own rules and metadata, for example:

• Amount: the number of credits in the block (e.g., 5,000 credits).
• Creation date: when the grant has been created.
• Effective date: when the credits become usable.
• Expiration date: when the credits expire if unused.
• Category: whether the credits are paid or promotional.
• Cost basis: the effective price per credit, used for revenue recognition.
• Priority: determines which block is consumed first when multiple are available.
• Status: the state of the block (available, expired, revoked).

The pool reflects the current balance at any point in time and supports:

• Recurring credits included in plans (e.g. annual, monthly, daily, etc.).
• Prepaid packages with fixed amounts.
• Top-ups (manual or automatic).
• Promotional credits granted for adoption.
• Manual adjustments applied by an admin.

When usage is reported, the corresponding credit cost is deducted in real time, decreasing the pool balance and updating the relevant grant(s).

​

Credit ledger

The credit ledger is an append-only, chronological record of every state change affecting credits. It provides transparency for customers and Stigg app users, and supports forensic audits, revenue recognition, and reconciliation with billing. Every change to the credit pool is captured in the ledger, including:

• Credit grants: new blocks added from plans, top-ups, or promotions.
• Top-ups and adjustments: manual or automatic increases/decreases to the balance.
• Deductions: reductions from metered usage, recorded per event.
• Expirations: blocks that reached their configured expiry date.
• Revocations: credits manually voided or removed.

The ledger records:

• Starting and ending balances for each change.
• Timestamps for when changes occurred.
• Actors (system or admin) that initiated the balance change.

The ledger ensures that credit usage is traceable, auditable, and exportable for reporting, analytics, and compliance.

​

Direct credit consumption

Credits can be granted to and consumed by a customer regardless of whether they have an active subscription or an assigned plan. This decouples the credits system from Stigg subscription management entirely, which is useful when:

• You manage subscriptions on your own side and only want Stigg for credit pools, balances, and entitlement enforcement/governance.
• You already have your own credit-metering system and just want to report consumption to Stigg.

Credits can be subtracted directly from the Stigg app (Customers → [Customer] → Credits → Adjust credits balance → Subtract credits, see Adjust credit balance) or from the SDK via consumeCredits / consumeCreditsAsync. Entitlement checks (getCreditEntitlement, getEntitlement) also work without a subscription in place.

​

Credit consumption modes

Credits can be consumed via two reporting paths. Choosing the right one depends on whether your use case requires strict, real-time enforcement or can tolerate a short lag: The optimistic write-back used by reportUsage means the balance shown to your application is correct immediately — Stigg applies the deduction at write time and reconciles to the source-of-truth asynchronously. For most strict-enforcement flows, this is indistinguishable from a fully synchronous system. Both paths write to the same credit ledger. The choice is about latency and volume, not accuracy. See Report usage for the SDK call and the response shape including the returned credit object.

​

Credit grant types

Credit grants are categorized by how they originate and how they behave within the credit pool:

• Recurring - Credits included in a subscription plan, issued automatically on each billing cycle.
• Prepaid - Credits purchased up front as a fixed package.
• Promotional - Free credits granted for adoption or incentive purposes, with zero cost basis.
• Manual adjustment - Credits added or removed by an admin.
• Overdraft - System-generated grants that track negative credit balances. Overdraft grants are created automatically when a customer’s usage exceeds their available balance and are settled automatically when new credits arrive. Overdraft grants cannot be created, edited, or voided manually.

​

Negative credit balance

Stigg supports negative credit balances, allowing customers to continue consuming credits even after their balance reaches zero. Instead of blocking usage, the system creates an overdraft grant that tracks the deficit. How it works:

1. A customer consumes credits through usage events.
2. When all active grants are depleted and there is still remaining cost, an overdraft grant is automatically created.
3. The overdraft grant tracks how many credits the customer owes.
4. When the customer receives new credits (purchase, top-up, promotional, or recurring), the overdraft is automatically settled.

Overdraft grant properties:

• Display name: Overdraft
• Grant type: OVERDRAFT
• Amount: 0 (the grant itself has no credits to give)
• Consumed amount: reflects the deficit (how many credits the customer consumed beyond their balance)
• Payment collection: not required

Settlement behavior:

• Full settlement - The new grant has enough capacity to cover the entire overdraft. The overdraft’s consumed amount is transferred to the new grant, and the overdraft is voided.
• Partial settlement - The new grant doesn’t fully cover the overdraft. Only the available capacity is transferred, and the overdraft remains active with a reduced deficit.

One overdraft per currency per customer - Each customer can have at most one active overdraft grant per credit currency (and per resource, if resource-scoped).

​

Credit wallet soft limit

Every credit entitlement on a plan or add-on can be set to hard limit (default) or soft limit. Configuring the limit type In the plan or add-on editor, open the credit entitlement row. A Hard limit toggle is shown alongside the entitlement (matching the toggle pattern used for other metered features). The toggle is on by default (hard). Flip it off to allow overage. Composition rule — any soft wins When a customer’s credit wallet is funded by multiple entitlements (e.g., a plan grant and an add-on grant), the wallet is treated as soft if any contributing entitlement has the soft-limit flag set. The resolved hasSoftLimit value is OR’d across all active grants for that wallet. Credit-backed features inherit the wallet’s soft-limit Features that consume credits (credit-backed features) are subject to the same access result as the wallet. If the wallet is soft, those feature entitlement checks also return hasAccess: true and hasSoftLimit: true past zero balance, keeping feature reads consistent with the wallet state. What’s not in scope yet

• Soft limits on subscription-level credit grant overrides
• Usage reset on plan migrations for soft-limit wallets