> ## 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.
# Monetize my product using credits
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 using a prepaid model. You’ll create a credit type, include credits in a plan, 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.
**Looking to include credits directly in a plan or add-on as an entitlement?** For "included credits" use cases (e.g., "5,000 AI credits per month on the Pro Plan"), see the [Grant credits as entitlements in plans and add-ons](./grant-credits-in-plans-and-add-ons) guide.
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](/documentation/modeling-your-pricing-in-stigg/features#event-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.
#### Grant credits
```typescript theme={null}
await stiggClient.grantCredits({
customerId: 'customer-123', // required
amount: 100, // required
currencyId: 'currency-789', // required
displayName: 'Promo credits', // required
resourceId: 'resource-456', // optional
description: 'Promo credits', // optional
expireAt: new Date('2025-12-31'), // optional
priority: 1, // optional
cost: { amount: 100, currency: 'USD' }, // optional
awaitPaymentConfirmation: false, // optional
metadata: {
campaign: 'summer-promo',
grantedBy: 'admin-id'
}
});
```
#### List credit grants
```typescript theme={null}
await stiggClient.getCreditGrants({
customerId: 'customer-123',
resourceId: 'resource-456',
currencyId: 'currency-789',
});
```
#### Retrieve credit ledger
```typescript theme={null}
await stiggClient.getCreditLedger({
customerId: 'customer-123',
resourceId: 'resource-456',
currencyId: 'currency-789',
paging: { // optional
first: 50,
after: 'cursor-string'
}
});
```
#### Get credit usage
```typescript theme={null}
await stiggClient.getCreditUsage({
customerId: 'customer-123',
resourceId: 'resource-456',
currencyId: 'currency-789',
timeRange: 'LAST_MONTH' // 'LAST_DAY' | 'LAST_WEEK' | 'LAST_MONTH' | 'LAST_YEAR'
});
```
#### Void a credit grant
```typescript theme={null}
await stiggClient.voidCreditGrant({
id: 'grant-id-123' // required
});
```
## 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](#inspect-the-grants-table-credit-blocks) of the customer overview page and an increment entry is written to the ledger.
## 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](/documentation/modeling-your-pricing-in-stigg/features#event-meters). Learn more on how to set up the [feature-to-credit mapping](#map-feature-usage-to-credit-consumption).
By default, Stigg supports up to **1,000 events per second** per customer environment. This limit can be significantly increased for enterprise-scale workloads. Contact Stigg support to raise throughput as needed.
## 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).
### Explore credit usage (trends)
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.
#### Paid credits
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.
```typescript theme={null}
const entitlement = await stigg.getCreditEntitlement({
customerId: 'customer-2cd9b7',
currencyId: 'cred-type-ai-credits',
});
if (entitlement?.remaining > 0) {
// The current balance is positive, we can consume more credits
}
```
2. If **Remaining > 0**, proceed with the action and **report usage** (event-based).
```typescript theme={null}
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 one of the configured thresholds. Thresholds are configurable per customer, allowing you to set multiple alert levels (e.g., 80%, 50%, 20%). Use for proactive 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 one of the configured usage thresholds (e.g., 80% consumed). Thresholds are configurable, allowing multiple alert levels. 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**](/documentation/modeling-your-pricing-in-stigg/features#event-meters) 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
| Symptom | What to check | Where |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Usage isn’t deducting** | Confirm 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 credits** | Verify 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](/documentation/native-integrations/overview#data-warehouse) and use the exported credits tables described in the [export schema](/documentation/importing-and-exporting-data/export/schema#schema) to join grants, ledger entries, consumption, expirations, and adjustments.