Users
Billing

Adjust a user's credit balance

Changed on

Increases or decreases the credit balance for the specified user. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that duplicate requests are safely handled.

post/users/{user_id}/billing/credits

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/users/{user_id}/billing/credits
  • Auth: HTTP bearer

Path parameters

user_idstring required

The ID of the user whose credit balance to adjust

Request body

amountinteger required

The credit amount in cents. Must be greater than zero.

action'increase' | 'decrease' required

Whether to increase or decrease the credit balance.

currencystring

The currency code (e.g. "USD"). Defaults to USD if not provided.

idempotency_keystring required

A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.

notestring

An optional note to attach to the ledger entry.

Response

A credit ledger entry.

objectstring required

String representing the object's type. Always "commerce_credit_ledger".

idstring required

Unique identifier for the ledger entry.

payer_idstring required

The ID of the payer whose balance was adjusted.

source_typestring required

The type of source that originated the adjustment (e.g. "grant").

source_idstring required

The ID of the source that originated the adjustment.

notestring nullable

An optional note attached to the ledger entry.

created_atstring date-time required

Timestamp when the ledger entry was created.

Changes

  • 2025-11-107f4ef90e4daaRevision changes
    • breaking

      the response's property type changed from integer to object, and format from int64 to no format for status

    • breaking

      removed the required property from the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

  • 2025-11-1042e3e85e75f8Revision changes
    • info

      endpoint added