Customer credits

​

Credit usage per customer

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

​

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. See Resource-specific credit 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. Left column — granted credits Right column — balance status 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.

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

Custom range granularity When Custom range is selected, the chart’s x-axis granularity adapts to the window length: 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

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