Stigg Credits

Stigg Credits — Credit-Based Monetization

This skill is the canonical home for credits end-to-end: credit currency definition, granting credits (recurring / prepaid / promotional / manual / overdraft), runtime consumption (mappings, custom formulas, ledger), auto-recharge, seat-based pools, billing integration, and revenue recognition. The static catalog shape (recurring credit grants attached to plans / add-ons as entitlements) is in stigg-pricing-modeling/references/credits-modeling.md; everything else lives here.

Before You Start

Per the umbrella stigg skill: search first. The credits surface evolves quickly (custom formulas, overdraft mechanics, seat-based pools are recent additions). Use the Mintlify Stigg docs MCP (search_stigg, query_docs_filesystem_stigg) to confirm specifics before authoring.

Mental Model — Five Pieces

                              ┌──────────────────────────────────┐
                              │   Credit currency (the unit)     │
                              │   "AI tokens", "API credits",    │
                              │   "compute units"                │
                              └────────────────┬─────────────────┘
                                               │ denominates
                                               ▼
   Grants funded by:        ┌──────────────────────────────────┐
   • Recurring (plan/addon)  │   Credit pool (per customer,    │
   • Prepaid (purchase)      │   per credit currency)          │
   • Promotional (zero cost) │   = balance + many grants       │
   • Manual                  └────────────────┬─────────────────┘
   • Overdraft (system)                       │ deducted by
                                              ▼
                              ┌──────────────────────────────────┐
                              │   Consumption mapping or         │
                              │   custom formula  (per plan)     │
                              │   metered feature → credits      │
                              └────────────────┬─────────────────┘
                                               │ records
                                               ▼
                              ┌──────────────────────────────────┐
                              │   Credit ledger (append-only)    │
                              │   grants, burns, expirations,    │
                              │   revocations, adjustments       │
                              └──────────────────────────────────┘

references/grants.md, references/consumption.md, references/ledger.md, references/auto-recharge.md, references/seat-pools.md, references/custom-formulas.md, references/billing-integration.md, references/revenue-recognition.md.

Credit Currency

A credit currency (called a "credit type" in the Stigg app's catalog UI) is your unit of consumption — tokens, credits, compute units. Customers' usage of metered features deducts from a pool denominated in that currency.

• The full currency lifecycle — define, update, archive, unarchive, list, and inspect associated plans/add-ons — is available via the Stigg MCP (preferred for AI-assisted dev) or the Stigg app under Product Catalog → Credits. An end-to-end credits-consumption workflow (currency → metered feature → per-plan consumption mapping → grants → usage reporting) can run entirely through the MCP. Refresh the live MCP tool listing or the docs before authoring — operation names and field shapes are owned by the live surface, not this skill.
• Singular / plural display names like "token" / "tokens", immutable ID. Inspect dependencies before archiving — Stigg blocks archive while the currency is referenced by active plans or add-ons.
• Non-interchangeable across currencies — usage against one currency cannot consume another.
• Not a billing currency. Custom credit currency is a consumption unit; for multi-currency billing (USD/EUR/JPY), see stigg-pricing-modeling/references/price-localization.md.
• The catalog-side modeling shape (recurring grants attached to plans / add-ons as entitlements) is in stigg-pricing-modeling/references/credits-modeling.md.

Credit Pool

One pool per (customer, credit currency) (and per resourceId for multi-active products). The pool holds many credit blocks (also called "grants" or "allocations"), each with amount, lifecycle dates (effective_at / expires_at), category (paid / promotional), cost_basis ($ per credit, used for revenue rec), priority (lower = higher), and status. Full field reference: references/grants.md.

Five Grant Types

Modeling shape (recurring credits attached to a plan or add-on as an entitlement) is covered in stigg-pricing-modeling/references/credits-modeling.md. Granting credits at runtime (prepaid / promotional / manual) lives here in references/grants.md.

Consumption — Configured on the Plan

How a metered feature converts to credits is configured on the plan (and on each add-on) — not on the feature or the credit currency. Each plan picks a flat conversion rate (1 token = 1 credit) or a custom formula on dimensions (credits = 2.5 × input + 10 × output). Same feature, different rules per plan, is fully supported.

Path: Product catalog → Plans → select plan → Edit price → Set price → Credit consumption (per metered feature on the plan).

Burn order — when multiple grants are eligible

Once an event consumes N credits, Stigg picks which grant(s) to deduct in this order:

1. Priority — lower number = higher priority.
2. Expiration date — sooner-expiring grants burn first.
3. Category — promotional before paid (when other attributes match).
4. Effective date — earlier-effective first.
5. Created date — older first if all else ties.

If a single event needs more credits than the highest-ranked grant has, Stigg consumes from the next, then the next, with a separate ledger entry per grant consumed. Worked example in references/consumption.md.

Overdraft — Negative Balance

Stigg supports negative credit balances. When a usage event needs more credits than the customer has, an overdraft grant is auto-created to track the deficit. Always enabled — there is no off switch. Overdraft grants:

• grant_type: OVERDRAFT, amount: 0, consumed_amount = the deficit.
• One overdraft per (customer, currency) (and per resource, if resource-scoped).
• Cannot be edited or voided manually.
• Auto-settled when new credits arrive — full or partial.

Detailed behavior + worked example: references/consumption.md.

Custom Consumption Formulas

For variable-cost workloads (multi-model LLM ops, multi-input processing, weighted token costs), define a custom formula instead of a fixed conversion rate:

credits_used = (a × documents) + (b × emails) + (c × images)
credits_used = (1.1 × model1_tokens) + (1.5 × model2_tokens) + (5 × model3_tokens)

Configured per metered feature, in Product Catalog → Plans → Edit price → Set price → Credit consumption → Calculation mode: Advanced formula. Full mechanics: references/custom-formulas.md.

Auto-Recharge

Keep a customer's prepaid balance from depleting by auto-purchasing credits when the balance drops below a threshold:

Webhook events to handle:

• automatic_recharge.operation.attempted — every attempt (success and failure).
• credits.automatic_recharge_limit_exceeded — fired at 80%, 90%, 100% of the spend limit.
• automatic_recharge.configuration.changed — enabled / disabled, including system-driven (e.g. payment failure).

Setup walkthrough: references/auto-recharge.md.

Seat-Based Credit Pools

Link a recurring credit grant to a metered seat feature so credits scale with team size:

"1,000 AI credits per seat per month" → 5 seats = 5,000 credits/month → adding a 6th seat auto-provisions another 1,000.

Credits go into a shared pool (not siloed per user) — the org draws from one balance. Requires Stripe integration. Available on plans/add-ons that include both a credit entitlement and a metered seat feature. Configuration in references/seat-pools.md.

Billing Integration

Stigg sits alongside your billing stack — no rip-and-replace. Your billing provider (Stripe / Zuora / custom) handles payments, taxes, invoices, payment methods. Stigg handles credit pools, grants, consumption, and enforcement.

When money moves:

System boundaries (who owns what):

• Your billing system: product catalog and prices, taxes, invoicing, payments, refunds, collections.
• Stigg: credit currencies (the catalog UI calls them "credit types"), pools, grants, real-time consumption, ledger, customer widgets.

Common flows (self-serve top-up, sales-led invoice, automatic top-up): references/billing-integration.md.

Revenue Recognition

Stigg gives Finance an auditable trail. Per grant: amount_granted, amount_remaining, amount_consumed, expires_at, category, cost_basis (per-unit). The append-only ledger captures every burn / expiry / revocation.

Deferred revenue   = amount_remaining × cost_basis      (paid grants only)
Recognized revenue = consumed_in_period × cost_basis
Breakage           = expired_in_period × cost_basis     (per your policy)

Promotional grants have zero cost basis → never affect revenue. Full journal-entry model + reconciliation pattern: references/revenue-recognition.md.

Credits Webhooks

Credit-specific events (credit.balance.low / .depleted, credit.grant.*, automatic_recharge.*) drive in-app notifications, win-back campaigns, and payment-failure flows. For payload shape, signature verification, retry semantics, and a handler skeleton, see stigg-webhooks.

When NOT to Use This Skill

• Modeling non-credit features / plans / add-ons → stigg-pricing-modeling.
• Runtime entitlement checks for boolean / configuration features (no credits involved) → stigg-entitlements.
• Provisioning / canceling subscriptions → stigg-subscriptions.
• Deciding whether credits are the right pricing model in the first place → stigg-pricing-expert.

Common Mistakes