Credits balance

Overview

The Credits Balance widget displays a customer’s current prepaid credit balance. It provides visibility into how many credits remain in the account, and includes an Add credits call-to-action button for prompting customers to top up their balance.

Layout

The Credit balance widget displays the customer’s current available credit amount in a clear and prominent format. The layout includes the following elements:

The customer’s current credit balance in tokens (or other configured unit).
The balance updates in real time after purchases or top-ups.
An Add credits CTA button for prompting customers to top up their balance.

Add credits

The Add credits button is shown automatically when both of the following conditions are met:

Credit top-ups are allowed for the customer’s account.
The customer’s current plan includes add-ons that can grant additional credits.

When clicked, Stigg opens a checkout flow that allows the customer to purchase additional credits. The credit amount and pricing are determined by the billing model configured in the top-up add-on within the price wizard.

Use the onAddCredits prop to hook into the button click, for example to open a custom modal, trigger analytics, or redirect to a dedicated top-up page:

<CreditBalance
  currencyId="cred-type-ai-tokens"
  onAddCredits={() => {
    // Custom behavior when "Add credits" is clicked
  }}
/>

Customization

The Stigg app offers a no-code widget designer, which allows you to control the widget colors, typography and layout.

Custom CSS

For more advanced customization, custom CSS can be applied using the widget designer of the Stigg app. Alternatively, custom CSS can also be applied using code. Below you can find a list of the supported CSS classes:

Main container classes

Class name	Description
`stigg-credit-balance-container`	Main wrapper container for the entire `CreditBalance` widget
`stigg-credit-balance-card`	Card container with border and padding that wraps the content

Content classes

Class name	Description
`stigg-credit-balance-title`	Title/header text at the top of the widget
`stigg-credit-balance-value-amount`	Main balance amount (large number)
`stigg-credit-balance-value-suffix`	Units or symbol text next to the amount
`stigg-credit-balance-value-error`	Error message when balance fails to load
`stigg-credit-balance-value-loading`	Loading skeleton state
`stigg-credit-balance-value-no-balance`	Message shown when no balance data is available

CTA button classes

Class name	Description
`stigg-credit-balance-add-credits-button`	Add credits CTA button
`stigg-credit-balance-add-credits-icon`	Icon inside the Add credits button

Snippet

import { StiggProvider, CreditBalance } from '@stigg/react-sdk';

function App() {
  return (
    <StiggProvider
      apiKey="your-stigg-api-key"
      customerId="customer-demo-01"
    >
      <div className="credit-widgets">
        {/* Basic Credit Balance */}
        <CreditBalance
          currencyId="cred-type-ai-tokens" // Required: currency identifier
          showUnits={true} // Optional: show units text
          decimalPlaces={2} // Optional: limit decimal places (null = no limit)
          localization={{
            title: "Available Credits" // Optional: custom title
          }}
          onAddCredits={() => {
            // Optional: callback invoked when the "Add credits" button is clicked
            // The button is displayed when top-ups are allowed and
            // the plan has add-ons that can grant additional credits
          }}
        />
      </div>
    </StiggProvider>
  );
}

export default App;

Props

string

required

Currency or credit type identifier used to fetch the credit balance.

number

Number of decimal places to display for the balance value. Defaults to no limit when not set.

boolean

Whether to display the currency unit label (for example, "tokens" or "credits").

(entitlement: CreditEntitlement) => void

Callback invoked when the Add credits button is clicked. Receives the current CreditEntitlement object. Use this to open a checkout flow, a modal, or redirect the customer to a top-up page.

object

Text overrides for customizing widget labels, messages, and states.

string

Additional CSS class applied to the root container.

React

Vue.js

Next.js

Webflow, Wordpress, HTML

Getting started

Developer tools

Governance (Private Beta)

Modeling your pricing in Stigg

Managing customers, subscriptions and entitlements

Getting usage data into Stigg

Snap-in widgets

Native integrations

Importing and exporting data

Going live

Workflow automation

Rolling out pricing changes with confidence

Price localization

Managing your account

High-availability and scale

Security & compliance

Overview

Layout

Add credits

Customization