Clerk API (unofficial showcase)
POST/users/{user_id}/billing/credits

Adjust a user's credit balance

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 5 body fields
user_idstringrequired
The ID of the user whose credit balance to adjust

Parameters for the credit balance adjustment

amountintegerrequired
The credit amount in cents. Must be greater than zero.
actionstringrequired
Whether to increase or decrease the credit balance.
Allowed:increasedecrease
currencystringoptional
The currency code (e.g. "USD"). Defaults to USD if not provided.
idempotency_keystringrequired
A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry.
notestringoptional
An optional note to attach to the ledger entry.

8 status codes
200A credit ledger entry.
objectstringrequired
String representing the object's type. Always "commerce_credit_ledger".
idstringrequired
Unique identifier for the ledger entry.
payer_idstringrequired
The ID of the payer whose balance was adjusted.
amountobjectrequired
The credit amount with formatting. Positive for increases, negative for decreases.
source_typestringrequired
The type of source that originated the adjustment (e.g. "grant").
source_idstringrequired
The ID of the source that originated the adjustment.
notestringoptional
An optional note attached to the ledger entry.
created_atstringrequired
Timestamp when the ledger entry was created.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
409Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
500Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 409 is returned: Request was not successful. A 422 is returned: Invalid request parameters. A 500 is returned: Request was not successful.