> ## Documentation Index
> Fetch the complete documentation index at: https://autumn-b9b4c0fb-dev.mintlify.site/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.
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.
How to handle a lock that exceeds the available balance. "reject" (default) returns allowed: false and reserves nothing. "cap" reserves only what fits and returns allowed: true. "overflow" reserves the full value: the balance can go negative, though spend limits still apply. balances.finalize reuses the behavior chosen here.
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 classic credit systems: maps metered features to flat or graduated credit costs.
ID of the metered feature that draws from this credit system.
Number of metered-feature units priced together. Defaults to one when omitted.
Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Multiplies the matched rate. All matching multipliers stack.
Added to the rate after every factor is applied, in credits per billing-unit group.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Credits consumed per billing-unit group.
Whether usage of this classic credit system should be itemized as invoice credits.
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.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
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 originally rolled over from a previous period, before any of it was consumed.
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 classic credit systems: maps metered features to flat or graduated credit costs.
ID of the metered feature that draws from this credit system.
Number of metered-feature units priced together. Defaults to one when omitted.
Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Multiplies the matched rate. All matching multipliers stack.
Added to the rate after every factor is applied, in credits per billing-unit group.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Credits consumed per billing-unit group.
Whether usage of this classic credit system should be itemized as invoice credits.
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.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
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 originally rolled over from a previous period, before any of it was consumed.
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 classic credit systems: maps metered features to flat or graduated credit costs.
ID of the metered feature that draws from this credit system.
Number of metered-feature units priced together. Defaults to one when omitted.
Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Multiplies the matched rate. All matching multipliers stack.
Added to the rate after every factor is applied, in credits per billing-unit group.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Credits consumed per billing-unit group.
Whether usage of this classic credit system should be itemized as invoice credits.
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.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
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.
Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.
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.
What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.
Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.
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.4.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.4.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.
overage_behavior:
description: >-
How to handle a lock that exceeds the available balance.
"reject" (default) returns allowed: false and reserves
nothing. "cap" reserves only what fits and returns
allowed: true. "overflow" reserves the full value: the
balance can go negative, though spend limits still
apply. balances.finalize reuses the behavior chosen
here.
enum:
- cap
- overflow
type: string
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:
anyOf:
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- metered_feature_id
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
- type: object
properties:
metered_feature_id:
const: ''
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
description: >-
For classic credit systems: maps metered
features to flat or graduated credit costs.
invoice_credit:
type: boolean
description: >-
Whether usage of this classic credit system
should be itemized as invoice credits.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
pattern: .+\/.+
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.
processors:
type: object
properties:
stripe:
type: object
properties:
product_id:
type: string
description: >-
Stripe product ID this feature's usage
prices bill under.
meter_id:
type: string
description: >-
Stripe meter ID used to create this
feature's metered price.
description: >-
Processor mappings for this feature. Present
when a Stripe product or meter is set.
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
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.
anchor:
enum:
- billing_cycle
- utc
type: string
description: >-
Window alignment. 'billing_cycle' phases
the interval to the customer's renewal
time; 'utc' aligns to the UTC calendar.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: string
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.
basis:
enum:
- balance
- included
- recurring
- usage_limit
type: string
default: balance
description: >-
What 100% means. balance: every grant on
the feature. included: the plan
allowance only. recurring: grants that
reset. usage_limit: the cap of the usage
limit with the same feature and filter.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: string
required:
- properties
description: >-
Only valid with basis usage_limit.
Points the alert at the usage limit
carrying the same filter.
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:
anyOf:
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- metered_feature_id
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
- type: object
properties:
metered_feature_id:
const: ''
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
description: >-
For classic credit systems: maps metered
features to flat or graduated credit costs.
invoice_credit:
type: boolean
description: >-
Whether usage of this classic credit system
should be itemized as invoice credits.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
pattern: .+\/.+
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.
processors:
type: object
properties:
stripe:
type: object
properties:
product_id:
type: string
description: >-
Stripe product ID this feature's usage
prices bill under.
meter_id:
type: string
description: >-
Stripe meter ID used to create this
feature's metered price.
description: >-
Processor mappings for this feature. Present
when a Stripe product or meter is set.
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
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.
anchor:
enum:
- billing_cycle
- utc
type: string
description: >-
Window alignment. 'billing_cycle' phases
the interval to the customer's renewal
time; 'utc' aligns to the UTC calendar.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: string
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.
basis:
enum:
- balance
- included
- recurring
- usage_limit
type: string
default: balance
description: >-
What 100% means. balance: every grant on
the feature. included: the plan
allowance only. recurring: grants that
reset. usage_limit: the cap of the usage
limit with the same feature and filter.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: string
required:
- properties
description: >-
Only valid with basis usage_limit.
Points the alert at the usage limit
carrying the same filter.
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:
anyOf:
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws from this credit
system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced together.
Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group when
this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties. The most
specific match sets the rate; with no match the item's
own rate applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to. Every
key must equal the tracked property, compared as
strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All matching
multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is applied,
in credits per billing-unit group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event properties. Every
match applies: factors multiply, then adds are summed.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be 'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group within
this tier.
required:
- to
- credit_cost
required:
- metered_feature_id
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws from this credit
system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced together.
Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group when
this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties. The most
specific match sets the rate; with no match the item's
own rate applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to. Every
key must equal the tracked property, compared as
strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All matching
multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is applied,
in credits per billing-unit group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event properties. Every
match applies: factors multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
- type: object
properties:
metered_feature_id:
const: ''
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced together.
Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to.
Every key must equal the tracked property,
compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that match
the same number of keys. Higher wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group when
this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties. The most
specific match sets the rate; with no match the item's
own rate applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description: >-
Event properties this entry applies to. Every
key must equal the tracked property, compared as
strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All matching
multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is applied,
in credits per billing-unit group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event properties. Every
match applies: factors multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
description: >-
For classic credit systems: maps metered features to flat or
graduated credit costs.
invoice_credit:
type: boolean
description: >-
Whether usage of this classic credit system should be itemized
as invoice credits.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
pattern: .+\/.+
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.
processors:
type: object
properties:
stripe:
type: object
properties:
product_id:
type: string
description: >-
Stripe product ID this feature's usage prices bill
under.
meter_id:
type: string
description: >-
Stripe meter ID used to create this feature's metered
price.
description: >-
Processor mappings for this feature. Present when a Stripe
product or meter is set.
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:
granted:
type: number
description: >-
Amount originally rolled over from a previous period, before
any of it was consumed.
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:
- granted
- 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
````