import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.check({
customerId: "cus_123",
featureId: "messages",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.check(
customer_id="cus_123",
feature_id="messages",
)curl --request POST \
--url https://api.useautumn.com/v1/balances.check \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"feature_id": "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 Permissions
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.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.check({
customerId: "cus_123",
featureId: "messages",
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.check(
customer_id="cus_123",
feature_id="messages",
)curl --request POST \
--url https://api.useautumn.com/v1/balances.check \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"feature_id": "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
}
]
}
}
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`);
const { allowed } = await autumn.check({
customerId: "cus_123",
featureId: "api_calls",
requiredBalance: 1,
sendEvent: true // Deducts usage if allowed
});
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
The ID of the customer.
The ID of the feature.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
Additional properties to attach to the usage event if send_event is true.
Show child attributes
Show child attributes
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.
Reserve units of a feature upfront by passing a lock_id, then call balances.finalize to confirm or release the hold.
Show child attributes
Show child attributes
If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
Response
OK
Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
The ID of the customer that was checked.
The customer's balance for this feature. Null if the customer has no balance for this feature.
Show child attributes
Show child attributes
{
"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
}
]
}
The flag associated with this check, if any.
Show child attributes
Show child attributes
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "dashboard"
}
The ID of the entity, if an entity-scoped check was performed.
The required balance that was checked against.
Map of feature_id to balance for the checked feature and any related features (e.g. linked credit systems).
Show child attributes
Show child attributes
Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.
Show child attributes
Show child attributes