---
title: "Get Entity"
openapi: "openapi POST /v1/entities.get"
---
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
### Body Parameters
The ID of the customer to create the entity for.
The ID of the entity.
### Response
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
The unique identifier of this subscription. If a subscription_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if expanded.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null for unlimited rollover.
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
When rolled over units expire.
Number of periods before expiry.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Miscellaneous plan-level configuration flags.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
Whether the customer's active instance of this plan is set to cancel.
Whether the customer is currently on a free trial of this plan.
The action that would occur if this plan were attached to the customer.
The unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
The full plan object if expanded.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null for unlimited rollover.
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
When rolled over units expire.
Number of periods before expiry.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Miscellaneous plan-level configuration flags.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
Whether the customer's active instance of this plan is set to cancel.
Whether the customer is currently on a free trial of this plan.
The action that would occur if this plan were attached to the customer.
The unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. $9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Billing controls for the entity.
List of overage spend limits per feature.
Optional feature ID this spend limit applies to.
Whether this spend limit is enabled.
Maximum allowed overage spend for the target feature.
List of usage alert configurations per feature.
The feature ID this alert applies to.
Whether this usage alert is enabled.
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
Optional user-defined label to distinguish multiple alerts on the same feature.
List of overage allowed controls per feature. When enabled, usage can exceed balance.
The feature ID this overage allowed control applies to.
Whether overage is allowed for this feature.
Invoices for this entity (only included when expand=invoices)
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
```json 200
{
"id": "seat_42",
"name": "Seat 42",
"customer_id": "cus_123",
"feature_id": "seats",
"created_at": 1771409161016,
"env": "sandbox",
"subscriptions": [
{
"plan_id": "pro_plan",
"auto_enable": true,
"add_on": false,
"status": "active",
"past_due": false,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"started_at": 1771431921437,
"current_period_start": 1771431921437,
"current_period_end": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"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
}
]
}
},
"invoices": []
}
```