Skip to main content
POST
/
v1
/
balances.check
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.check({
  customerId: "cus_123",
  featureId: "messages",
});
{
  "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
      }
    ]
  }
}
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.

​
Common Use Cases

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`);

​
Body Parameters

​
Response

{
  "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
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.1
required

Body

application/json
​
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.

​
with_preview
boolean

If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.

Response

200 - application/json

OK

​
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.

​
balance
object
required

The customer's balance for this feature. Null if the customer has no balance for this feature.

Example:
{
  "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
    }
  ]
}
​
entity_id
string | null

The ID of the entity, if an entity-scoped check was performed.

​
required_balance
number

The required balance that was checked against.

​
preview
object

Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.