---
title: "POST /v1/balances.check"
method: POST
path: "/v1/balances.check"
---

# POST /v1/balances.check

`POST /v1/balances.check`

Checks whether a customer currently has enough balance to use a feature.

Use this to gate access before a feature action. Enable sendEvent when you want to check and consume balance atomically in one request.

## 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).
  - `required_balance` number — Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
  - `properties` object — Additional properties to attach to the usage event if send_event is true.
  - `send_event` boolean — If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call.
  - `lock` object — Reserve units of a feature upfront by passing a lock_id, then call balances.finalize to confirm or release the hold.
    - `lock_id` string, required — A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
    - `enabled` unknown, required
    - `expires_at` number — Unix timestamp (ms) when the lock automatically expires and releases the held balance.
  - `with_preview` boolean — If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.

## Response `200`

OK

- object
  - `allowed` boolean, required — Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
  - `customer_id` string, required — The ID of the customer that was checked.
  - `entity_id` string, nullable — The ID of the entity, if an entity-scoped check was performed.
  - `required_balance` number — The required balance that was checked against.
  - `balance` Balance, required
    - `feature_id` string, required — The feature ID this balance is for.
    - `feature` object — The full feature object if expanded.
      - `id` string, required — The unique identifier for this feature, used in /check and /track calls.
      - `name` string, required — Human-readable name displayed in the dashboard and billing UI.
      - `type` 'boolean' | 'metered' | 'credit_system' | 'ai_credit_system', required — Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
      - `consumable` boolean, required — For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
      - `event_names` string[] — Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
      - `credit_schema` object[] — For credit_system features: maps metered features to their credit costs.
        - `metered_feature_id` string, required — ID of the metered feature that draws from this credit system.
        - `credit_cost` number, required — Credits consumed per unit of the metered feature.
      - `model_markups` object, nullable — Per-model markup overrides for AI credit systems.
      - `default_markup` number — Default percentage markup for AI credit systems. Use -100 to make usage free.
      - `provider_markups` object, nullable — Per-provider default markup percentages for AI credit systems.
      - `display` object — Display names for the feature in billing UI and customer-facing components.
        - `singular` string, nullable — Singular form for UI display (e.g., 'API call', 'seat').
        - `plural` string, nullable — Plural form for UI display (e.g., 'API calls', 'seats').
      - `archived` boolean, required — Whether the feature is archived and hidden from the dashboard.
    - `granted` number, required — Total balance granted (included + prepaid).
    - `remaining` number, required — Remaining balance available for use.
    - `usage` number, required — Total usage consumed in the current period.
    - `unlimited` boolean, required — Whether this feature has unlimited usage.
    - `overage_allowed` boolean, required — Whether usage beyond the granted balance is allowed (with overage charges).
    - `max_purchase` number, nullable, required — Maximum quantity that can be purchased as a top-up, or null for unlimited.
    - `next_reset_at` number, nullable, required — Timestamp when the balance will reset, or null for no reset.
    - `breakdown` object[] — Detailed breakdown of balance sources when stacking multiple plans or grants.
      - `id` string — The unique identifier for this balance breakdown.
      - `plan_id` string, nullable, required — The plan ID this balance originates from, or null for standalone balances.
      - `included_grant` number, required — Amount granted from the plan's included usage.
      - `prepaid_grant` number, required — Amount granted from prepaid purchases or top-ups.
      - `remaining` number, required — Remaining balance available for use.
      - `usage` number, required — Amount consumed in the current period.
      - `unlimited` boolean, required — Whether this balance has unlimited usage.
      - `reset` object, nullable, required — Reset configuration for this balance, or null if no reset.
        - `interval` union, required — The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
          - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
          - 'multiple'
        - `interval_count` number — Number of intervals between resets (eg. 2 for bi-monthly).
        - `resets_at` number, nullable, required — Timestamp when the balance will next reset.
      - `price` object, nullable, required — Pricing configuration if this balance has usage-based pricing.
        - `amount` number — The per-unit price amount.
        - `tiers` object[] — Tiered pricing configuration if applicable.
          - `to` union, required
            - number
            - 'inf'
          - `amount` number, required
          - `flat_amount` number
        - `tier_behavior` 'graduated' | 'volume' — How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
        - `billing_units` number, required — The number of units per billing increment (eg. $9 / 250 units).
        - `billing_method` 'prepaid' | 'usage_based', required — Whether usage is prepaid or billed pay-per-use.
        - `max_purchase` number, nullable, required — Maximum quantity that can be purchased, or null for unlimited.
      - `expires_at` number, nullable, required — Timestamp when this balance expires, or null for no expiration.
    - `rollovers` object[] — Rollover balances carried over from previous periods.
      - `balance` number, required — Amount of balance rolled over from a previous period.
      - `expires_at` number, required — Timestamp when the rollover balance expires.
  - `balances` object — Map of feature_id to balance for the checked feature and any related features (e.g. linked credit systems).
  - `flag` object, nullable, required — The flag associated with this check, if any.
    - `id` string, required — The unique identifier for this flag.
    - `plan_id` string, nullable, required — The plan ID this flag originates from, or null for standalone flags.
    - `expires_at` number, nullable, required — Timestamp when this flag expires, or null for no expiration.
    - `feature_id` string, required — The feature ID this flag is for.
    - `feature` object — The full feature object if expanded.
      - `id` string, required — The unique identifier for this feature, used in /check and /track calls.
      - `name` string, required — Human-readable name displayed in the dashboard and billing UI.
      - `type` 'boolean' | 'metered' | 'credit_system' | 'ai_credit_system', required — Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
      - `consumable` boolean, required — For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
      - `event_names` string[] — Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
      - `credit_schema` object[] — For credit_system features: maps metered features to their credit costs.
        - `metered_feature_id` string, required — ID of the metered feature that draws from this credit system.
        - `credit_cost` number, required — Credits consumed per unit of the metered feature.
      - `model_markups` object, nullable — Per-model markup overrides for AI credit systems.
      - `default_markup` number — Default percentage markup for AI credit systems. Use -100 to make usage free.
      - `provider_markups` object, nullable — Per-provider default markup percentages for AI credit systems.
      - `display` object — Display names for the feature in billing UI and customer-facing components.
        - `singular` string, nullable — Singular form for UI display (e.g., 'API call', 'seat').
        - `plural` string, nullable — Plural form for UI display (e.g., 'API calls', 'seats').
      - `archived` boolean, required — Whether the feature is archived and hidden from the dashboard.
  - `preview` object — Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.
    - `scenario` 'usage_limit' | 'feature_flag', required — The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan.
    - `title` string, required — A title suitable for displaying in a paywall or upgrade modal.
    - `message` string, required — A message explaining why access was denied.
    - `feature_id` string, required — The ID of the feature that was checked.
    - `feature_name` string, required — The display name of the feature.
    - `products` object[], required — Products that would grant access to this feature. Use to display upgrade options.
      - `id` string, required — The ID of the product you set when creating the product
      - `name` string, required — The name of the product
      - `group` string, nullable, required — Product group which this product belongs to
      - `env` 'sandbox' | 'live', required — The environment of the product
      - `is_add_on` boolean, required — Whether the product is an add-on and can be purchased alongside other products
      - `is_default` boolean, required — Whether the product is the default product
      - `archived` boolean, required — Whether this product has been archived and is no longer available
      - `version` number, required — The current version of the product
      - `created_at` number, required — The timestamp of when the product was created in milliseconds since epoch
      - `items` object[], required — Array of product items that define the product's features and pricing
        - `type` 'feature' | 'priced_feature' | 'price', nullable — The type of the product item
        - `feature_id` string, nullable — The feature ID of the product item. If the item is a fixed price, should be `null`
        - `feature_type` 'single_use' | 'continuous_use' | 'boolean' | 'static', nullable — Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats.
        - `included_usage` union — The amount of usage included for this feature.
          - number
          - 'inf'
        - `interval` 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', nullable — The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off.
        - `interval_count` number, nullable — The interval count of the product item.
        - `price` number, nullable — The price of the product item. Should be `null` if tiered pricing is set.
        - `tiers` unknown[], nullable — Tiered pricing for the product item. Not applicable for fixed price items.
          - unknown
        - `tier_behavior` 'graduated' | 'volume', nullable — How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated.
        - `usage_model` 'prepaid' | 'pay_per_use', nullable — Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
        - `billing_units` number, nullable — The amount per billing unit (eg. $9 / 250 units)
        - `reset_usage_when_enabled` boolean, nullable — Whether the usage should be reset when the product is enabled.
        - `entity_feature_id` string, nullable — The entity feature ID of the product item if applicable.
        - `display` object, nullable — The display of the product item.
          - `primary_text` string, required
          - `secondary_text` string, nullable
        - `quantity` number, nullable — Used in customer context. Quantity of the feature the customer has prepaid for.
        - `next_cycle_quantity` number, nullable — Used in customer context. Quantity of the feature the customer will prepay for in the next cycle.
        - `config` object, nullable — Configuration for rollover and proration behavior of the feature.
          - `rollover` object, nullable
            - `max` number, nullable
            - `max_percentage` number, nullable
            - `duration` 'month' | 'forever'
            - `length` number, required
          - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', nullable
          - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', nullable
      - `free_trial` object, nullable, required — Free trial configuration for this product, if available
        - `duration` 'day' | 'month' | 'year', required — The duration type of the free trial
        - `length` number, required — The length of the duration type specified
        - `unique_fingerprint` boolean, required — Whether the free trial is limited to one per customer fingerprint
        - `card_required` boolean, required — Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file.
        - `on_end` 'bill' | 'revert', nullable — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
        - `trial_available` boolean, nullable — Used in customer context. Whether the free trial is available for the customer if they were to attach the product.
      - `base_variant_id` string, nullable, required — ID of the base variant this product is derived from
      - `billing_controls` object — Plan-level billing controls used as customer defaults
        - `auto_topups` object[] — List of auto top-up configurations per feature.
          - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up.
          - `enabled` boolean — Whether auto top-up is enabled.
          - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased.
          - `quantity` number, required — Amount of credits to add per auto top-up.
          - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur.
            - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window.
            - `interval_count` number — Number of intervals in the purchase limit window.
            - `limit` number, required — Maximum number of auto top-ups allowed within the interval.
          - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging.
        - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend).
          - `feature_id` string — Optional feature ID this spend limit applies to.
          - `enabled` boolean — Whether the overage spend limit is enabled.
          - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
          - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
          - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
        - `usage_limits` object[] — List of hard usage caps per feature (max units per interval).
          - `feature_id` string, required — The feature this usage limit applies to.
          - `enabled` boolean — Whether this usage limit is enabled.
          - `limit` number, required — Maximum units allowed per interval.
          - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle.
          - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
            - `properties` object, required
        - `usage_alerts` object[] — List of usage alert configurations per feature.
          - `feature_id` string — The feature ID this alert applies to.
          - `enabled` boolean — Whether this usage alert is enabled.
          - `threshold` number, required — The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
          - `threshold_type` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
          - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature.
        - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
          - `feature_id` string, required — The feature ID this overage allowed control applies to.
          - `enabled` boolean — Whether overage is allowed for this feature.
      - `scenario` 'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'update_prepaid_quantity' | 'downgrade' | 'cancel' | 'expired' | 'past_due' — Scenario for when this product is used in attach flows
      - `properties` object
        - `is_free` boolean, required — True if the product has no base price or usage prices
        - `is_one_off` boolean, required — True if the product only contains a one-time price
        - `interval_group` string, nullable — The billing interval group for recurring products (e.g., 'monthly', 'yearly')
        - `has_trial` boolean, nullable — True if the product includes a free trial
        - `updateable` boolean, nullable — True if the product can be updated after creation (only applicable if there are prepaid recurring prices)

## Other responses

- `202` — Accepted. Autumn is experiencing degraded service from a downstream provider, so access was allowed fail-open.

---

[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/versions/29536933c0dc/schema)