> ## 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.

# Customer credits

## Credit usage per customer

1. Go to **Customers**.
2. Select a customer.
3. Go to the **Credits** tab.

<Note>
  Credits can be granted to and consumed by customers regardless of whether they have an active subscription - the balance updates immediately even if no plan is currently assigned. This makes it possible to run the credits system fully decoupled from Stigg subscription management, for example when subscriptions are managed elsewhere or credits are the only Stigg capability in use.
</Note>

### Resource ID filter

When a customer has resource-specific credit pools, a **Resource ID** dropdown appears at the top of the Credits tab. Use it to switch between the global credit pool and any resource-scoped pools (e.g., individual workspaces or team members). Selecting a resource scopes all views on the tab — usage overview, usage chart, and ledger — to that resource's isolated wallet.

<Frame caption="Resource ID filter in the Credits tab">
  <img src="https://mintcdn.com/stigg/-OizVNAUe4vspCwF/images/docs/credits-resource-pools.png?fit=max&auto=format&n=-OizVNAUe4vspCwF&q=85&s=e2233737bdf6307c7e10cf61ef731a84" width="2400" height="827" data-path="images/docs/credits-resource-pools.png" />
</Frame>

See [Resource-specific credit pools](./resource-specific-pools) for setup details.

### Usage overview

The **Usage overview** card provides an at-a-glance summary of a customer's credit balance for the current billing period.

<Frame caption="Usage overview showing included credits, additional grants, and balance details">
  <img src="https://mintcdn.com/stigg/-OizVNAUe4vspCwF/images/docs/credits-usage-overview-revamp.png?fit=max&auto=format&n=-OizVNAUe4vspCwF&q=85&s=a2ed8d15c9e75fff2c9e0eae1710e58c" width="1568" height="1028" data-path="images/docs/credits-usage-overview-revamp.png" />
</Frame>

**Left column — granted credits**

| Field                 | Description                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **Included credits**  | Recurring credits that came with the customer's subscription plan (reset each billing cycle). |
| **Additional grants** | One-time or promotional credits granted on top of the plan's recurring allocation.            |
| **Total granted**     | Sum of included credits and additional grants for the period.                                 |

**Right column — balance status**

| Field                 | Description                                         |
| --------------------- | --------------------------------------------------- |
| **Credits remaining** | Current spendable balance across all active grants. |
| **Used**              | Total credits consumed in the current period.       |
| **Next reset**        | Date when the recurring grant refreshes.            |

The progress bar visualizes consumption, with a separate segment for additional grants when present.

### Adjust credit balance

Click **Adjust credits balance**, then in **Adjustment type**, choose **Grant credits** or **Subtract credits**.

**Grant credits**

1. Choose the **Resource** (credit currency).
2. In **Credit amount**, enter the number of credits and verify the credit type.
3. (Optional) In **Schedule**, set an **Effective date** and/or **Expiry date**.
4. Under **Grant method**, choose:
   * **Purchase credits** → set **Per unit cost basis**, select a **Payment method**, and (optionally) add a **Reason**.
   * **Promo/Free granted** → (optionally) add a **Reason**.
5. Review the **Summary** panel (credits, total, previous/new balance).
6. Click **Grant Credits** to apply.

**Subtract credits**

Deduct credits directly from the customer's pool — no subscription or feature usage event required. Credits are burned from the customer's active grant(s) following the standard [burn order](./credits-core-concepts#credit-grant-types).

1. Choose the **Resource** (credit currency).
2. Under **Subtract details**, enter the **Credit amount** to deduct.
3. Review the **Summary** panel (previous balance, credit amount, new balance).
4. Click **Subtract credits** to apply.

A confirmation toast ("Credits subtracted successfully") confirms the deduction. The entry appears in the **Ledger** as a **Usage** event with source **Direct consumption**.

Both actions can also be performed from the backend SDK — see [Grant credits](/api-and-sdks/integration/backend/usage-and-billing#credits) and [Consume credits directly](/api-and-sdks/integration/backend/usage-and-billing#consume-credits-directly) (SDK methods `consumeCredits` / `consumeCreditsAsync`).

### Credit usage

The credit usage chart shows how a customer's credits were consumed over time.

**Top controls**

* **Group by:** break down the chart and top-sources list by any dimension attached to your reported usage events (e.g., `feature`, `user`, `model`, `region`). Type to search across all available dimensions.
* **Time range:** choose a preset (**Last 7 days**, **Last 30 days**, **Last 3 months**, **Last 12 months**) or select **Custom range** to specify exact start and end dates. Custom ranges are capped at 12 months and cannot extend into the future.

<Frame caption="Credit usage chart with dimension-based group-by and custom date range">
  <img src="https://mintcdn.com/stigg/-OizVNAUe4vspCwF/images/docs/credits-usage-date-filter.png?fit=max&auto=format&n=-OizVNAUe4vspCwF&q=85&s=f9c5d8c3603aa9ac61e74e0817d31f68" width="1418" height="704" data-path="images/docs/credits-usage-date-filter.png" />
</Frame>

**Custom range granularity**

When **Custom range** is selected, the chart's x-axis granularity adapts to the window length:

| Selected window   | X-axis granularity |
| ----------------- | ------------------ |
| Up to 2 days      | Hourly             |
| 3 to 60 days      | Daily              |
| More than 60 days | Monthly            |

**Chart**

* A stacked bar chart with one bar per date in the selected range.
* Each color segment represents a distinct value of the selected dimension.
* The breakdown list below the chart shows the top sources, ranked by total credits consumed, with the total count per source.

#### Group by dimensions

<Frame caption="Grouping credit usage by the 'model' dimension">
  <img src="https://mintcdn.com/stigg/-OizVNAUe4vspCwF/images/docs/credits-usage-breakdown-dimensions.png?fit=max&auto=format&n=-OizVNAUe4vspCwF&q=85&s=c46dfd1f82ee14bf8110fa02717e14f6" width="2400" height="1099" data-path="images/docs/credits-usage-breakdown-dimensions.png" />
</Frame>

The **Group by** control lets you slice credit consumption by any dimension key that was included in your reported usage events. Standard options are always available:

* **Feature** — which metered feature drove the consumption.
* **User** — which end-user or actor reported the usage.

Any custom dimensions you attach to usage events (e.g., `model`, `region`, `workspace_id`) also appear in the dropdown. The dropdown includes a built-in search bar so you can quickly find the right dimension when your events carry many metadata keys.

<Frame caption="Searchable group-by dropdown for credit usage dimensions">
  <img src="https://mintcdn.com/stigg/-OizVNAUe4vspCwF/images/docs/credits-usage-searchable-groupby.png?fit=max&auto=format&n=-OizVNAUe4vspCwF&q=85&s=5ade3fe27a6eec5f73ba598c2631ca9f" width="2359" height="585" data-path="images/docs/credits-usage-searchable-groupby.png" />
</Frame>

The breakdown list and chart update instantly when you change the dimension, giving you and your customers precise visibility into where credits are being spent.

### Credit ledger and grants

This screen provides a forensic history of a customer's credits. It has two coordinated tables:

#### Ledger

A chronological, append-only list of all balance-impacting events.

**Filters & controls**

* **Date range**: e.g., *May 27, 2025 - Jul 27, 2025*
* **Group by**: aggregate view options
* **Source filter**: e.g., *All source*
* **Pagination**: page numbers and **rows per page** (e.g., *12 rows*)

**Columns**

* **Timestamp**: when the event occurred
* **Type**: *Grant*, *Consumed*, *Expired* (badges)
* **Source ID**: identifier of the originating grant/feature
* **Source**: e.g., *Promotional grant*, *Credit purchase*, *Image Upscale*
* **AI Tokens**: delta for the event
  * Positive = credits **added** (e.g., `1,000`)
  * Negative = credits **removed** (e.g., `-3.0`, `-1,000`)
* **End balance**: pool balance **after** this event (e.g., `1,697`)
* **Actor**: *System*, *API*, *Admin*
* **Row actions**: three dots (⋯)

#### Grants

A ledger of individual credit blocks (grants) with their lifecycle and remaining amounts.

**Filters & controls**

* **Audit trail** link
* **Date range**: e.g., *May 27, 2025 - Jul 27, 2025*
* **Group by**
* **Actors filter**: e.g., *All actors*

**Columns**

* **Grant ID**: unique identifier
* **Timestamp**: when the grant was created
* **Status**: *Active*, *Expired*, *Voided*, *Scheduled* (badges)
* **AI Tokens Balance**: remaining vs. original (e.g., `600 / 1,000`)
* **Expiry date**: e.g., *Jul 31, 2025*
* **Effective date**: when the grant becomes usable
* **Actor**: who created/changed it (System/Admin)
* **Reason**: e.g., *Onboarding*, *Promo ended*, *Payment failed*, *Renewal bonus*
* **Row actions**: three dots (⋯)

#### Grant types

Grants in the table are categorized by type:

* **Recurring** - Credits from a subscription plan, issued each billing cycle.
* **Prepaid** - Credits purchased up front.
* **Promotional** - Free credits granted for adoption or incentive.
* **Manual** - Credits added or removed by an admin.
* **Overdraft** - System-generated grants that track negative credit balances. Created automatically when usage exceeds the available balance; settled automatically when new credits arrive.

#### Overdraft grants

Overdraft grants appear in the credit grants table with grant type **Overdraft**. They show:

* **Amount**: 0 (overdraft grants don't provide credits)
* **Consumed**: the deficit amount (how much the customer owes)
* **Status**: *Active* (until fully settled) or *Voided* (after full settlement)

<Note>
  Overdraft grants cannot be voided or edited from the grants table - the void and edit actions are disabled for overdraft grants. They are settled and voided automatically when new credits are granted.
</Note>