--- title: "POST /v1/customers.get_or_create" method: POST path: "/v1/customers.get_or_create" tags: ["customers"] --- # POST /v1/customers.get_or_create `POST /v1/customers.get_or_create` Creates a customer if they do not exist, or returns the existing customer by your external customer ID. Use this as the primary entrypoint before billing operations so the customer record is always present and up to date. ## Headers - `x-api-version` string, required ## Request body - object - `customer_id` string, required — Your unique identifier for the customer - `name` string, nullable — Customer's name - `email` string, email, nullable — Customer's email address - `fingerprint` string, nullable — Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse - `metadata` object, nullable — Additional metadata for the customer - `stripe_id` string, nullable — Stripe customer ID if you already have one - `create_in_stripe` boolean — Whether to create the customer in Stripe - `auto_enable_plan_id` string — The ID of the free plan to auto-enable for the customer - `send_email_receipts` boolean — Whether to send email receipts to this customer - `currency` string, nullable — Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency. - `billing_controls` object — Billing controls for the customer (auto top-ups, etc.) - `auto_topups` object[] — List of auto top-up configurations per feature. - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up. - `enabled` boolean — Whether auto top-up is enabled. - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased. - `quantity` number, required — Amount of credits to add per auto top-up. - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window's consumed top-ups. - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window. - `interval_count` number — Number of intervals in the purchase limit window. - `limit` number, required — Maximum number of auto top-ups allowed within the interval. - `count` number — Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged. - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging. - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - `feature_id` string — Optional feature ID this spend limit applies to. - `enabled` boolean — Whether the overage spend limit is enabled. - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - `feature_id` string, required — The feature this usage limit applies to. - `enabled` boolean — Whether this usage limit is enabled. - `limit` number, required — Maximum units allowed per interval. - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle. - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. - `properties` object, required - `usage_alerts` object[] — List of usage alert configurations per feature. - `feature_id` string — The feature ID this alert applies to. - `enabled` boolean — Whether this usage alert is enabled. - `threshold` number, required — 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` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature. - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - `feature_id` string, required — The feature ID this overage allowed control applies to. - `enabled` boolean — Whether overage is allowed for this feature. - `config` object — Miscellaneous configurations for the customer. - `disable_pooled_balance` boolean — Whether to disable the shared customer-level pool for entities. - `disable_overage_billing` boolean — Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting. - `expand` CustomerExpand[] — Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature. ## Response `200` OK - Customer - `id` string, nullable, required — Your unique identifier for the customer. - `name` string, nullable, required — The name of the customer. - `email` string, nullable, required — The email address of the customer. - `created_at` number, required — Timestamp of customer creation in milliseconds since epoch. - `fingerprint` string, nullable, required — A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID. - `stripe_id` string, nullable, required — Stripe customer ID. - `env` 'sandbox' | 'live', required — The environment this customer was created in. - `metadata` object, required — The metadata for the customer. - `send_email_receipts` boolean, required — Whether to send email receipts to the customer. - `billing_controls` object, required — Billing controls for the customer (auto top-ups, etc.) - `auto_topups` object[] — List of auto top-up configurations per feature. - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up. - `enabled` boolean — Whether auto top-up is enabled. - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased. - `quantity` number, required — Amount of credits to add per auto top-up. - `purchase_limit` union — Optional rate limit to cap how often auto top-ups occur. Expand billing_controls.auto_topups.purchase_limit for a count of top ups and the next_reset_at. - object - `interval` 'hour' | 'day' | 'week' | 'month', nullable, required — The time interval for the purchase limit window. Null when no purchase limit is configured. - `interval_count` number, nullable, required — Number of intervals in the purchase limit window. Null when no purchase limit is configured. - `limit` number, nullable, required — Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured. - `count` number, required — Number of auto top-ups already consumed in the current window. - `next_reset_at` number, required — Unix ms timestamp when the current purchase window ends and the count resets. - object - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window. - `interval_count` number — Number of intervals in the purchase limit window. - `limit` number, required — Maximum number of auto top-ups allowed within the interval. - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging. - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults. - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - `feature_id` string — Optional feature ID this spend limit applies to. - `enabled` boolean — Whether the overage spend limit is enabled. - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults. - `usage_limits` object[] — List of hard usage caps per feature, with current interval usage. - `feature_id` string, required — The feature this usage limit applies to. - `enabled` boolean — Whether this usage limit is enabled. - `limit` number, required — Maximum units allowed per interval. - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle. - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. - `properties` object, required - `usage` number — Current usage already consumed in the active interval. Response-only; not stored on billing controls. - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults. - `usage_alerts` object[] — List of usage alert configurations per feature. - `feature_id` string — The feature ID this alert applies to. - `enabled` boolean — Whether this usage alert is enabled. - `threshold` number, required — 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` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature. - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults. - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - `feature_id` string, required — The feature ID this overage allowed control applies to. - `enabled` boolean — Whether overage is allowed for this feature. - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults. - `subscriptions` object[], required — Active and scheduled recurring plans that this customer has attached. - `id` string, required — 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. - `plan` Plan - `id` string, required — Unique identifier for the plan. - `name` string, required — Display name of the plan. - `description` string, nullable, required — Optional description of the plan. - `group` string, nullable, required — Group identifier for organizing related plans. Plans in the same group are mutually exclusive. - `version` number, required — Version number of the plan. Incremented when plan configuration changes. - `add_on` boolean, required — Whether this is an add-on plan that can be attached alongside a main plan. - `auto_enable` boolean, required — If true, this plan is automatically attached when a customer is created. Used for free plans. - `price` object, nullable, required — Base recurring price for the plan. Null for free plans or usage-only plans. - `amount` number, required — Base price amount for the plan. - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency. - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount. - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year'). - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `display` object — Display text for showing this price in pricing pages. - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages'). - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - `items` object[], required — Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. - `feature_id` string, required — The ID of the feature this item configures. - `feature` object — The full feature object if expanded. - `id` string, required — The ID of the feature, used to refer to it in other API calls like /track or /check. - `name` string, nullable — The name of the feature. - `type` 'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system', required — The type of the feature - `display` object, nullable — Singular and plural display names for the feature. - `singular` string, required — The singular display name for the feature. - `plural` string, required — The plural display name for the feature. - `credit_schema` object[], nullable — Credit cost schema for credit system features. - `metered_feature_id` string, required — The ID of the metered feature (should be a single_use feature). - `credit_cost` number, required — The credit cost of the metered feature. - `archived` boolean, nullable — Whether or not the feature is archived. - `included` number, required — Number of free units included. For consumable features, balance resets to this number each interval. - `unlimited` boolean, required — Whether the customer has unlimited access to this feature. - `reset` object, nullable, required — Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored. - `interval_count` number — Number of intervals between resets. Defaults to 1. - `price` object, nullable, required — Pricing configuration for usage beyond included units. Null if feature is entirely free. - `amount` number — Price per billing_units after included usage is consumed. Mutually exclusive with tiers. - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers' (tiered prices carry per-currency amounts on each tier). - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount. - `tiers` object[] — Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. - `to` union, required - … - `amount` number, required - `flat_amount` number - `additional_currencies` object[] - … - `tier_behavior` 'graduated' | 'volume' - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval for this price. For consumable features, should match reset.interval. - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `billing_units` number, required — 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). - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage. - `max_purchase` number, nullable, required — 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` object — Display text for showing this item in pricing pages. - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages'). - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - `rollover` object — Rollover configuration for unused units. If set, unused included units roll over to the next period. - `max` number, nullable, required — Maximum rollover units. Null for unlimited rollover. - `max_percentage` number, nullable — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire. - `expiry_duration_length` number — Number of periods before expiry. - `free_trial` object — Free trial configuration. If set, new customers can try this plan before being charged. - `duration_length` number, required — Number of duration_type periods the trial lasts. - `duration_type` 'day' | 'month' | 'year', required — Unit of time for the trial duration ('day', 'month', 'year'). - `card_required` boolean, required — Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. - `on_end` 'bill' | 'revert', nullable — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. - `created_at` number, required — Unix timestamp (ms) when the plan was created. - `env` 'sandbox' | 'live', required — Environment this plan belongs to ('sandbox' or 'live'). - `archived` boolean, required — Whether the plan is archived. Archived plans cannot be attached to new customers. - `base_variant_id` string, nullable, required — Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from. - `variant_details` object — Details about how this variant relates to its latest base plan. - `base_plan_id` string, required — The ID of the base plan this variant was derived from. - `customize` object — The customization that transforms the base plan into this variant. - `price` object, nullable — Base price configuration for a plan. - `amount` number, required — Base price amount for the plan. - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year'). - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency. - … - `add_items` object[] — Items to add to the plan. - `feature_id` string, required — The ID of the feature to configure. - `included` number — Number of free units included. Balance resets to this each interval for consumable features. - `unlimited` boolean — If true, customer has unlimited access to this feature. - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats. - … - `price` object — Pricing for usage beyond included units. Omit for free features. - … - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing. - … - `rollover` object — Rollover config for unused units. If set, unused included units carry over. - … - `remove_items` object[] — Filters selecting items to remove from the plan. - `feature_id` string — Match items linked to this feature. - `billing_method` 'prepaid' | 'usage_based' — Match items with this billing method (prepaid or usage_based). - `interval` union — Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated. - … - `interval_count` integer — Match items with this interval_count. Disambiguates between items that share an interval but differ in count. - `free_trial` object, nullable — Free trial configuration for a plan. - `duration_length` number, required — Number of duration_type periods the trial lasts. - `duration_type` 'day' | 'month' | 'year' — Unit of time for the trial ('day', 'month', 'year'). - `card_required` boolean — If true, payment method required to start trial. Customer is charged after trial ends. - `on_end` 'bill' | 'revert' — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. - `billing_controls` object — Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer. - `auto_topups` object[] — List of auto top-up configurations per feature. - … - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - … - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - … - `usage_alerts` object[] — List of usage alert configurations per feature. - … - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - … - `config` object, required — Miscellaneous plan-level configuration flags. - `ignore_past_due` boolean — If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. - `billing_controls` object — Plan-level billing controls used as customer defaults. - `auto_topups` object[] — List of auto top-up configurations per feature. - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up. - `enabled` boolean — Whether auto top-up is enabled. - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased. - `quantity` number, required — Amount of credits to add per auto top-up. - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window. - `interval_count` number — Number of intervals in the purchase limit window. - `limit` number, required — Maximum number of auto top-ups allowed within the interval. - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging. - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - `feature_id` string — Optional feature ID this spend limit applies to. - `enabled` boolean — Whether the overage spend limit is enabled. - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - `feature_id` string, required — The feature this usage limit applies to. - `enabled` boolean — Whether this usage limit is enabled. - `limit` number, required — Maximum units allowed per interval. - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle. - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. - `properties` object, required - `usage_alerts` object[] — List of usage alert configurations per feature. - `feature_id` string — The feature ID this alert applies to. - `enabled` boolean — Whether this usage alert is enabled. - `threshold` number, required — 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` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature. - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - `feature_id` string, required — The feature ID this overage allowed control applies to. - `enabled` boolean — Whether overage is allowed for this feature. - `metadata` object, required — Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan. - `customer_eligibility` object - `trial_available` boolean — 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. - `status` 'active' | 'scheduled' — The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. - `canceling` boolean — Whether the customer's active instance of this plan is set to cancel. - `trialing` boolean — Whether the customer is currently on a free trial of this plan. - `attach_action` 'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase', required — The action that would occur if this plan were attached to the customer. - `plan_id` string, required — The unique identifier of the subscribed plan. - `auto_enable` boolean, required — Whether the plan was automatically enabled for the customer. - `add_on` boolean, required — Whether this is an add-on plan rather than a base subscription. - `status` 'active' | 'scheduled', required — Current status of the subscription. - `past_due` boolean, required — Whether the subscription has overdue payments. - `canceled_at` number, nullable, required — Timestamp when the subscription was canceled, or null if not canceled. - `expires_at` number, nullable, required — Timestamp when the subscription will expire, or null if no expiry set. - `trial_ends_at` number, nullable, required — Timestamp when the trial period ends, or null if not on trial. - `started_at` number, required — Timestamp when the subscription started. - `current_period_start` number, nullable, required — Start timestamp of the current billing period. - `current_period_end` number, nullable, required — End timestamp of the current billing period. - `quantity` number, required — Number of units of this subscription (for per-seat plans). - `scope` 'customer' | 'entity' — Whether this subscription is attached at the customer level or entity level. - `purchases` object[], required — One-time purchases made by the customer. - `plan` Plan - `id` string, required — Unique identifier for the plan. - `name` string, required — Display name of the plan. - `description` string, nullable, required — Optional description of the plan. - `group` string, nullable, required — Group identifier for organizing related plans. Plans in the same group are mutually exclusive. - `version` number, required — Version number of the plan. Incremented when plan configuration changes. - `add_on` boolean, required — Whether this is an add-on plan that can be attached alongside a main plan. - `auto_enable` boolean, required — If true, this plan is automatically attached when a customer is created. Used for free plans. - `price` object, nullable, required — Base recurring price for the plan. Null for free plans or usage-only plans. - `amount` number, required — Base price amount for the plan. - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency. - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount. - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year'). - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `display` object — Display text for showing this price in pricing pages. - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages'). - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - `items` object[], required — Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. - `feature_id` string, required — The ID of the feature this item configures. - `feature` object — The full feature object if expanded. - `id` string, required — The ID of the feature, used to refer to it in other API calls like /track or /check. - `name` string, nullable — The name of the feature. - `type` 'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system', required — The type of the feature - `display` object, nullable — Singular and plural display names for the feature. - `singular` string, required — The singular display name for the feature. - `plural` string, required — The plural display name for the feature. - `credit_schema` object[], nullable — Credit cost schema for credit system features. - `metered_feature_id` string, required — The ID of the metered feature (should be a single_use feature). - `credit_cost` number, required — The credit cost of the metered feature. - `archived` boolean, nullable — Whether or not the feature is archived. - `included` number, required — Number of free units included. For consumable features, balance resets to this number each interval. - `unlimited` boolean, required — Whether the customer has unlimited access to this feature. - `reset` object, nullable, required — Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored. - `interval_count` number — Number of intervals between resets. Defaults to 1. - `price` object, nullable, required — Pricing configuration for usage beyond included units. Null if feature is entirely free. - `amount` number — Price per billing_units after included usage is consumed. Mutually exclusive with tiers. - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers' (tiered prices carry per-currency amounts on each tier). - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount. - `tiers` object[] — Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. - `to` union, required - … - `amount` number, required - `flat_amount` number - `additional_currencies` object[] - … - `tier_behavior` 'graduated' | 'volume' - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval for this price. For consumable features, should match reset.interval. - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `billing_units` number, required — 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). - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage. - `max_purchase` number, nullable, required — 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` object — Display text for showing this item in pricing pages. - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages'). - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - `rollover` object — Rollover configuration for unused units. If set, unused included units roll over to the next period. - `max` number, nullable, required — Maximum rollover units. Null for unlimited rollover. - `max_percentage` number, nullable — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire. - `expiry_duration_length` number — Number of periods before expiry. - `free_trial` object — Free trial configuration. If set, new customers can try this plan before being charged. - `duration_length` number, required — Number of duration_type periods the trial lasts. - `duration_type` 'day' | 'month' | 'year', required — Unit of time for the trial duration ('day', 'month', 'year'). - `card_required` boolean, required — Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. - `on_end` 'bill' | 'revert', nullable — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. - `created_at` number, required — Unix timestamp (ms) when the plan was created. - `env` 'sandbox' | 'live', required — Environment this plan belongs to ('sandbox' or 'live'). - `archived` boolean, required — Whether the plan is archived. Archived plans cannot be attached to new customers. - `base_variant_id` string, nullable, required — Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from. - `variant_details` object — Details about how this variant relates to its latest base plan. - `base_plan_id` string, required — The ID of the base plan this variant was derived from. - `customize` object — The customization that transforms the base plan into this variant. - `price` object, nullable — Base price configuration for a plan. - `amount` number, required — Base price amount for the plan. - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year'). - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency. - … - `add_items` object[] — Items to add to the plan. - `feature_id` string, required — The ID of the feature to configure. - `included` number — Number of free units included. Balance resets to this each interval for consumable features. - `unlimited` boolean — If true, customer has unlimited access to this feature. - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats. - … - `price` object — Pricing for usage beyond included units. Omit for free features. - … - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing. - … - `rollover` object — Rollover config for unused units. If set, unused included units carry over. - … - `remove_items` object[] — Filters selecting items to remove from the plan. - `feature_id` string — Match items linked to this feature. - `billing_method` 'prepaid' | 'usage_based' — Match items with this billing method (prepaid or usage_based). - `interval` union — Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated. - … - `interval_count` integer — Match items with this interval_count. Disambiguates between items that share an interval but differ in count. - `free_trial` object, nullable — Free trial configuration for a plan. - `duration_length` number, required — Number of duration_type periods the trial lasts. - `duration_type` 'day' | 'month' | 'year' — Unit of time for the trial ('day', 'month', 'year'). - `card_required` boolean — If true, payment method required to start trial. Customer is charged after trial ends. - `on_end` 'bill' | 'revert' — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. - `billing_controls` object — Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer. - `auto_topups` object[] — List of auto top-up configurations per feature. - … - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - … - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - … - `usage_alerts` object[] — List of usage alert configurations per feature. - … - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - … - `config` object, required — Miscellaneous plan-level configuration flags. - `ignore_past_due` boolean — If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. - `billing_controls` object — Plan-level billing controls used as customer defaults. - `auto_topups` object[] — List of auto top-up configurations per feature. - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up. - `enabled` boolean — Whether auto top-up is enabled. - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased. - `quantity` number, required — Amount of credits to add per auto top-up. - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window. - `interval_count` number — Number of intervals in the purchase limit window. - `limit` number, required — Maximum number of auto top-ups allowed within the interval. - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging. - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - `feature_id` string — Optional feature ID this spend limit applies to. - `enabled` boolean — Whether the overage spend limit is enabled. - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - `feature_id` string, required — The feature this usage limit applies to. - `enabled` boolean — Whether this usage limit is enabled. - `limit` number, required — Maximum units allowed per interval. - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle. - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. - `properties` object, required - `usage_alerts` object[] — List of usage alert configurations per feature. - `feature_id` string — The feature ID this alert applies to. - `enabled` boolean — Whether this usage alert is enabled. - `threshold` number, required — 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` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature. - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - `feature_id` string, required — The feature ID this overage allowed control applies to. - `enabled` boolean — Whether overage is allowed for this feature. - `metadata` object, required — Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan. - `customer_eligibility` object - `trial_available` boolean — 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. - `status` 'active' | 'scheduled' — The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. - `canceling` boolean — Whether the customer's active instance of this plan is set to cancel. - `trialing` boolean — Whether the customer is currently on a free trial of this plan. - `attach_action` 'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase', required — The action that would occur if this plan were attached to the customer. - `plan_id` string, required — The unique identifier of the purchased plan. - `expires_at` number, nullable, required — Timestamp when the purchase expires, or null for lifetime access. - `started_at` number, required — Timestamp when the purchase was made. - `quantity` number, required — Number of units purchased. - `scope` 'customer' | 'entity' — Whether this purchase is attached at the customer level or entity level. - `licenses` object[], required — License seat pools granted by the customer's plans, with seat counts. - `license_plan_id` string, required — The plan offered as an assignable license. - `parent_plan_id` string, required — The plan that offers this license. - `license_plan_name` string, required — Display name of the license plan. - `granted` number, required — Total seats the customer has for this license, included plus paid. - `usage` number, required — Seats currently assigned to entities. - `remaining` number, required — Seats still available to assign. - `paid_quantity` number, required — Paid seats purchased on top of the plan's included amount. - `balances` object, required — Feature balances keyed by feature ID, showing usage limits and remaining amounts. - `flags` object, required — Boolean feature flags keyed by feature ID, showing enabled access for on/off features. - `config` object — Configuration for the customer. - `disable_pooled_balance` boolean — Whether to disable the shared customer-level pool for entities. - `disable_overage_billing` boolean — Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting. - `processors` object — Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor. - `stripe` object — Stripe processor connection for the customer. - `id` string, required — Stripe customer ID. - `vercel` object — Vercel processor connection for the customer (public-safe subset). - `installation_id` string, required — Vercel marketplace installation ID for this customer. - `account_id` string, required — Vercel account ID associated with the installation. - `revenuecat` object — RevenueCat processor connection for the customer. - `id` string, nullable, required — Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set. - `invoices` object[] — Invoices for this customer. - `plan_ids` string[], required — Array of plan IDs included in this invoice - `stripe_id` string, required — The Stripe invoice ID - `processor_type` 'stripe' | 'revenuecat' — The billing processor that owns this invoice. - `status` string, required — The status of the invoice - `total` number, required — The total amount of the invoice - `currency` string, required — The currency code for the invoice - `created_at` number, required — Timestamp when the invoice was created - `hosted_invoice_url` string, nullable — URL to the Stripe-hosted invoice page - `entities` object[] — Entities associated with this customer. - `id` string, nullable, required — The unique identifier of the entity - `name` string, nullable, required — The name of the entity - `customer_id` string, nullable — The customer ID this entity belongs to - `feature_id` string, nullable — The feature ID this entity belongs to - `created_at` number, required — Unix timestamp when the entity was created - `env` 'sandbox' | 'live', required — The environment (sandbox/live) - `trials_used` object[] — Trial usage history for this customer. - `plan_id` string, required - `customer_id` string, required - `fingerprint` string, nullable - `rewards` object, nullable — Rewards earned or applied for this customer. - `discounts` object[], required — Array of active discounts applied to the customer - `id` string, required — The unique identifier for this discount - `name` string, required — The name of the discount or coupon - `type` 'percentage_discount' | 'fixed_discount' | 'free_product' | 'invoice_credits' | 'feature_grant', required — The type of reward - `discount_value` number, required — The discount value (percentage or fixed amount) - `duration_type` 'one_off' | 'months' | 'forever', required — How long the discount lasts - `duration_value` number, nullable — Number of billing periods the discount applies for repeating durations - `currency` string, nullable — The currency code for fixed amount discounts - `start` number, nullable — Timestamp when the discount becomes active - `end` number, nullable — Timestamp when the discount expires - `subscription_id` string, nullable — The Stripe subscription ID this discount is applied to - `total_discount_amount` number, nullable — Total amount saved from this discount - `referrals` object[] — Referral records for this customer. - `program_id` string, required - `customer` object, required - `id` string, required - `name` string, nullable - `email` string, nullable - `reward_applied` boolean, required - `created_at` number, required - `payment_method` unknown --- [API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/versions/29536933c0dc/schema)