Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
balances

Update a customer balance.

post/v1/balances.update

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer.

feature_idstring required

The ID of the feature.

entity_idstring

The ID of the entity for entity-scoped balances (e.g., per-seat limits).

remainingnumber

Set the remaining balance to this exact value. Cannot be combined with add_to_balance.

add_to_balancenumber

Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance.

usagenumber

The usage amount to update. Cannot be combined with remaining or add_to_balance.

interval'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'

Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals.

included_grantnumber

Set the granted balance to this exact value.

balance_idstring

Target a specific balance by its ID (set on create). Use when the customer has multiple balances for the same feature.

next_reset_atnumber

The next reset time for the balance. If there are multiple breakdowns, this will update the breakdown with the next reset time.

expires_atnumber

Unix timestamp (milliseconds) when the balance expires. Targets a specific balance via balance_id / interval when the customer has multiple balances for the same feature.

Example request

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "remaining": 5
}

Response

OK

successboolean required