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

# POST /v1/balances.create

`POST /v1/balances.create`

Create a balance for a customer feature.

## 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).
  - `included_grant` number — The initial balance amount to grant. For metered features, this is the number of units the customer can use.
  - `unlimited` boolean — If true, the balance has unlimited usage. Cannot be combined with 'included_grant'.
  - `reset` object — Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets.
    - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — The interval at which the balance resets (e.g., 'month', 'day', 'year').
    - `interval_count` number — Number of intervals between resets. Defaults to 1 (e.g., interval_count: 2 with interval: 'month' resets every 2 months).
  - `rollover` object — Rollover configuration for the balance.
    - `max` number, nullable
    - `max_percentage` number, nullable
    - `duration` 'month' | 'forever'
    - `length` number, required
  - `expires_at` number — Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset.
  - `next_reset_at` number — Unix timestamp (milliseconds) for the first reset boundary, allowing a custom (e.g. shorter) first period. Requires 'reset', and must occur before 'expires_at' if both are provided. Subsequent resets advance by one reset interval from this boundary.
  - `balance_id` string — A unique identifier for this balance. Use this to target the balance in future update / delete calls.

## 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)