---
title: "POST /v1/balances.update"
method: POST
path: "/v1/balances.update"
tags: ["balances"]
---

# POST /v1/balances.update

`POST /v1/balances.update`

Update a customer balance.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string, required — The ID of the customer.
  - `feature_id` string, required — The ID of the feature.
  - `entity_id` string — The ID of the entity for entity-scoped balances (e.g., per-seat limits).
  - `remaining` number — Set the remaining balance to this exact value. Cannot be combined with add_to_balance.
  - `add_to_balance` number — Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance.
  - `usage` number — 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_grant` number — Set the granted balance to this exact value.
  - `balance_id` string — Target a specific balance by its ID (set on create). Use when the customer has multiple balances for the same feature.
  - `next_reset_at` number — The next reset time for the balance. If there are multiple breakdowns, this will update the breakdown with the next reset time.
  - `expires_at` number — 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.

## Response `200`

OK

- object
  - `success` boolean, required

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/revisions/29536933c0dc/schema)