Credits make fast-moving AI usage predictable. They give customers transparency and control while protecting your costs in real time. The challenge has been delivery, where you either build complex infrastructure or replace your billing system. Stigg removes that trade-off. You can launch enterprise-grade credits on top of your existing billing, with no migration. This guide shows how to configure credits in Stigg and connect them to your current provider. You’ll create a credit type, include credits in a plan (prepaid or recurring), create a subscription, map metered features to credit burn, enable trial grants and auto top-ups, and review usage in the credit ledger and charts. If you’re evaluating, run the steps in a test environment first.

​
Create your credit type

A credit type is the custom currency your product will grant and burn (for example, “AI Tokens”). It defines the unit name customers see, and it’s what Stigg uses to create a separate credit pool and ledger per customer. Credit types are independent and non-interchangeable. Usage mapped to one credit type can only consume from that type’s pool. You’ll reference this credit type later in plans (prepaid or recurring), grants/top-ups, auto top-ups, and customer widgets. To create one:
  1. Go to Product Catalog → Credits.
  2. Click Create credit type.
  3. Enter a Name and Description (e.g., “AI Tokens for processing requests”).
  4. Set Units for how the currency is displayed in your UI (singular “Token”, plural “Tokens”).
  5. Save.
Stigg generates an ID automatically. If you need to customize it or to edit the name, description, or units later, open the … menu next to the credit type and choose Edit.
After creation, the credit type becomes the anchor for pricing and consumption. Each customer can hold multiple, independent credit pools, one per type. Usage only burns from the pool that matches the feature’s mapping to that type. Plans (prepaid or recurring), grants and top-ups (manual or automatic), and customer-facing widgets all reference this type to display balances, drive deductions in real time, and report grant and usage history.

​
Add credit type to plan

Decide how customers receive and spend credits in your product. Currently, credits are supported only in a prepaid model, where customers purchase a block of credits up front and consume them over time. Every change is written to the ledger, ensuring accurate tracking and reporting. Link your credit type to a prepaid plan so customers can buy a balance up front and have metered usage burn it down in real time. Prepaid works well when customers want strict spend control and the flexibility to top up at any time. To configure it:

​
Create a prepaid plan

  1. Create a plan with Plan type set to Paid and Billing model set to Prepaid. This tells Stigg the plan sells credits up front and burns them down as usage arrives.
  2. In Currency, choose the credit type you created earlier. This is the currency the plan will grant and consume.

​
Define the default (self-service) top-up configuration

  1. Pick a Top-up model (for example, Flat rate). This controls how additional purchases are priced when customers add more credits.
  2. Set the currency value, for example: one AI Token costs $1.00.
  3. Enable Min/Max rules and enter the allowed purchase range, for example: minimum 250 and maximum 8,000 credits.

​
Map feature usage to credit consumption

  1. Under Credit consumption, map metered features to credits, for example: one email burns one AI Token, or one image burns five AI Tokens.
  2. Save changes.
Currently, only event-based meters are supported. Learn more about event-based meters.
After you save the plan, purchases deposit credit blocks into the customer’s pool. As usage is reported, Stigg deducts in real time from the pool and records each decrement in the ledger. You can see your current balance and how it changes over time in the grants table and the usage chart.

​
Create a subscription

Once your plan is ready, create a live subscription so Stigg can grant credits, enforce burn-down, and (optionally) auto-recharge.

​
Option 1: Sales-led (in the Stigg app)

This approach is more relevant for sales-led opportunities.
  1. Go to Customers → [customer] → Create subscription.
  2. In Configuration, pick the Product and the credit-enabled Plan.
  3. Set Price localization if you need a different display currency.
  4. In Credits, confirm the currency and, if applicable, adjust the currency value for this subscription.
  5. In Schedule, choose the start date.
  6. In Billing, select the billing provider, confirm the billing address, and choose a payment method.
  7. Review the subscription preview panel on the right, then click Create Subscription.

​
Option 2: In your application (code-first approach)

Use the SDK or API to provision subscriptions programmatically as part of your product’s self-service flow. This approach is best for automated sign-ups and in-app upgrades and most relevant for self-service opportunities.

​
Add credits to a customer’s pool

You can load credits two ways: through the Stigg app (one-off admin actions) or self-serve (customers buy credits and the grant is created automatically).

​
Add credits in the Stigg app

  1. Go to Customers → [customer] → Credits and click Adjust credits balance.
  2. In Adjustment type, choose Grant credits.
  3. Pick the credit Currency (type) to fund (for example, AI Tokens).
  4. In Credit amount, enter how many credits to add.
  5. Set Priority — lower numbers are consumed first (e.g., 0 is the highest priority).
  6. If you need to schedule the credits addition, set Effective date and Expiry date in Schedule.
  7. Set the required credit grant method in the Grant method section:
    • Purchase credits — set Per unit cost basis and select a Payment method.
    • Promo/Free granted — add a Reason for the grant.
  8. Add a Reason (up to 200 characters) for audit/context.
  9. Review the Summary section and click Grant Credits.
The grant will now appear in the Grants section of the customer overview page and an increment entry is written to the ledger.

​
Add credits in your application

Customers can add credits in your application in two ways: embed the Stigg Checkout (see Credits Balance widget) to take payment and automatically create a paid grant, or handle payment in your app and then create the grant programmatically via the API/SDKs.

​
Implement real-time usage tracking

Report raw usage events from your server as they happen. Each event should include the customer identifier, the metered feature identifier, and the quantity in the priced unit (defaults to 1 if you don’t send it). Stigg applies your configured feature → credit mapping to price the event, deducts credits immediately, and records the change in the credit ledger. For idempotency and reconciliation, include a stable event ID.
Stigg currently supports event-based meters. Learn more on how to set up the feature-to-credit mapping.

​
Track credit consumption

Use the customer screen to monitor balances, analyze usage, audit changes, and apply adjustments for a single customer.
  1. Go to Customers → [Customer], then switch to the Credits tab for the dedicated credits workspace. If the customer has multiple credit types, use the Currency selector in the Credits view to switch pools.
  2. Check Credits utilization for the live used/total visualization and the by-feature legend.
  3. Use quick the Adjust credits balance actionwhen the balance is low or you need to grant credits.
  4. If you need plan or billing context, go to Overview to see Customer details, Subscriptions, and saved Payment method.

​
Use the customer credits workspace (Stigg app)

  1. In the Stigg app, go to Customers → [Customer], then open the Credits tab. If the customer has multiple credit types, use the Currency selector to switch between pools.
  2. Review Credits usage.
  3. Use the quick actions Automatic top-up or Adjust credits balance to configure thresholds/top-ups or to grant credits.
  4. For plan or billing context, switch to the Overview tab (Customer details, Subscriptions, Payment method).
Answer “who used what, when” before you adjust anything.
  1. In Credit usage, set Breakdown to By feature.
  2. Use the Range picker to select a preset window
  3. Read the stacked bars; each segment shows credits consumed for that feature or user on that date.
  4. Check the number displayed next to each item in the legend. That number is the total credits consumed by that item within the selected range.

​
Audit with the credit ledger (event-by-event)

Use the ledger when you need a forensic, append-only trail of balance changes.
  1. Click Ledger.
  2. Filter with Date range, Group by, and Source to narrow results.
  3. Review columns: Timestamp, Type (Grant / Consumed / Expired), Source ID and Source, AI Tokens (delta), End balance, Actor.
  4. Page with the controls or change Rows per page to see more events.

​
Inspect the grants table (credit blocks)

Understand where the current balance comes from and what will expire.
  1. Switch to Grants.
  2. Use Date range, Group by, and Actors filters if needed.
  3. Review each row: Status (Active / Expired / Voided / Scheduled), AI Tokens Balance (remaining / original), Effective date, Expiry date, Actor, Reason.
  4. Use the ⋯ menu for row actions where available.

​
Promotional credits

  1. Enter Credit amount.
  2. Under Grant method, select Promo/Free granted.
  3. Set Priority — lower numbers are consumed first (e.g., 0 = highest priority).
  4. If required, in Schedule, set Effective date and/or Expiry date.
  5. Add a reason for the grant to the Reason field.
  6. Review the Summary and click Grant Credits.
A promotional grant block will appear in Grants with its dates and status. The Ledger will record a Grant entry.
  1. Enter Credit amount.
  2. Under Grant method, select Purchase credits.
  3. Set Priority — lower numbers are consumed first (e.g., 0 = highest priority).
  4. Set Per unit cost basis and choose a Payment method (or issue an invoice, per your billing flow).
  5. If required, in Schedule, set Effective date and/or Expiry date.
  6. Add a reason for the grant to the Reason field.
  7. Review the Summary and click Grant Credits.
A paid grant block with cost basis will appear in Grants;. The Ledger will recordß the increment and new End balance.

​
Add widgets

Stigg’s customer widgets let you expose credit transparency and control directly in your product—without rebuilding UI. You can embed them individually or assemble a full self-serve experience for balance, usage, grants, and account context. Using the widgets saves engineering time, reduces maintenance, and helps you go to market faster with a consistent, battle-tested UX.

​
Credits Balance widget

Use this widget to show a real-time balance and make topping up effortless. Customers see their current credit count update instantly, get low-balance warnings before they run out, and can purchase more credits without leaving your app. If you run multiple credit types, the widget can present each pool side by side, with a short balance history to explain recent changes.

​
Credits Usage Chart

Once balance is visible, help customers understand where credits go. The usage chart visualizes daily, weekly, or monthly burn, with breakdowns by feature or by user so teams can spot heavy consumers at a glance. A date-range selector supports quick comparisons (last 7, 30, or custom periods), and an export makes it easy to share usage data for reporting.

​
Credits Grants Table

For full lifecycle transparency, the grants table lists the credit blocks that fund the balance. Each row shows amount, effective and expiry dates, and category (paid or promo), along with current status (active, expired, voided, or scheduled). Customers can review purchase history, see remaining amounts per grant, and act on upcoming expirations before value is lost.

​
Credits Utilization Portal

The utilization portal brings everything together in a single screen. It opens with a dashboard that summarizes balance, usage trends, and grant status, then lets customers dive into detailed analytics to understand consumption patterns and projections. The same view also surfaces plan context and billing information—such as invoice history and payment methods—and gives users control over notification preferences for low balance and expiration.

​
Enforce access when credits run out

Decide how your product should behave at depletion and implement an entitlement check before you execute a metered action. With a hard limit, usage is denied once the balance is insufficient. With a soft limit, usage can continue and the balance may go negative (to be handled by your commercial policy). In both cases, Stigg records every attempt in the ledger when a deduction occurs and updates the credit pool in real time.

​
Hard limit

  1. Pre-check the customer’s credit balance for the relevant credit type.
const { balances: [balance] } = await stigg.getCreditBalance({
  customerId: 'customer-2cd9b7',
  currencyId: 'cred-type-ai-credits',
});

if (balance?.currentBalance > 0){
  // The current balancer is positive, we can consume more credits
}
  1. If Remaining > 0, proceed with the action and report usage (event-based).
await stiggClient.reportEvent({
  customerId: 'customer-2cd9b7',
  eventName: 'credit-consuming-action',
  idempotencyKey: 'ccc4bbf4-8b9d-4f3a-a1e5-1f6e6e6e6e6e',
  timestamp: new Date('2025-01-01T10:10:10.000Z'),
  dimensions: {
    userId: 'user-123',
    actionTokens: 150,
  }
});

​
Soft limit

Proceed with the action and report usage. The ledger will show a Consumed entry and the End balance may drop below zero.
Enforcement (block at zero vs. allow overage) is handled in your application logic. Use Stigg’s real-time balance to pre-check before metered actions and decide whether to proceed or deny. When usage is reported, deductions follow your feature→credit mapping and are recorded in the append-only ledger.

​
Notify customers about low balance and depletion

Use alerts and webhooks to prevent unexpected service interruptions and to keep downstream systems in sync.

​
In-product alerts

Configure low balance notifications so end users see warnings before they hit zero.

​
Webhooks

​
Balance-level (aggregate pool)

  • credits.balance.usage_low — The customer’s credit pool for a given credit type crossed a configured threshold. Use for low-balance warnings, in-app banners, or to propose enabling Auto top-up.
  • credits.balance.depleted — The pool has hit zero. Use to enforce hard limits, pause metered features, and prompt a top-up or plan change.

​
Grant-level (individual block)

  • credits.granted — A new grant block was created (prepaid purchase, promo, or admin grant). Use to update the grants table, acknowledge purchases, and refresh balances.
  • credits.grant.updated — An existing grant’s metadata changed (for example, dates or amount). Use to re-render grant rows and refresh expiry messaging.
  • credits.grant.usage_low — A specific grant block crossed a usage threshold (e.g., 80% consumed). Use for proactive “use-it-or-lose-it” nudges when expiry is near.
  • credits.grant.depleted — A grant block was fully consumed. Use to update the grants table and, if relevant, roll consumption to the next block.
  • credits.expired — A grant block reached its expiry date. Use to remove it from “Active” balances and notify the customer if value was left unused.

​
Which to use when

  • Prefer balance-level events for customer-facing alerts and enforcement decisions (they reflect the effective ability to use credits right now).
  • Prefer grant-level events for finance, rev-rec schedules, and grant lifecycle UIs (they track the provenance and status of each block).

​
Troubleshoot and monitor

When numbers don’t look right, follow the same path your data takes.
  1. Check the usage events surface to confirm the feature and quantity you reported.
  2. In Credits → Ledger, find a matching Consumed entry with the expected delta and end balance.
  3. In Credits → Credit usage, select a preset range and confirm the burn appears in the stacked chart.
  4. In Credits → Grants, ensure there was an active grant at the time.

​
Common fixes

SymptomWhat to checkWhere
Usage isn’t deductingConfirm the feature → credit mapping targets the correct credit type, and that event-based usage was sent.Credits configuration; Usage events; Customers → [Customer] → Credits → Ledger
Purchase didn’t grant creditsVerify payment/invoice status in Overview, then look for a corresponding Grant entry and an Active block.Customers → [Customer] → Overview (billing status); Credits → Grants / Ledger

​
Billing and revenue checks

Paid top-ups and purchases grant credits after payment succeeds (card) or when an invoice is issued (invoice flow). Each purchase writes a grant entry with amount and cost basis for revenue recognition. To reconcile in your analytics stack, connect a warehouse in Integrations → Data warehouse. See the native integrations overview and use the exported credits tables described in the export schema to join grants, ledger entries, consumption, expirations, and adjustments.