> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
export const DynamicResponseExample = ({json, statusCode = "200"}) => {
const toCamelCase = str => {
return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
};
const convertKeysToCamelCase = obj => {
if (Array.isArray(obj)) {
return obj.map(item => convertKeysToCamelCase(item));
}
if (obj !== null && typeof obj === "object") {
return Object.keys(obj).reduce((acc, key) => {
const camelKey = toCamelCase(key);
acc[camelKey] = convertKeysToCamelCase(obj[key]);
return acc;
}, {});
}
return obj;
};
const [isTypeScript, setIsTypeScript] = useState(() => {
if (typeof window !== "undefined") {
try {
const lang = localStorage.getItem("code");
return JSON.parse(lang) === "typescript";
} catch {
return true;
}
}
return true;
});
useEffect(() => {
const onMintlifyStorage = event => {
if (event.detail?.key === "code") {
try {
const value = JSON.parse(event.detail.value);
setIsTypeScript(value === "typescript");
} catch {}
}
};
const pollInterval = setInterval(() => {
try {
const lang = localStorage.getItem("code");
const value = JSON.parse(lang);
setIsTypeScript(value === "typescript");
} catch {}
}, 300);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, []);
const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
const snakeCaseString = JSON.stringify(json, null, 2);
const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
return
{isTypeScript ?
{camelCaseString}
:
{snakeCaseString}
}
;
};
export const DynamicResponseField = ({children, name, ...props}) => {
const convertToCamelCase = str => {
if (typeof str !== "string") return str;
return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
};
const [lang, setLang] = useState(() => {
if (typeof window !== "undefined") {
const stored = localStorage.getItem("code");
return stored || '"typescript"';
}
return '"typescript"';
});
useEffect(() => {
const onMintlifyStorage = event => {
const key = event.detail?.key;
if (key === "code") {
setLang(event.detail.value);
}
};
const pollInterval = setInterval(() => {
const current = localStorage.getItem("code");
if (current && current !== lang) {
setLang(current);
}
}, 500);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, [lang]);
const resolvedName = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(name) : name;
} catch {
return name;
}
}, [name, lang]);
return
{children}
;
};
export const DynamicParamField = ({children, body, path, ...props}) => {
const convertToCamelCase = str => {
if (typeof str !== "string") return str;
return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
};
const [lang, setLang] = useState(() => {
if (typeof window !== "undefined") {
const stored = localStorage.getItem("code");
return stored || '"typescript"';
}
return '"typescript"';
});
useEffect(() => {
const onMintlifyStorage = event => {
const key = event.detail?.key;
if (key === "code") {
setLang(event.detail.value);
}
};
const pollInterval = setInterval(() => {
const current = localStorage.getItem("code");
if (current && current !== lang) {
setLang(current);
}
}, 500);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, [lang]);
const resolvedBody = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(body) : body;
} catch {
return body;
}
}, [body, lang]);
const resolvedPath = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(path) : path;
} catch {
return path;
}
}, [path, lang]);
return
{children}
;
};
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
```typescript Check feature access theme={null}
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 theme={null}
const { allowed } = await autumn.check({
customerId: "cus_123",
featureId: "api_calls",
requiredBalance: 1,
sendEvent: true // Deducts usage if allowed
});
```
### Body Parameters
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.
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.
A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
Must be true to enable locking.
Unix timestamp (ms) when the lock automatically expires and releases the held balance.
If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
### Response
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 ID of the entity, if an entity-scoped check was performed.
The required balance that was checked against.
The customer's balance for this feature. Null if the customer has no balance for this feature.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
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.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit\_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Map of feature\_id to balance for the checked feature and any related features (e.g. linked credit systems).
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
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.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit\_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The flag associated with this check, if any.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
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.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit\_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Upgrade/upsell information when access is denied. Only present if with\_preview was true and allowed is false.
The reason access was denied. 'usage\_limit' means the customer exceeded their balance, 'feature\_flag' means the feature is not included in their plan.
A title suitable for displaying in a paywall or upgrade modal.
A message explaining why access was denied.
The ID of the feature that was checked.
The display name of the feature.
Products that would grant access to this feature. Use to display upgrade options.
The ID of the product you set when creating the product
The name of the product
Product group which this product belongs to
The environment of the product
Whether the product is an add-on and can be purchased alongside other products
Whether the product is the default product
Whether this product has been archived and is no longer available
The current version of the product
The timestamp of when the product was created in milliseconds since epoch
Array of product items that define the product's features and pricing
The type of the product item
The feature ID of the product item. If the item is a fixed price, should be `null`
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.
The amount of usage included for this feature.
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.
The interval count of the product item.
The price of the product item. Should be `null` if tiered pricing is set.
Tiered pricing for the product item. Not applicable for fixed price items.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated.
Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
The amount per billing unit (eg. \$9 / 250 units)
Whether the usage should be reset when the product is enabled.
The entity feature ID of the product item if applicable.
The display of the product item.
Used in customer context. Quantity of the feature the customer has prepaid for.
Used in customer context. Quantity of the feature the customer will prepay for in the next cycle.
Configuration for rollover and proration behavior of the feature.
Free trial configuration for this product, if available
The duration type of the free trial
The length of the duration type specified
Whether the free trial is limited to one per customer fingerprint
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.
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
Used in customer context. Whether the free trial is available for the customer if they were to attach the product.
ID of the base variant this product is derived from
Plan-level billing controls used as customer defaults
List of auto top-up configurations per feature.
The ID of the feature (credit balance) to auto top-up.
Whether auto top-up is enabled.
When the balance drops below this threshold, an auto top-up will be purchased.
Amount of credits to add per auto top-up.
Optional rate limit to cap how often auto top-ups occur.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
List of overage spend limits per feature (caps overage spend).
Optional feature ID this spend limit applies to.
Whether the overage spend limit is enabled.
How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
List of hard usage caps per feature (max units per interval).
The feature this usage limit applies to.
Whether this usage limit is enabled.
Maximum units allowed per interval.
Interval for the cap, aligned to the customer's billing cycle.
When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
List of usage alert configurations per feature.
The feature ID this alert applies to.
Whether this usage alert is enabled.
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).
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
Optional user-defined label to distinguish multiple alerts on the same feature.
List of overage allowed controls per feature. When enabled, usage can exceed balance.
The feature ID this overage allowed control applies to.
Whether overage is allowed for this feature.
Scenario for when this product is used in attach flows
True if the product has no base price or usage prices
True if the product only contains a one-time price
The billing interval group for recurring products (e.g., 'monthly', 'yearly')
True if the product includes a free trial
True if the product can be updated after creation (only applicable if there are prepaid recurring prices)
```json 200 theme={null}
{
"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
}
]
}
}
```
## OpenAPI
````yaml openapi POST /v1/balances.check
openapi: 3.1.0
info:
title: Autumn API
version: 2.3.0
servers:
- url: https://api.useautumn.com
description: Production server
security:
- secretKey: []
paths:
/v1/balances.check:
post:
description: >-
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.
operationId: check
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
default: 2.3.0
x-speakeasy-globals-hidden: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The ID of the customer.
feature_id:
type: string
description: The ID of the feature.
entity_id:
type: string
description: >-
The ID of the entity for entity-scoped balances (e.g.,
per-seat limits).
required_balance:
type: number
description: >-
Minimum balance required for access. Returns allowed: false
if the customer's balance is below this value. Defaults to
1.
properties:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Additional properties to attach to the usage event if
send_event is true.
send_event:
type: boolean
description: >-
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:
type: object
properties:
lock_id:
type: string
maxLength: 256
description: >-
A unique identifier for this lock. Used to finalize the
lock later via balances.finalize.
enabled:
const: true
description: Must be true to enable locking.
expires_at:
type: number
description: >-
Unix timestamp (ms) when the lock automatically expires
and releases the held balance.
required:
- lock_id
- enabled
description: >-
Reserve units of a feature upfront by passing a lock_id,
then call balances.finalize to confirm or release the hold.
with_preview:
type: boolean
description: >-
If true, includes upgrade/upsell information in the response
when access is denied. Useful for displaying paywalls.
required:
- customer_id
- feature_id
title: CheckParams
examples:
- customer_id: cus_123
feature_id: messages
- customer_id: cus_123
feature_id: messages
required_balance: 3
send_event: true
example:
customer_id: cus_123
feature_id: messages
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
allowed:
type: boolean
description: >-
Whether the customer is allowed to use the feature. True
if they have sufficient balance or the feature is
unlimited/boolean.
customer_id:
type: string
description: The ID of the customer that was checked.
entity_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the entity, if an entity-scoped check was
performed.
required_balance:
type: number
description: The required balance that was checked against.
balance:
anyOf:
- $ref: '#/components/schemas/Balance'
- type: 'null'
description: >-
The customer's balance for this feature. Null if the
customer has no balance for this feature.
balances:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- $ref: '#/components/schemas/Balance'
- type: 'null'
description: >-
Map of feature_id to balance for the checked feature and
any related features (e.g. linked credit systems).
flag:
anyOf:
- type: object
properties:
id:
type: string
description: The unique identifier for this flag.
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan ID this flag originates from, or null for
standalone flags.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when this flag expires, or null for no
expiration.
feature_id:
type: string
description: The feature ID this flag is for.
feature:
type: object
properties:
id:
type: string
description: >-
The unique identifier for this feature, used
in /check and /track calls.
name:
type: string
description: >-
Human-readable name displayed in the dashboard
and billing UI.
type:
enum:
- boolean
- metered
- credit_system
- ai_credit_system
type: string
description: >-
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:
type: boolean
description: >-
For metered features: true if usage resets
periodically (API calls, credits), false if
allocated persistently (seats, storage).
event_names:
type: array
items:
type: string
description: >-
Event names that trigger this feature's
balance. Allows multiple features to respond
to a single event.
credit_schema:
type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
ID of the metered feature that draws
from this credit system.
credit_cost:
type: number
description: >-
Credits consumed per unit of the metered
feature.
required:
- metered_feature_id
- credit_cost
description: >-
For credit_system features: maps metered
features to their credit costs.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
input_cost:
type: number
minimum: 0
output_cost:
type: number
minimum: 0
- type: 'null'
description: >-
Per-model markup overrides for AI credit
systems.
default_markup:
type: number
minimum: -100
description: >-
Default percentage markup for AI credit
systems. Use -100 to make usage free.
provider_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
required:
- markup
- type: 'null'
description: >-
Per-provider default markup percentages for AI
credit systems.
display:
type: object
properties:
singular:
anyOf:
- type: string
- type: 'null'
description: >-
Singular form for UI display (e.g., 'API
call', 'seat').
plural:
anyOf:
- type: string
- type: 'null'
description: >-
Plural form for UI display (e.g., 'API
calls', 'seats').
description: >-
Display names for the feature in billing UI
and customer-facing components.
archived:
type: boolean
description: >-
Whether the feature is archived and hidden
from the dashboard.
required:
- id
- name
- type
- consumable
- archived
description: The full feature object if expanded.
required:
- id
- plan_id
- expires_at
- feature_id
examples:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
plan_id: pro_plan
expires_at: null
feature_id: dashboard
- type: 'null'
description: The flag associated with this check, if any.
preview:
type: object
properties:
scenario:
enum:
- usage_limit
- feature_flag
type: string
description: >-
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:
type: string
description: >-
A title suitable for displaying in a paywall or
upgrade modal.
message:
type: string
description: A message explaining why access was denied.
feature_id:
type: string
description: The ID of the feature that was checked.
feature_name:
type: string
description: The display name of the feature.
products:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The ID of the product you set when creating the
product
name:
type: string
description: The name of the product
group:
anyOf:
- type: string
- type: 'null'
description: Product group which this product belongs to
env:
enum:
- sandbox
- live
type: string
description: The environment of the product
is_add_on:
type: boolean
description: >-
Whether the product is an add-on and can be
purchased alongside other products
is_default:
type: boolean
description: Whether the product is the default product
archived:
type: boolean
description: >-
Whether this product has been archived and is no
longer available
version:
type: number
description: The current version of the product
created_at:
type: number
description: >-
The timestamp of when the product was created in
milliseconds since epoch
items:
type: array
items:
type: object
properties:
type:
anyOf:
- enum:
- feature
- priced_feature
- price
type: string
- type: 'null'
description: The type of the product item
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The feature ID of the product item. If the
item is a fixed price, should be `null`
feature_type:
anyOf:
- enum:
- single_use
- continuous_use
- boolean
- static
type: string
- type: 'null'
description: >-
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:
anyOf:
- anyOf:
- type: number
- const: inf
- type: 'null'
description: >-
The amount of usage included for this
feature.
interval:
anyOf:
- enum:
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
- type: 'null'
description: >-
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:
anyOf:
- type: number
- type: 'null'
description: The interval count of the product item.
price:
anyOf:
- type: number
- type: 'null'
description: >-
The price of the product item. Should be
`null` if tiered pricing is set.
tiers:
anyOf:
- type: array
items:
anyOf:
- {}
- type: 'null'
- type: 'null'
description: >-
Tiered pricing for the product item. Not
applicable for fixed price items.
tier_behavior:
anyOf:
- enum:
- graduated
- volume
type: string
- type: 'null'
description: >-
How tiers are applied: graduated (split
across bands) or volume (flat rate for the
matched tier). Defaults to graduated.
usage_model:
anyOf:
- enum:
- prepaid
- pay_per_use
type: string
- type: 'null'
description: >-
Whether the feature should be prepaid
upfront or billed for how much they use
end of billing period.
billing_units:
anyOf:
- type: number
- type: 'null'
description: >-
The amount per billing unit (eg. $9 / 250
units)
reset_usage_when_enabled:
anyOf:
- type: boolean
- type: 'null'
description: >-
Whether the usage should be reset when the
product is enabled.
entity_feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The entity feature ID of the product item
if applicable.
display:
anyOf:
- type: object
properties:
primary_text:
type: string
secondary_text:
anyOf:
- type: string
- type: 'null'
required:
- primary_text
- type: 'null'
description: The display of the product item.
quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Used in customer context. Quantity of the
feature the customer has prepaid for.
next_cycle_quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Used in customer context. Quantity of the
feature the customer will prepay for in
the next cycle.
config:
anyOf:
- type: object
properties:
rollover:
anyOf:
- type: object
properties:
max:
anyOf:
- type: number
- type: 'null'
max_percentage:
anyOf:
- type: number
- type: 'null'
duration:
enum:
- month
- forever
type: string
default: month
length:
type: number
required:
- length
- type: 'null'
on_increase:
anyOf:
- enum:
- bill_immediately
- prorate_immediately
- prorate_next_cycle
- bill_next_cycle
type: string
- type: 'null'
on_decrease:
anyOf:
- enum:
- prorate
- prorate_immediately
- prorate_next_cycle
- none
- no_prorations
type: string
- type: 'null'
- type: 'null'
description: >-
Configuration for rollover and proration
behavior of the feature.
description: >-
Product item defining features and pricing
within a product
description: >-
Array of product items that define the product's
features and pricing
free_trial:
anyOf:
- type: object
properties:
duration:
enum:
- day
- month
- year
type: string
description: The duration type of the free trial
length:
type: number
description: >-
The length of the duration type
specified
unique_fingerprint:
type: boolean
description: >-
Whether the free trial is limited to one
per customer fingerprint
card_required:
type: boolean
description: >-
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:
anyOf:
- enum:
- bill
- revert
type: string
- type: 'null'
description: >-
Behavior when the trial ends. 'bill'
charges the customer (default). 'revert'
expires the trial and restores the
customer's previous plan.
trial_available:
anyOf:
- type: boolean
default: true
- type: 'null'
description: >-
Used in customer context. Whether the
free trial is available for the customer
if they were to attach the product.
required:
- duration
- length
- unique_fingerprint
- card_required
- type: 'null'
description: >-
Free trial configuration for this product, if
available
base_variant_id:
anyOf:
- type: string
- type: 'null'
description: >-
ID of the base variant this product is derived
from
billing_controls:
type: object
properties:
auto_topups:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The ID of the feature (credit balance)
to auto top-up.
enabled:
type: boolean
default: false
description: Whether auto top-up is enabled.
threshold:
type: number
minimum: 0
description: >-
When the balance drops below this
threshold, an auto top-up will be
purchased.
quantity:
type: number
minimum: 1
description: >-
Amount of credits to add per auto
top-up.
purchase_limit:
type: object
properties:
interval:
enum:
- hour
- day
- week
- month
type: string
description: >-
The time interval for the purchase limit
window.
interval_count:
type: number
minimum: 1
default: 1
description: >-
Number of intervals in the purchase
limit window.
limit:
type: number
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often
auto top-ups occur.
invoice_mode:
type: boolean
description: >-
When true, auto top-up creates a
send_invoice invoice instead of
auto-charging.
required:
- feature_id
- threshold
- quantity
description: >-
List of auto top-up configurations per
feature.
spend_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
Optional feature ID this spend limit
applies to.
enabled:
type: boolean
default: false
description: >-
Whether the overage spend limit is
enabled.
limit_type:
enum:
- absolute
- usage_percentage
type: string
description: >-
How overage_limit is interpreted: an
absolute overage cap (default) or a
percentage of the main-plan allowance.
overage_limit:
type: number
minimum: 0
description: >-
Overage cap for the feature: absolute
units, or a percent (e.g. 120) when
limit_type is usage_percentage.
skip_overage_billing:
type: boolean
description: >-
When true, overage for this feature is
not posted to Stripe. Usage tracking and
balance resets still behave normally.
description: >-
List of overage spend limits per feature
(caps overage spend).
usage_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature this usage limit applies to.
enabled:
type: boolean
default: true
description: Whether this usage limit is enabled.
limit:
type: number
minimum: 0
description: Maximum units allowed per interval.
interval:
enum:
- day
- week
- month
- year
type: string
description: >-
Interval for the cap, aligned to the
customer's billing cycle.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties: {}
required:
- properties
description: >-
When set, only usage from events whose
properties match counts toward this cap.
Omit to count all usage of the feature.
required:
- feature_id
- limit
- interval
description: >-
List of hard usage caps per feature (max
units per interval).
usage_alerts:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature ID this alert applies to.
enabled:
type: boolean
default: true
description: Whether this usage alert is enabled.
threshold:
type: number
minimum: 0
description: >-
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:
enum:
- usage
- usage_percentage
- remaining
- remaining_percentage
type: string
description: >-
Whether the threshold is an absolute
count or a percentage of the usage
allowance or remaining balance.
name:
type: string
description: >-
Optional user-defined label to
distinguish multiple alerts on the same
feature.
required:
- threshold
- threshold_type
description: >-
List of usage alert configurations per
feature.
overage_allowed:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The feature ID this overage allowed
control applies to.
enabled:
type: boolean
default: false
description: >-
Whether overage is allowed for this
feature.
required:
- feature_id
description: >-
List of overage allowed controls per
feature. When enabled, usage can exceed
balance.
description: >-
Plan-level billing controls used as customer
defaults
scenario:
enum:
- scheduled
- active
- new
- renew
- upgrade
- update_prepaid_quantity
- downgrade
- cancel
- expired
- past_due
type: string
description: >-
Scenario for when this product is used in attach
flows
properties:
type: object
properties:
is_free:
type: boolean
description: >-
True if the product has no base price or
usage prices
is_one_off:
type: boolean
description: >-
True if the product only contains a one-time
price
interval_group:
anyOf:
- type: string
- type: 'null'
description: >-
The billing interval group for recurring
products (e.g., 'monthly', 'yearly')
has_trial:
anyOf:
- type: boolean
- type: 'null'
description: True if the product includes a free trial
updateable:
anyOf:
- type: boolean
- type: 'null'
description: >-
True if the product can be updated after
creation (only applicable if there are
prepaid recurring prices)
required:
- is_free
- is_one_off
required:
- id
- name
- group
- env
- is_add_on
- is_default
- archived
- version
- created_at
- items
- free_trial
- base_variant_id
description: >-
Products that would grant access to this feature. Use
to display upgrade options.
required:
- scenario
- title
- message
- feature_id
- feature_name
- products
description: >-
Upgrade/upsell information when access is denied. Only
present if with_preview was true and allowed is false.
required:
- allowed
- customer_id
- balance
- flag
examples:
- 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
example:
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
'202':
description: >-
Accepted. Autumn is experiencing degraded service from a downstream
provider, so access was allowed fail-open.
content:
application/json:
schema:
type: object
properties:
allowed:
type: boolean
description: >-
Whether the customer is allowed to use the feature. True
if they have sufficient balance or the feature is
unlimited/boolean.
customer_id:
type: string
description: The ID of the customer that was checked.
entity_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the entity, if an entity-scoped check was
performed.
required_balance:
type: number
description: The required balance that was checked against.
balance:
anyOf:
- $ref: '#/components/schemas/Balance'
- type: 'null'
description: >-
The customer's balance for this feature. Null if the
customer has no balance for this feature.
balances:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- $ref: '#/components/schemas/Balance'
- type: 'null'
description: >-
Map of feature_id to balance for the checked feature and
any related features (e.g. linked credit systems).
flag:
anyOf:
- type: object
properties:
id:
type: string
description: The unique identifier for this flag.
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan ID this flag originates from, or null for
standalone flags.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when this flag expires, or null for no
expiration.
feature_id:
type: string
description: The feature ID this flag is for.
feature:
type: object
properties:
id:
type: string
description: >-
The unique identifier for this feature, used
in /check and /track calls.
name:
type: string
description: >-
Human-readable name displayed in the dashboard
and billing UI.
type:
enum:
- boolean
- metered
- credit_system
- ai_credit_system
type: string
description: >-
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:
type: boolean
description: >-
For metered features: true if usage resets
periodically (API calls, credits), false if
allocated persistently (seats, storage).
event_names:
type: array
items:
type: string
description: >-
Event names that trigger this feature's
balance. Allows multiple features to respond
to a single event.
credit_schema:
type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
ID of the metered feature that draws
from this credit system.
credit_cost:
type: number
description: >-
Credits consumed per unit of the metered
feature.
required:
- metered_feature_id
- credit_cost
description: >-
For credit_system features: maps metered
features to their credit costs.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
input_cost:
type: number
minimum: 0
output_cost:
type: number
minimum: 0
- type: 'null'
description: >-
Per-model markup overrides for AI credit
systems.
default_markup:
type: number
minimum: -100
description: >-
Default percentage markup for AI credit
systems. Use -100 to make usage free.
provider_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
required:
- markup
- type: 'null'
description: >-
Per-provider default markup percentages for AI
credit systems.
display:
type: object
properties:
singular:
anyOf:
- type: string
- type: 'null'
description: >-
Singular form for UI display (e.g., 'API
call', 'seat').
plural:
anyOf:
- type: string
- type: 'null'
description: >-
Plural form for UI display (e.g., 'API
calls', 'seats').
description: >-
Display names for the feature in billing UI
and customer-facing components.
archived:
type: boolean
description: >-
Whether the feature is archived and hidden
from the dashboard.
required:
- id
- name
- type
- consumable
- archived
description: The full feature object if expanded.
required:
- id
- plan_id
- expires_at
- feature_id
examples:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
plan_id: pro_plan
expires_at: null
feature_id: dashboard
- type: 'null'
description: The flag associated with this check, if any.
preview:
type: object
properties:
scenario:
enum:
- usage_limit
- feature_flag
type: string
description: >-
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:
type: string
description: >-
A title suitable for displaying in a paywall or
upgrade modal.
message:
type: string
description: A message explaining why access was denied.
feature_id:
type: string
description: The ID of the feature that was checked.
feature_name:
type: string
description: The display name of the feature.
products:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The ID of the product you set when creating the
product
name:
type: string
description: The name of the product
group:
anyOf:
- type: string
- type: 'null'
description: Product group which this product belongs to
env:
enum:
- sandbox
- live
type: string
description: The environment of the product
is_add_on:
type: boolean
description: >-
Whether the product is an add-on and can be
purchased alongside other products
is_default:
type: boolean
description: Whether the product is the default product
archived:
type: boolean
description: >-
Whether this product has been archived and is no
longer available
version:
type: number
description: The current version of the product
created_at:
type: number
description: >-
The timestamp of when the product was created in
milliseconds since epoch
items:
type: array
items:
type: object
properties:
type:
anyOf:
- enum:
- feature
- priced_feature
- price
type: string
- type: 'null'
description: The type of the product item
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The feature ID of the product item. If the
item is a fixed price, should be `null`
feature_type:
anyOf:
- enum:
- single_use
- continuous_use
- boolean
- static
type: string
- type: 'null'
description: >-
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:
anyOf:
- anyOf:
- type: number
- const: inf
- type: 'null'
description: >-
The amount of usage included for this
feature.
interval:
anyOf:
- enum:
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
- type: 'null'
description: >-
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:
anyOf:
- type: number
- type: 'null'
description: The interval count of the product item.
price:
anyOf:
- type: number
- type: 'null'
description: >-
The price of the product item. Should be
`null` if tiered pricing is set.
tiers:
anyOf:
- type: array
items:
anyOf:
- {}
- type: 'null'
- type: 'null'
description: >-
Tiered pricing for the product item. Not
applicable for fixed price items.
tier_behavior:
anyOf:
- enum:
- graduated
- volume
type: string
- type: 'null'
description: >-
How tiers are applied: graduated (split
across bands) or volume (flat rate for the
matched tier). Defaults to graduated.
usage_model:
anyOf:
- enum:
- prepaid
- pay_per_use
type: string
- type: 'null'
description: >-
Whether the feature should be prepaid
upfront or billed for how much they use
end of billing period.
billing_units:
anyOf:
- type: number
- type: 'null'
description: >-
The amount per billing unit (eg. $9 / 250
units)
reset_usage_when_enabled:
anyOf:
- type: boolean
- type: 'null'
description: >-
Whether the usage should be reset when the
product is enabled.
entity_feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The entity feature ID of the product item
if applicable.
display:
anyOf:
- type: object
properties:
primary_text:
type: string
secondary_text:
anyOf:
- type: string
- type: 'null'
required:
- primary_text
- type: 'null'
description: The display of the product item.
quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Used in customer context. Quantity of the
feature the customer has prepaid for.
next_cycle_quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Used in customer context. Quantity of the
feature the customer will prepay for in
the next cycle.
config:
anyOf:
- type: object
properties:
rollover:
anyOf:
- type: object
properties:
max:
anyOf:
- type: number
- type: 'null'
max_percentage:
anyOf:
- type: number
- type: 'null'
duration:
enum:
- month
- forever
type: string
default: month
length:
type: number
required:
- length
- type: 'null'
on_increase:
anyOf:
- enum:
- bill_immediately
- prorate_immediately
- prorate_next_cycle
- bill_next_cycle
type: string
- type: 'null'
on_decrease:
anyOf:
- enum:
- prorate
- prorate_immediately
- prorate_next_cycle
- none
- no_prorations
type: string
- type: 'null'
- type: 'null'
description: >-
Configuration for rollover and proration
behavior of the feature.
description: >-
Product item defining features and pricing
within a product
description: >-
Array of product items that define the product's
features and pricing
free_trial:
anyOf:
- type: object
properties:
duration:
enum:
- day
- month
- year
type: string
description: The duration type of the free trial
length:
type: number
description: >-
The length of the duration type
specified
unique_fingerprint:
type: boolean
description: >-
Whether the free trial is limited to one
per customer fingerprint
card_required:
type: boolean
description: >-
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:
anyOf:
- enum:
- bill
- revert
type: string
- type: 'null'
description: >-
Behavior when the trial ends. 'bill'
charges the customer (default). 'revert'
expires the trial and restores the
customer's previous plan.
trial_available:
anyOf:
- type: boolean
default: true
- type: 'null'
description: >-
Used in customer context. Whether the
free trial is available for the customer
if they were to attach the product.
required:
- duration
- length
- unique_fingerprint
- card_required
- type: 'null'
description: >-
Free trial configuration for this product, if
available
base_variant_id:
anyOf:
- type: string
- type: 'null'
description: >-
ID of the base variant this product is derived
from
billing_controls:
type: object
properties:
auto_topups:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The ID of the feature (credit balance)
to auto top-up.
enabled:
type: boolean
default: false
description: Whether auto top-up is enabled.
threshold:
type: number
minimum: 0
description: >-
When the balance drops below this
threshold, an auto top-up will be
purchased.
quantity:
type: number
minimum: 1
description: >-
Amount of credits to add per auto
top-up.
purchase_limit:
type: object
properties:
interval:
enum:
- hour
- day
- week
- month
type: string
description: >-
The time interval for the purchase limit
window.
interval_count:
type: number
minimum: 1
default: 1
description: >-
Number of intervals in the purchase
limit window.
limit:
type: number
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often
auto top-ups occur.
invoice_mode:
type: boolean
description: >-
When true, auto top-up creates a
send_invoice invoice instead of
auto-charging.
required:
- feature_id
- threshold
- quantity
description: >-
List of auto top-up configurations per
feature.
spend_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
Optional feature ID this spend limit
applies to.
enabled:
type: boolean
default: false
description: >-
Whether the overage spend limit is
enabled.
limit_type:
enum:
- absolute
- usage_percentage
type: string
description: >-
How overage_limit is interpreted: an
absolute overage cap (default) or a
percentage of the main-plan allowance.
overage_limit:
type: number
minimum: 0
description: >-
Overage cap for the feature: absolute
units, or a percent (e.g. 120) when
limit_type is usage_percentage.
skip_overage_billing:
type: boolean
description: >-
When true, overage for this feature is
not posted to Stripe. Usage tracking and
balance resets still behave normally.
description: >-
List of overage spend limits per feature
(caps overage spend).
usage_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature this usage limit applies to.
enabled:
type: boolean
default: true
description: Whether this usage limit is enabled.
limit:
type: number
minimum: 0
description: Maximum units allowed per interval.
interval:
enum:
- day
- week
- month
- year
type: string
description: >-
Interval for the cap, aligned to the
customer's billing cycle.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties: {}
required:
- properties
description: >-
When set, only usage from events whose
properties match counts toward this cap.
Omit to count all usage of the feature.
required:
- feature_id
- limit
- interval
description: >-
List of hard usage caps per feature (max
units per interval).
usage_alerts:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature ID this alert applies to.
enabled:
type: boolean
default: true
description: Whether this usage alert is enabled.
threshold:
type: number
minimum: 0
description: >-
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:
enum:
- usage
- usage_percentage
- remaining
- remaining_percentage
type: string
description: >-
Whether the threshold is an absolute
count or a percentage of the usage
allowance or remaining balance.
name:
type: string
description: >-
Optional user-defined label to
distinguish multiple alerts on the same
feature.
required:
- threshold
- threshold_type
description: >-
List of usage alert configurations per
feature.
overage_allowed:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The feature ID this overage allowed
control applies to.
enabled:
type: boolean
default: false
description: >-
Whether overage is allowed for this
feature.
required:
- feature_id
description: >-
List of overage allowed controls per
feature. When enabled, usage can exceed
balance.
description: >-
Plan-level billing controls used as customer
defaults
scenario:
enum:
- scheduled
- active
- new
- renew
- upgrade
- update_prepaid_quantity
- downgrade
- cancel
- expired
- past_due
type: string
description: >-
Scenario for when this product is used in attach
flows
properties:
type: object
properties:
is_free:
type: boolean
description: >-
True if the product has no base price or
usage prices
is_one_off:
type: boolean
description: >-
True if the product only contains a one-time
price
interval_group:
anyOf:
- type: string
- type: 'null'
description: >-
The billing interval group for recurring
products (e.g., 'monthly', 'yearly')
has_trial:
anyOf:
- type: boolean
- type: 'null'
description: True if the product includes a free trial
updateable:
anyOf:
- type: boolean
- type: 'null'
description: >-
True if the product can be updated after
creation (only applicable if there are
prepaid recurring prices)
required:
- is_free
- is_one_off
required:
- id
- name
- group
- env
- is_add_on
- is_default
- archived
- version
- created_at
- items
- free_trial
- base_variant_id
description: >-
Products that would grant access to this feature. Use
to display upgrade options.
required:
- scenario
- title
- message
- feature_id
- feature_name
- products
description: >-
Upgrade/upsell information when access is denied. Only
present if with_preview was true and allowed is false.
required:
- allowed
- customer_id
- balance
- flag
examples:
- 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
example:
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
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.check({
customerId: "cus_123",
featureId: "messages",
});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.check(
customer_id="cus_123",
feature_id="messages",
)
components:
schemas:
Balance:
type: object
properties:
feature_id:
type: string
description: The feature ID this balance is for.
feature:
type: object
properties:
id:
type: string
description: >-
The unique identifier for this feature, used in /check and
/track calls.
name:
type: string
description: Human-readable name displayed in the dashboard and billing UI.
type:
enum:
- boolean
- metered
- credit_system
- ai_credit_system
type: string
description: >-
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:
type: boolean
description: >-
For metered features: true if usage resets periodically (API
calls, credits), false if allocated persistently (seats,
storage).
event_names:
type: array
items:
type: string
description: >-
Event names that trigger this feature's balance. Allows multiple
features to respond to a single event.
credit_schema:
type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
ID of the metered feature that draws from this credit
system.
credit_cost:
type: number
description: Credits consumed per unit of the metered feature.
required:
- metered_feature_id
- credit_cost
description: >-
For credit_system features: maps metered features to their
credit costs.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
input_cost:
type: number
minimum: 0
output_cost:
type: number
minimum: 0
- type: 'null'
description: Per-model markup overrides for AI credit systems.
default_markup:
type: number
minimum: -100
description: >-
Default percentage markup for AI credit systems. Use -100 to
make usage free.
provider_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
required:
- markup
- type: 'null'
description: Per-provider default markup percentages for AI credit systems.
display:
type: object
properties:
singular:
anyOf:
- type: string
- type: 'null'
description: Singular form for UI display (e.g., 'API call', 'seat').
plural:
anyOf:
- type: string
- type: 'null'
description: Plural form for UI display (e.g., 'API calls', 'seats').
description: >-
Display names for the feature in billing UI and customer-facing
components.
archived:
type: boolean
description: Whether the feature is archived and hidden from the dashboard.
required:
- id
- name
- type
- consumable
- archived
description: The full feature object if expanded.
granted:
type: number
description: Total balance granted (included + prepaid).
remaining:
type: number
minimum: 0
description: Remaining balance available for use.
usage:
type: number
description: Total usage consumed in the current period.
unlimited:
type: boolean
description: Whether this feature has unlimited usage.
overage_allowed:
type: boolean
description: >-
Whether usage beyond the granted balance is allowed (with overage
charges).
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum quantity that can be purchased as a top-up, or null for
unlimited.
next_reset_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the balance will reset, or null for no reset.
breakdown:
type: array
items:
type: object
properties:
id:
type: string
default: ''
description: The unique identifier for this balance breakdown.
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan ID this balance originates from, or null for
standalone balances.
included_grant:
type: number
description: Amount granted from the plan's included usage.
prepaid_grant:
type: number
description: Amount granted from prepaid purchases or top-ups.
remaining:
type: number
description: Remaining balance available for use.
usage:
type: number
description: Amount consumed in the current period.
unlimited:
type: boolean
description: Whether this balance has unlimited usage.
reset:
anyOf:
- type: object
properties:
interval:
anyOf:
- enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
- const: multiple
description: >-
The reset interval (hour, day, week, month, etc.) or
'multiple' if combined from different intervals.
interval_count:
type: number
description: >-
Number of intervals between resets (eg. 2 for
bi-monthly).
resets_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the balance will next reset.
required:
- interval
- resets_at
- type: 'null'
description: Reset configuration for this balance, or null if no reset.
price:
anyOf:
- type: object
properties:
amount:
type: number
description: The per-unit price amount.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
required:
- to
- amount
description: Tiered pricing configuration if applicable.
tier_behavior:
enum:
- graduated
- volume
type: string
description: >-
How tiers are applied: graduated (split across bands)
or volume (flat rate for the matched tier).
billing_units:
type: number
description: >-
The number of units per billing increment (eg. $9 /
250 units).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: Whether usage is prepaid or billed pay-per-use.
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum quantity that can be purchased, or null for
unlimited.
required:
- billing_units
- billing_method
- max_purchase
- type: 'null'
description: Pricing configuration if this balance has usage-based pricing.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when this balance expires, or null for no
expiration.
required:
- plan_id
- included_grant
- prepaid_grant
- remaining
- usage
- unlimited
- reset
- price
- expires_at
description: >-
Detailed breakdown of balance sources when stacking multiple plans
or grants.
rollovers:
type: array
items:
type: object
properties:
balance:
type: number
description: Amount of balance rolled over from a previous period.
expires_at:
type: number
description: Timestamp when the rollover balance expires.
required:
- balance
- expires_at
description: Rollover balances carried over from previous periods.
required:
- feature_id
- granted
- remaining
- usage
- unlimited
- overage_allowed
- max_purchase
- next_reset_at
examples:
- 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
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````