Account credits

Account credits let you maintain a credit balance for Users and Organizations. Whenever an eligible charge is created, Clerk automatically applies any available credits on the account before charging its payment method.

Manage account credits

Credits can be managed from the Clerk Dashboard or programmatically through the Backend API.

In the Clerk Dashboard

To manually adjust an account's credit balance:

1. In the Clerk Dashboard, navigate to the Users⁠ or Organizations⁠ page.
2. Select the User or Organization whose credit balance you want to adjust.
3. Open the Actions dropdown and select Adjust credit balance.
4. Enter the credit amount to add or remove.
5. Select Adjust balance.

The updated credit balance is available immediately and will be applied automatically to future eligible charges.

Programmatically

The Backend API⁠ provides endpoints for managing account credits:

• Add or remove account credits using:
  • POST /v1/users/{user_id}/billing/credits for Users
  • POST /v1/organizations/{organization_id}/billing/credits for Organizations
• Retrieve the current credit balance using:
  • GET /v1/users/{user_id}/billing/credits for Users
  • GET /v1/organizations/{organization_id}/billing/credits for Organizations

See the BAPI reference⁠ for endpoint details and request parameters.

How account credits work

Account credits are automatically applied whenever Clerk creates an eligible charge, such as a subscription renewal, subscription upgrade, etc.

If an account has available credits, Clerk deducts them from the amount due before attempting to charge the account's payment method. If the available credit exceeds the amount due, the remaining balance stays on the account and is automatically applied to future eligible charges.

The following examples show how credits are applied to charges:

Credit ledger

Every credit adjustment creates a new ledger entry. The ledger provides a complete history of how an account's credit balance changes over time, whether credits are managed from the Clerk Dashboard or through the Backend API.

Each ledger entry records:

• The amount added or removed
• The resulting balance
• When the adjustment occurred
• The reason for the adjustment (if provided)

Use the ledger to audit account credit adjustments and reconcile account balances over time.