---
title: "Check Permissions"
openapi: "openapi POST /v1/balances.check"
---

import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";

<Note>
  Check determines if a customer has access to a feature based on their current balance. Returns `allowed: true` if they have sufficient balance, the feature is unlimited, or it's a boolean feature included in their plan.
</Note>

### Common Use Cases

<CodeGroup>

```typescript Check feature access
const { allowed, balance } = await autumn.check({
  customerId: "cus_123",
  featureId: "ai_messages"
});

if (!allowed) {
  // Show upgrade prompt or paywall
}

console.log(`You have ${balance.remaining} messages left`);
```

```typescript Check and track atomically
const { allowed } = await autumn.check({
  customerId: "cus_123",
  featureId: "api_calls",
  requiredBalance: 1,
  sendEvent: true // Deducts usage if allowed
});
```

</CodeGroup>

### Body Parameters

<DynamicParamField body="customer_id" type="string" required>
  The ID of the customer.
</DynamicParamField>

<DynamicParamField body="feature_id" type="string" required>
  The ID of the feature.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
</DynamicParamField>

<DynamicParamField body="required_balance" type="number">
  Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
</DynamicParamField>

<DynamicParamField body="properties" type="object">
  Additional properties to attach to the usage event if send_event is true.
</DynamicParamField>

<DynamicParamField body="send_event" type="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.
</DynamicParamField>

<DynamicParamField body="with_preview" type="boolean">
  If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
</DynamicParamField>


### Response

<DynamicResponseField name="allowed" type="boolean">
  Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
</DynamicResponseField>

<DynamicResponseField name="customer_id" type="string">
  The ID of the customer that was checked.
</DynamicResponseField>

<DynamicResponseField name="entity_id" type="string | null">
  The ID of the entity, if an entity-scoped check was performed.
</DynamicResponseField>

<DynamicResponseField name="required_balance" type="number">
  The required balance that was checked against.
</DynamicResponseField>

<DynamicResponseField name="balance" type="object | null">
  The customer's balance for this feature. Null if the customer has no balance for this feature.
  <Expandable title="properties">
    <DynamicResponseField name="feature_id" type="string">
      The feature ID this balance is for.
    </DynamicResponseField>

    <DynamicResponseField name="feature" type="object">
      The full feature object if expanded.
      <Expandable title="properties">
        <DynamicResponseField name="id" type="string">
          The unique identifier for this feature, used in /check and /track calls.
        </DynamicResponseField>

        <DynamicResponseField name="name" type="string">
          Human-readable name displayed in the dashboard and billing UI.
        </DynamicResponseField>

        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'">
          Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools.
        </DynamicResponseField>

        <DynamicResponseField name="consumable" type="boolean">
          For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
        </DynamicResponseField>

        <DynamicResponseField name="event_names" type="string[]">
          Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
        </DynamicResponseField>

        <DynamicResponseField name="credit_schema" type="object[]">
          For credit_system features: maps metered features to their credit costs.
          <Expandable title="properties">
            <DynamicResponseField name="metered_feature_id" type="string">
              ID of the metered feature that draws from this credit system.
            </DynamicResponseField>

            <DynamicResponseField name="credit_cost" type="number">
              Credits consumed per unit of the metered feature.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="display" type="object">
          Display names for the feature in billing UI and customer-facing components.
          <Expandable title="properties">
            <DynamicResponseField name="singular" type="string | null">
              Singular form for UI display (e.g., 'API call', 'seat').
            </DynamicResponseField>

            <DynamicResponseField name="plural" type="string | null">
              Plural form for UI display (e.g., 'API calls', 'seats').
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="archived" type="boolean">
          Whether the feature is archived and hidden from the dashboard.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="granted" type="number">
      Total balance granted (included + prepaid).
    </DynamicResponseField>

    <DynamicResponseField name="remaining" type="number">
      Remaining balance available for use.
    </DynamicResponseField>

    <DynamicResponseField name="usage" type="number">
      Total usage consumed in the current period.
    </DynamicResponseField>

    <DynamicResponseField name="unlimited" type="boolean">
      Whether this feature has unlimited usage.
    </DynamicResponseField>

    <DynamicResponseField name="overage_allowed" type="boolean">
      Whether usage beyond the granted balance is allowed (with overage charges).
    </DynamicResponseField>

    <DynamicResponseField name="max_purchase" type="number | null">
      Maximum quantity that can be purchased as a top-up, or null for unlimited.
    </DynamicResponseField>

    <DynamicResponseField name="next_reset_at" type="number | null">
      Timestamp when the balance will reset, or null for no reset.
    </DynamicResponseField>

    <DynamicResponseField name="breakdown" type="object[]">
      Detailed breakdown of balance sources when stacking multiple plans or grants.
      <Expandable title="properties">
        <DynamicResponseField name="id" type="string">
          The unique identifier for this balance breakdown.
        </DynamicResponseField>

        <DynamicResponseField name="plan_id" type="string | null">
          The plan ID this balance originates from, or null for standalone balances.
        </DynamicResponseField>

        <DynamicResponseField name="included_grant" type="number">
          Amount granted from the plan's included usage.
        </DynamicResponseField>

        <DynamicResponseField name="prepaid_grant" type="number">
          Amount granted from prepaid purchases or top-ups.
        </DynamicResponseField>

        <DynamicResponseField name="remaining" type="number">
          Remaining balance available for use.
        </DynamicResponseField>

        <DynamicResponseField name="usage" type="number">
          Amount consumed in the current period.
        </DynamicResponseField>

        <DynamicResponseField name="unlimited" type="boolean">
          Whether this balance has unlimited usage.
        </DynamicResponseField>

        <DynamicResponseField name="reset" type="object | null">
          Reset configuration for this balance, or null if no reset.
          <Expandable title="properties">
            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="number">
              Number of intervals between resets (eg. 2 for bi-monthly).
            </DynamicResponseField>

            <DynamicResponseField name="resets_at" type="number | null">
              Timestamp when the balance will next reset.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="price" type="object | null">
          Pricing configuration if this balance has usage-based pricing.
          <Expandable title="properties">
            <DynamicResponseField name="amount" type="number">
              The per-unit price amount.
            </DynamicResponseField>

            <DynamicResponseField name="tiers" type="object[]">
              Tiered pricing configuration if applicable.
              <Expandable title="properties">
                <DynamicResponseField name="to" type="number" />

                <DynamicResponseField name="amount" type="number" />

                <DynamicResponseField name="flat_amount" type="number | null" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'">
              How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
            </DynamicResponseField>

            <DynamicResponseField name="billing_units" type="number">
              The number of units per billing increment (eg. $9 / 250 units).
            </DynamicResponseField>

            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
              Whether usage is prepaid or billed pay-per-use.
            </DynamicResponseField>

            <DynamicResponseField name="max_purchase" type="number | null">
              Maximum quantity that can be purchased, or null for unlimited.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="expires_at" type="number | null">
          Timestamp when this balance expires, or null for no expiration.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="rollovers" type="object[]">
      Rollover balances carried over from previous periods.
      <Expandable title="properties">
        <DynamicResponseField name="balance" type="number">
          Amount of balance rolled over from a previous period.
        </DynamicResponseField>

        <DynamicResponseField name="expires_at" type="number">
          Timestamp when the rollover balance expires.
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="preview" type="object">
  Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.
  <Expandable title="properties">
    <DynamicResponseField name="scenario" type="'usage_limit' | 'feature_flag'">
      The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan.
    </DynamicResponseField>

    <DynamicResponseField name="title" type="string">
      A title suitable for displaying in a paywall or upgrade modal.
    </DynamicResponseField>

    <DynamicResponseField name="message" type="string">
      A message explaining why access was denied.
    </DynamicResponseField>

    <DynamicResponseField name="feature_id" type="string">
      The ID of the feature that was checked.
    </DynamicResponseField>

    <DynamicResponseField name="feature_name" type="string">
      The display name of the feature.
    </DynamicResponseField>

    <DynamicResponseField name="products" type="object[]">
      Products that would grant access to this feature. Use to display upgrade options.
      <Expandable title="properties">
        <DynamicResponseField name="id" type="string">
          The ID of the product you set when creating the product
        </DynamicResponseField>

        <DynamicResponseField name="name" type="string">
          The name of the product
        </DynamicResponseField>

        <DynamicResponseField name="group" type="string | null">
          Product group which this product belongs to
        </DynamicResponseField>

        <DynamicResponseField name="env" type="'sandbox' | 'live'">
          The environment of the product
        </DynamicResponseField>

        <DynamicResponseField name="is_add_on" type="boolean">
          Whether the product is an add-on and can be purchased alongside other products
        </DynamicResponseField>

        <DynamicResponseField name="is_default" type="boolean">
          Whether the product is the default product
        </DynamicResponseField>

        <DynamicResponseField name="archived" type="boolean">
          Whether this product has been archived and is no longer available
        </DynamicResponseField>

        <DynamicResponseField name="version" type="number">
          The current version of the product
        </DynamicResponseField>

        <DynamicResponseField name="created_at" type="number">
          The timestamp of when the product was created in milliseconds since epoch
        </DynamicResponseField>

        <DynamicResponseField name="items" type="object[]">
          Array of product items that define the product's features and pricing
          <Expandable title="properties">
            <DynamicResponseField name="type" type="'feature' | 'priced_feature' | 'price'">
              The type of the product item
            </DynamicResponseField>

            <DynamicResponseField name="feature_id" type="string | null">
              The feature ID of the product item. If the item is a fixed price, should be `null`
            </DynamicResponseField>

            <DynamicResponseField name="feature_type" type="'single_use' | 'continuous_use' | 'boolean' | 'static'">
              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.
            </DynamicResponseField>

            <DynamicResponseField name="included_usage" type="number | null">
              The amount of usage included for this feature.
            </DynamicResponseField>

            <DynamicResponseField name="interval" type="'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              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.
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="number | null">
              The interval count of the product item.
            </DynamicResponseField>

            <DynamicResponseField name="price" type="number | null">
              The price of the product item. Should be `null` if tiered pricing is set.
            </DynamicResponseField>

            <DynamicResponseField name="tiers" type="object[] | null">
              Tiered pricing for the product item. Not applicable for fixed price items.
              <Expandable title="properties">
                <DynamicResponseField name="to" type="number">
                  The maximum amount of usage for this tier.
                </DynamicResponseField>

                <DynamicResponseField name="amount" type="number">
                  The price of the product item for this tier.
                </DynamicResponseField>

                <DynamicResponseField name="flat_amount" type="number | null">
                  A flat fee charged for this tier, in addition to the per-unit amount.
                </DynamicResponseField>

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'">
              How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated.
            </DynamicResponseField>

            <DynamicResponseField name="usage_model" type="'prepaid' | 'pay_per_use'">
              Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
            </DynamicResponseField>

            <DynamicResponseField name="billing_units" type="number | null">
              The amount per billing unit (eg. $9 / 250 units)
            </DynamicResponseField>

            <DynamicResponseField name="reset_usage_when_enabled" type="boolean | null">
              Whether the usage should be reset when the product is enabled.
            </DynamicResponseField>

            <DynamicResponseField name="entity_feature_id" type="string | null">
              The entity feature ID of the product item if applicable.
            </DynamicResponseField>

            <DynamicResponseField name="display" type="object | null">
              The display of the product item.
              <Expandable title="properties">
                <DynamicResponseField name="primary_text" type="string" />

                <DynamicResponseField name="secondary_text" type="string | null" />

              </Expandable>
            </DynamicResponseField>

            <DynamicResponseField name="quantity" type="number | null">
              Used in customer context. Quantity of the feature the customer has prepaid for.
            </DynamicResponseField>

            <DynamicResponseField name="next_cycle_quantity" type="number | null">
              Used in customer context. Quantity of the feature the customer will prepay for in the next cycle.
            </DynamicResponseField>

            <DynamicResponseField name="config" type="object | null">
              Configuration for rollover and proration behavior of the feature.
              <Expandable title="properties">
                <DynamicResponseField name="rollover" type="object | null">
                  <Expandable title="properties">
                    <DynamicResponseField name="max" type="number | null" />

                    <DynamicResponseField name="duration" type="'month' | 'forever'" />

                    <DynamicResponseField name="length" type="number" />

                  </Expandable>
                </DynamicResponseField>

                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />

                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />

              </Expandable>
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="free_trial" type="object | null">
          Free trial configuration for this product, if available
          <Expandable title="properties">
            <DynamicResponseField name="duration" type="'day' | 'month' | 'year'">
              The duration type of the free trial
            </DynamicResponseField>

            <DynamicResponseField name="length" type="number">
              The length of the duration type specified
            </DynamicResponseField>

            <DynamicResponseField name="unique_fingerprint" type="boolean">
              Whether the free trial is limited to one per customer fingerprint
            </DynamicResponseField>

            <DynamicResponseField name="card_required" type="boolean">
              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.
            </DynamicResponseField>

            <DynamicResponseField name="trial_available" type="boolean | null">
              Used in customer context. Whether the free trial is available for the customer if they were to attach the product.
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="base_variant_id" type="string | null">
          ID of the base variant this product is derived from
        </DynamicResponseField>

        <DynamicResponseField name="scenario" type="'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'downgrade' | 'cancel' | 'expired' | 'past_due'">
          Scenario for when this product is used in attach flows
        </DynamicResponseField>

        <DynamicResponseField name="properties" type="object">
          <Expandable title="properties">
            <DynamicResponseField name="is_free" type="boolean">
              True if the product has no base price or usage prices
            </DynamicResponseField>

            <DynamicResponseField name="is_one_off" type="boolean">
              True if the product only contains a one-time price
            </DynamicResponseField>

            <DynamicResponseField name="interval_group" type="string | null">
              The billing interval group for recurring products (e.g., 'monthly', 'yearly')
            </DynamicResponseField>

            <DynamicResponseField name="has_trial" type="boolean | null">
              True if the product includes a free trial
            </DynamicResponseField>

            <DynamicResponseField name="updateable" type="boolean | null">
              True if the product can be updated after creation (only applicable if there are prepaid recurring prices)
            </DynamicResponseField>

          </Expandable>
        </DynamicResponseField>

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "allowed": true,
  "customer_id": "cus_123",
  "entity_id": null,
  "required_balance": 1,
  "balance": {
    "feature_id": "messages",
    "granted": 100,
    "remaining": 72,
    "usage": 28,
    "unlimited": false,
    "overage_allowed": false,
    "max_purchase": null,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
        "plan_id": "pro_plan",
        "included_grant": 100,
        "prepaid_grant": 0,
        "remaining": 72,
        "usage": 28,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  }
}
```
</ResponseExample>