info: title: Autumn API version: 2.3.0 servers: - url: https://api.useautumn.com description: Production server openapi: 3.1.0 components: schemas: CustomerId: type: string title: CustomerId description: Your unique identifier for the customer CustomerData: type: object properties: name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one create_in_stripe: type: boolean description: Whether to create the customer in Stripe auto_enable_plan_id: type: string description: The ID of the free plan to auto-enable for the customer send_email_receipts: type: boolean description: Whether to send email receipts to this customer billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: type: object properties: interval: enum: - hour - day - week - month type: string description: The time interval for the purchase limit window. interval_count: type: number minimum: 1 default: 1 description: Number of intervals in the purchase limit window. limit: type: number minimum: 1 description: Maximum number of auto top-ups allowed within the interval. required: - interval - limit description: Optional rate limit to cap how often auto top-ups occur. invoice_mode: type: boolean description: When true, auto top-up creates a send_invoice invoice instead of auto-charging. required: - feature_id - threshold - quantity description: List of auto top-up configurations per feature. spend_limits: type: array items: type: object properties: feature_id: type: string description: Optional feature ID this spend limit applies to. enabled: type: boolean default: false description: Whether this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Miscellaneous configurations for the customer. title: CustomerData description: Customer details to set when creating a customer CustomerExpand: enum: - invoices - trials_used - rewards - entities - referrals - payment_method - subscriptions.plan - purchases.plan - balances.feature - flags.feature - billing_controls.auto_topups.purchase_limit type: string title: CustomerExpand Customer: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live type: string description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: anyOf: - 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 - type: object properties: interval: anyOf: - enum: - hour - day - week - month type: string - type: "null" description: The time interval for the purchase limit window. Null when no purchase limit is configured. interval_count: anyOf: - type: number minimum: 1 - type: "null" description: Number of intervals in the purchase limit window. Null when no purchase limit is configured. limit: anyOf: - type: number minimum: 1 - type: "null" description: Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured. count: type: number description: Number of auto top-ups already consumed in the current window. next_reset_at: type: number description: Unix ms timestamp when the current purchase window ends and the count resets. required: - interval - interval_count - limit - count - next_reset_at description: 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. 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity description: Active and scheduled recurring plans that this customer has attached. purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity description: One-time purchases made by the customer. balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" description: Feature balances keyed by feature ID, showing usage limits and remaining amounts. flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard description: Boolean feature flags keyed by feature ID, showing enabled access for on/off features. config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Configuration for the customer. processors: type: object properties: stripe: type: object properties: id: type: string description: Stripe customer ID. required: - id description: Stripe processor connection for the customer. vercel: type: object properties: installation_id: type: string description: Vercel marketplace installation ID for this customer. account_id: type: string description: Vercel account ID associated with the installation. required: - installation_id - account_id description: Vercel processor connection for the customer (public-safe subset). revenuecat: type: object properties: id: anyOf: - type: string - type: "null" description: Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set. required: - id description: RevenueCat processor connection for the customer. description: Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this customer. entities: type: array items: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) required: - id - name - created_at - env description: Entities associated with this customer. trials_used: type: array items: type: object properties: plan_id: type: string customer_id: type: string fingerprint: anyOf: - type: string - type: "null" required: - plan_id - customer_id description: Trial usage history for this customer. rewards: anyOf: - type: object properties: discounts: type: array items: type: object properties: id: type: string description: The unique identifier for this discount name: type: string description: The name of the discount or coupon type: enum: - percentage_discount - fixed_discount - free_product - invoice_credits - feature_grant type: string description: The type of reward discount_value: type: number description: The discount value (percentage or fixed amount) duration_type: enum: - one_off - months - forever type: string description: How long the discount lasts duration_value: anyOf: - type: number - type: "null" description: Number of billing periods the discount applies for repeating durations currency: anyOf: - type: string - type: "null" description: The currency code for fixed amount discounts start: anyOf: - type: number - type: "null" description: Timestamp when the discount becomes active end: anyOf: - type: number - type: "null" description: Timestamp when the discount expires subscription_id: anyOf: - type: string - type: "null" description: The Stripe subscription ID this discount is applied to total_discount_amount: anyOf: - type: number - type: "null" description: Total amount saved from this discount required: - id - name - type - discount_value - duration_type description: Array of active discounts applied to the customer required: - discounts - type: "null" description: Rewards earned or applied for this customer. referrals: type: array items: type: object properties: program_id: type: string customer: type: object properties: id: type: string name: anyOf: - type: string - type: "null" email: anyOf: - type: string - type: "null" required: - id reward_applied: type: boolean created_at: type: number required: - program_id - customer - reward_applied - created_at description: Referral records for this customer. payment_method: anyOf: - {} - type: "null" description: The customer's default payment method. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - billing_controls - subscriptions - purchases - balances - flags examples: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO processors: stripe: id: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false billingControls: autoTopups: [] subscriptions: - planId: pro_plan autoEnable: true addOn: false status: active pastDue: false canceledAt: null expiresAt: null trialEndsAt: null startedAt: 1771431921437 currentPeriodStart: 1771431921437 currentPeriodEnd: 1771999921437 quantity: 1 purchases: [] balances: messages: featureId: messages granted: 100 remaining: 0 usage: 100 unlimited: false overageAllowed: false maxPurchase: null nextResetAt: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV planId: pro_plan includedGrant: 100 prepaidGrant: 0 remaining: 0 usage: 100 unlimited: false reset: interval: month resetsAt: 1773851121437 price: null expiresAt: null flags: advanced_workflows: id: cus_ent_abc123 plan_id: pro_plan expires_at: null feature_id: advanced_workflows config: disable_pooled_balance: false Plan: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this price in pricing pages. required: - amount - interval - type: "null" description: Base recurring price for the plan. Null for free plans or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature this item configures. feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system type: string description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type description: The full feature object if expanded. included: type: number description: Number of free units included. For consumable features, balance resets to this number each interval. unlimited: type: boolean description: Whether the customer has unlimited access to this feature. reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: 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: type: number description: Number of intervals between resets. Defaults to 1. required: - interval - type: "null" description: Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. price: anyOf: - type: object properties: amount: type: number description: Price per billing_units after included usage is consumed. Mutually exclusive with tiers. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval for this price. For consumable features, should match reset.interval. interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number description: 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: enum: - prepaid - usage_based type: string description: "'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage." max_purchase: anyOf: - type: number - type: "null" description: 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. required: - interval - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration for usage beyond included units. Null if feature is entirely free. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this item in pricing pages. rollover: type: object properties: max: anyOf: - type: number - type: "null" description: Maximum rollover units. Null for unlimited rollover. max_percentage: anyOf: - type: number - type: "null" description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - max - expiry_duration_type description: Rollover configuration for unused units. If set, unused included units roll over to the next period. required: - feature_id - included - unlimited - reset - price description: Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string description: Unit of time for the trial duration ('day', 'month', 'year'). card_required: type: boolean description: Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. 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. required: - duration_length - duration_type - card_required description: Free trial configuration. If set, new customers can try this plan before being charged. created_at: type: number description: Unix timestamp (ms) when the plan was created. env: enum: - sandbox - live type: string description: Environment this plan belongs to ('sandbox' or 'live'). archived: type: boolean description: Whether the plan is archived. Archived plans cannot be attached to new customers. base_variant_id: anyOf: - type: string - type: "null" description: If this is a variant, the ID of the base plan it was created from. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. customer_eligibility: type: object properties: trial_available: type: boolean description: 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: enum: - active - scheduled type: string description: The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. canceling: type: boolean description: Whether the customer's active instance of this plan is set to cancel. trialing: type: boolean description: Whether the customer is currently on a free trial of this plan. attach_action: enum: - activate - upgrade - downgrade - none - purchase type: string description: The action that would occur if this plan were attached to the customer. required: - attach_action required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id - config 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. granted: type: number description: Total balance granted (included + prepaid). remaining: type: number minimum: 0 description: Remaining balance available for use. usage: type: number description: Total usage consumed in the current period. unlimited: type: boolean description: Whether this feature has unlimited usage. overage_allowed: type: boolean description: Whether usage beyond the granted balance is allowed (with overage charges). max_purchase: anyOf: - type: number - type: "null" description: Maximum quantity that can be purchased as a top-up, or null for unlimited. next_reset_at: anyOf: - type: number - type: "null" description: Timestamp when the balance will reset, or null for no reset. breakdown: type: array items: type: object properties: id: type: string default: "" description: The unique identifier for this balance breakdown. plan_id: anyOf: - type: string - type: "null" description: The plan ID this balance originates from, or null for standalone balances. included_grant: type: number description: Amount granted from the plan's included usage. prepaid_grant: type: number description: Amount granted from prepaid purchases or top-ups. remaining: type: number description: Remaining balance available for use. usage: type: number description: Amount consumed in the current period. unlimited: type: boolean description: Whether this balance has unlimited usage. reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string - const: multiple description: The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals. interval_count: type: number description: Number of intervals between resets (eg. 2 for bi-monthly). resets_at: anyOf: - type: number - type: "null" description: Timestamp when the balance will next reset. required: - interval - resets_at - type: "null" description: Reset configuration for this balance, or null if no reset. price: anyOf: - type: object properties: amount: type: number description: The per-unit price amount. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration if applicable. tier_behavior: enum: - graduated - volume type: string description: "How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier)." billing_units: type: number description: The number of units per billing increment (eg. $9 / 250 units). billing_method: enum: - prepaid - usage_based type: string description: Whether usage is prepaid or billed pay-per-use. max_purchase: anyOf: - type: number - type: "null" description: Maximum quantity that can be purchased, or null for unlimited. required: - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration if this balance has usage-based pricing. expires_at: anyOf: - type: number - type: "null" description: Timestamp when this balance expires, or null for no expiration. required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at description: Detailed breakdown of balance sources when stacking multiple plans or grants. rollovers: type: array items: type: object properties: balance: type: number description: Amount of balance rolled over from a previous period. expires_at: type: number description: Timestamp when the rollover balance expires. required: - balance - expires_at description: Rollover balances carried over from previous periods. required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at examples: - feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null securitySchemes: secretKey: type: http scheme: bearer bearerFormat: JWT paths: /v1/customers.get_or_create: post: operationId: getOrCreateCustomer description: >- 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. @example ```typescript // Create or fetch a customer by external ID const response = await client.getOrCreate({ customerId: "cus_123", name: "John Doe", email: "john@example.com" }); ``` @param id - Your unique identifier for the customer (optional) @param name - Customer's name (optional) @param email - Customer's email address (optional) @param fingerprint - Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse (optional) @param metadata - Additional metadata for the customer (optional) @param stripeId - Stripe customer ID if you already have one (optional) @param createInStripe - Whether to create the customer in Stripe (optional) @param autoEnablePlanId - The ID of the free plan to auto-enable for the customer (optional) @param sendEmailReceipts - Whether to send email receipts to this customer (optional) @param billingControls - Billing controls for the customer (auto top-ups, etc.) (optional) @param config - Miscellaneous configurations for the customer. (optional) @param expand - Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature. (optional) tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: anyOf: - $ref: "#/components/schemas/CustomerId" - type: "null" name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one create_in_stripe: type: boolean description: Whether to create the customer in Stripe auto_enable_plan_id: type: string description: The ID of the free plan to auto-enable for the customer send_email_receipts: type: boolean description: Whether to send email receipts to this customer billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: type: object properties: interval: enum: - hour - day - week - month type: string description: The time interval for the purchase limit window. interval_count: type: number minimum: 1 default: 1 description: Number of intervals in the purchase limit window. limit: type: number minimum: 1 description: Maximum number of auto top-ups allowed within the interval. required: - interval - limit description: Optional rate limit to cap how often auto top-ups occur. invoice_mode: type: boolean description: When true, auto top-up creates a send_invoice invoice instead of auto-charging. required: - feature_id - threshold - quantity description: List of auto top-up configurations per feature. spend_limits: type: array items: type: object properties: feature_id: type: string description: Optional feature ID this spend limit applies to. enabled: type: boolean default: false description: Whether this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Miscellaneous configurations for the customer. expand: type: array items: $ref: "#/components/schemas/CustomerExpand" description: Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature. required: - customer_id title: GetOrCreateCustomerParams examples: - customer_id: cus_123 name: John Doe email: john@example.com responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" x-speakeasy-name-override: getOrCreate parameters: - &a1 name: x-api-version in: header required: true schema: type: string default: 2.3.0 x-speakeasy-globals-hidden: true /v1/customers.get: post: operationId: getCustomer description: >- Fetches a customer by ID, optionally expanding related data such as invoices or entities. Use this when you know the customer exists or assert they exist without creating them. @example ```typescript // Fetch a customer by external ID const response = await client.get({ customerId: "cus_123" }); ``` @example ```typescript // Fetch a customer with expanded invoices and entities const response = await client.get({ customerId: "cus_123", expand: ["invoices","entities"] }); ``` @param customerId - ID of the customer to fetch @param expand - Expand related customer data like invoices or entities, or expand nested objects like balances.feature, flags.feature, subscriptions.plan, and purchases.plan. (optional) tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to fetch expand: type: array items: $ref: "#/components/schemas/CustomerExpand" description: Expand related customer data like invoices or entities, or expand nested objects like balances.feature, flags.feature, subscriptions.plan, and purchases.plan. required: - customer_id title: GetCustomerParams examples: - customer_id: cus_123 - customer_id: cus_123 expand: - invoices - entities responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live type: string description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: anyOf: - 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 - type: object properties: interval: anyOf: - enum: - hour - day - week - month type: string - type: "null" description: The time interval for the purchase limit window. Null when no purchase limit is configured. interval_count: anyOf: - type: number minimum: 1 - type: "null" description: Number of intervals in the purchase limit window. Null when no purchase limit is configured. limit: anyOf: - type: number minimum: 1 - type: "null" description: Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured. count: type: number description: Number of auto top-ups already consumed in the current window. next_reset_at: type: number description: Unix ms timestamp when the current purchase window ends and the count resets. required: - interval - interval_count - limit - count - next_reset_at description: 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. 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity description: Active and scheduled recurring plans that this customer has attached. purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity description: One-time purchases made by the customer. balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" description: Feature balances keyed by feature ID, showing usage limits and remaining amounts. flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard description: Boolean feature flags keyed by feature ID, showing enabled access for on/off features. config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Configuration for the customer. processors: type: object properties: stripe: type: object properties: id: type: string description: Stripe customer ID. required: - id description: Stripe processor connection for the customer. vercel: type: object properties: installation_id: type: string description: Vercel marketplace installation ID for this customer. account_id: type: string description: Vercel account ID associated with the installation. required: - installation_id - account_id description: Vercel processor connection for the customer (public-safe subset). revenuecat: type: object properties: id: anyOf: - type: string - type: "null" description: Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set. required: - id description: RevenueCat processor connection for the customer. description: Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this customer. entities: type: array items: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) required: - id - name - created_at - env description: Entities associated with this customer. trials_used: type: array items: type: object properties: plan_id: type: string customer_id: type: string fingerprint: anyOf: - type: string - type: "null" required: - plan_id - customer_id description: Trial usage history for this customer. rewards: anyOf: - type: object properties: discounts: type: array items: type: object properties: id: type: string description: The unique identifier for this discount name: type: string description: The name of the discount or coupon type: enum: - percentage_discount - fixed_discount - free_product - invoice_credits - feature_grant type: string description: The type of reward discount_value: type: number description: The discount value (percentage or fixed amount) duration_type: enum: - one_off - months - forever type: string description: How long the discount lasts duration_value: anyOf: - type: number - type: "null" description: Number of billing periods the discount applies for repeating durations currency: anyOf: - type: string - type: "null" description: The currency code for fixed amount discounts start: anyOf: - type: number - type: "null" description: Timestamp when the discount becomes active end: anyOf: - type: number - type: "null" description: Timestamp when the discount expires subscription_id: anyOf: - type: string - type: "null" description: The Stripe subscription ID this discount is applied to total_discount_amount: anyOf: - type: number - type: "null" description: Total amount saved from this discount required: - id - name - type - discount_value - duration_type description: Array of active discounts applied to the customer required: - discounts - type: "null" description: Rewards earned or applied for this customer. referrals: type: array items: type: object properties: program_id: type: string customer: type: object properties: id: type: string name: anyOf: - type: string - type: "null" email: anyOf: - type: string - type: "null" required: - id reward_applied: type: boolean created_at: type: number required: - program_id - customer - reward_applied - created_at description: Referral records for this customer. payment_method: anyOf: - {} - type: "null" description: The customer's default payment method. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - billing_controls - subscriptions - purchases - balances - flags examples: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO processors: stripe: id: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false billingControls: autoTopups: [] subscriptions: - planId: pro_plan autoEnable: true addOn: false status: active pastDue: false canceledAt: null expiresAt: null trialEndsAt: null startedAt: 1771431921437 currentPeriodStart: 1771431921437 currentPeriodEnd: 1771999921437 quantity: 1 purchases: [] balances: messages: featureId: messages granted: 100 remaining: 0 usage: 100 unlimited: false overageAllowed: false maxPurchase: null nextResetAt: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV planId: pro_plan includedGrant: 100 prepaidGrant: 0 remaining: 0 usage: 100 unlimited: false reset: interval: month resetsAt: 1773851121437 price: null expiresAt: null flags: advanced_workflows: id: cus_ent_abc123 plan_id: pro_plan expires_at: null feature_id: advanced_workflows config: disable_pooled_balance: false x-speakeasy-name-override: get parameters: - *a1 /v1/customers.list: post: operationId: listCustomers description: 'Lists customers with cursor pagination and optional filters. Pass `start_cursor: ""` (or omit) for the first page; use `next_cursor` from a prior response for subsequent pages.' tags: - customers requestBody: required: true content: application/json: schema: type: object properties: start_cursor: type: string default: "" description: Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages. limit: type: integer minimum: 1 maximum: 5000 default: 50 description: Number of items to return. Default 50, hard ceiling 5000. plans: type: array items: type: object properties: id: type: string versions: type: array items: type: number required: - id description: Filter by plan ID and version. Returns customers with active subscriptions to this plan. subscription_status: enum: - active - scheduled type: string description: Filter by customer product status. Defaults to active and scheduled. search: type: string description: Search customers by id, name, or email. processors: type: array items: enum: - stripe - revenuecat - vercel type: string description: Filter by customer processor type (stripe, revenuecat, vercel). title: ListCustomersParams examples: - start_cursor: "" limit: 10 responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live type: string description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: anyOf: - 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 - type: object properties: interval: anyOf: - enum: - hour - day - week - month type: string - type: "null" description: The time interval for the purchase limit window. Null when no purchase limit is configured. interval_count: anyOf: - type: number minimum: 1 - type: "null" description: Number of intervals in the purchase limit window. Null when no purchase limit is configured. limit: anyOf: - type: number minimum: 1 - type: "null" description: Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured. count: type: number description: Number of auto top-ups already consumed in the current window. next_reset_at: type: number description: Unix ms timestamp when the current purchase window ends and the count resets. required: - interval - interval_count - limit - count - next_reset_at description: 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. 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity description: Active and scheduled recurring plans that this customer has attached. purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity description: One-time purchases made by the customer. balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" description: Feature balances keyed by feature ID, showing usage limits and remaining amounts. flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard description: Boolean feature flags keyed by feature ID, showing enabled access for on/off features. config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Configuration for the customer. processors: type: object properties: stripe: type: object properties: id: type: string description: Stripe customer ID. required: - id description: Stripe processor connection for the customer. vercel: type: object properties: installation_id: type: string description: Vercel marketplace installation ID for this customer. account_id: type: string description: Vercel account ID associated with the installation. required: - installation_id - account_id description: Vercel processor connection for the customer (public-safe subset). revenuecat: type: object properties: id: anyOf: - type: string - type: "null" description: Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set. required: - id description: RevenueCat processor connection for the customer. description: Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - billing_controls - subscriptions - purchases - balances - flags examples: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO processors: stripe: id: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false billingControls: autoTopups: [] subscriptions: - planId: pro_plan autoEnable: true addOn: false status: active pastDue: false canceledAt: null expiresAt: null trialEndsAt: null startedAt: 1771431921437 currentPeriodStart: 1771431921437 currentPeriodEnd: 1771999921437 quantity: 1 purchases: [] balances: messages: featureId: messages granted: 100 remaining: 0 usage: 100 unlimited: false overageAllowed: false maxPurchase: null nextResetAt: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV planId: pro_plan includedGrant: 100 prepaidGrant: 0 remaining: 0 usage: 100 unlimited: false reset: interval: month resetsAt: 1773851121437 price: null expiresAt: null flags: advanced_workflows: id: cus_ent_abc123 plan_id: pro_plan expires_at: null feature_id: advanced_workflows config: disable_pooled_balance: false description: Items for current page. next_cursor: anyOf: - type: string - type: "null" description: Opaque cursor for the next page. Null when there are no more results. required: - list - next_cursor examples: - list: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO processors: stripe: id: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false billingControls: autoTopups: [] subscriptions: - planId: pro_plan autoEnable: true addOn: false status: active pastDue: false canceledAt: null expiresAt: null trialEndsAt: null startedAt: 1771431921437 currentPeriodStart: 1771431921437 currentPeriodEnd: 1771999921437 quantity: 1 purchases: [] balances: messages: featureId: messages granted: 100 remaining: 0 usage: 100 unlimited: false overageAllowed: false maxPurchase: null nextResetAt: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV planId: pro_plan includedGrant: 100 prepaidGrant: 0 remaining: 0 usage: 100 unlimited: false reset: interval: month resetsAt: 1773851121437 price: null expiresAt: null flags: advanced_workflows: id: cus_ent_abc123 plan_id: pro_plan expires_at: null feature_id: advanced_workflows config: disable_pooled_balance: false next_cursor: null x-speakeasy-name-override: list parameters: - *a1 /v1/customers.update: post: operationId: updateCustomer description: Updates an existing customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to update name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one send_email_receipts: type: boolean description: Whether to send email receipts to this customer billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: type: object properties: interval: enum: - hour - day - week - month type: string description: The time interval for the purchase limit window. interval_count: type: number minimum: 1 default: 1 description: Number of intervals in the purchase limit window. limit: type: number minimum: 1 description: Maximum number of auto top-ups allowed within the interval. required: - interval - limit description: Optional rate limit to cap how often auto top-ups occur. invoice_mode: type: boolean description: When true, auto top-up creates a send_invoice invoice instead of auto-charging. required: - feature_id - threshold - quantity description: List of auto top-up configurations per feature. spend_limits: type: array items: type: object properties: feature_id: type: string description: Optional feature ID this spend limit applies to. enabled: type: boolean default: false description: Whether this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Miscellaneous configurations for the customer. new_customer_id: $ref: "#/components/schemas/CustomerId" description: New ID for the customer required: - customer_id title: UpdateCustomerParams examples: - customer_id: cus_123 name: Jane Doe email: jane@example.com responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live type: string description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. billing_controls: type: object properties: auto_topups: type: array items: type: object properties: feature_id: type: string description: The ID of the feature (credit balance) to auto top-up. enabled: type: boolean default: false description: Whether auto top-up is enabled. threshold: type: number minimum: 0 description: When the balance drops below this threshold, an auto top-up will be purchased. quantity: type: number minimum: 1 description: Amount of credits to add per auto top-up. purchase_limit: anyOf: - 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 - type: object properties: interval: anyOf: - enum: - hour - day - week - month type: string - type: "null" description: The time interval for the purchase limit window. Null when no purchase limit is configured. interval_count: anyOf: - type: number minimum: 1 - type: "null" description: Number of intervals in the purchase limit window. Null when no purchase limit is configured. limit: anyOf: - type: number minimum: 1 - type: "null" description: Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured. count: type: number description: Number of auto top-ups already consumed in the current window. next_reset_at: type: number description: Unix ms timestamp when the current purchase window ends and the count resets. required: - interval - interval_count - limit - count - next_reset_at description: 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. 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the customer (auto top-ups, etc.) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity description: Active and scheduled recurring plans that this customer has attached. purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity description: One-time purchases made by the customer. balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" description: Feature balances keyed by feature ID, showing usage limits and remaining amounts. flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard description: Boolean feature flags keyed by feature ID, showing enabled access for on/off features. config: type: object properties: disable_pooled_balance: type: boolean description: Whether to disable the shared customer-level pool for entities. description: Configuration for the customer. processors: type: object properties: stripe: type: object properties: id: type: string description: Stripe customer ID. required: - id description: Stripe processor connection for the customer. vercel: type: object properties: installation_id: type: string description: Vercel marketplace installation ID for this customer. account_id: type: string description: Vercel account ID associated with the installation. required: - installation_id - account_id description: Vercel processor connection for the customer (public-safe subset). revenuecat: type: object properties: id: anyOf: - type: string - type: "null" description: Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set. required: - id description: RevenueCat processor connection for the customer. description: Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - billing_controls - subscriptions - purchases - balances - flags examples: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO processors: stripe: id: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false billingControls: autoTopups: [] subscriptions: - planId: pro_plan autoEnable: true addOn: false status: active pastDue: false canceledAt: null expiresAt: null trialEndsAt: null startedAt: 1771431921437 currentPeriodStart: 1771431921437 currentPeriodEnd: 1771999921437 quantity: 1 purchases: [] balances: messages: featureId: messages granted: 100 remaining: 0 usage: 100 unlimited: false overageAllowed: false maxPurchase: null nextResetAt: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV planId: pro_plan includedGrant: 100 prepaidGrant: 0 remaining: 0 usage: 100 unlimited: false reset: interval: month resetsAt: 1773851121437 price: null expiresAt: null flags: advanced_workflows: id: cus_ent_abc123 plan_id: pro_plan expires_at: null feature_id: advanced_workflows config: disable_pooled_balance: false x-speakeasy-name-override: update parameters: - *a1 /v1/customers.delete: post: operationId: deleteCustomer description: Deletes a customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to delete delete_in_stripe: type: boolean default: false description: Whether to also delete the customer in Stripe required: - customer_id title: DeleteCustomerParams examples: - customer_id: cus_123 delete_in_stripe: false responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - *a1 /v1/plans.create: post: operationId: createPlan summary: Create a plan description: |- Creates a new plan with optional base price and feature configurations. Use this to programmatically create pricing plans. See [How plans work](/documentation/pricing/plans) for concepts. @example ```typescript // Create a free plan with limited features const response = await client.plans.create({ planId: "free_plan", name: "Free", autoEnable: true, items: [{"featureId":"messages","included":100,"reset":{"interval":"month"}}], }); ``` @example ```typescript // Create a paid plan with base price and usage-based feature const response = await client.plans.create({ planId: "pro_plan", name: "Pro Plan", price: {"amount":10,"interval":"month"}, items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"},"price":{"amount":0.01,"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}], }); ``` @example ```typescript // Create a plan with prepaid seats const response = await client.plans.create({ planId: "team_plan", name: "Team Plan", price: {"amount":49,"interval":"month"}, items: [{"featureId":"seats","included":5,"price":{"amount":10,"interval":"month","billingUnits":1,"billingMethod":"prepaid"}}], }); ``` @example ```typescript // Create an add-on plan const response = await client.plans.create({ planId: "analytics_addon", name: "Advanced Analytics", addOn: true, price: {"amount":20,"interval":"month"}, }); ``` @example ```typescript // Create a plan with tiered pricing const response = await client.plans.create({ planId: "api_plan", name: "API Plan", items: [{"featureId":"api_calls","included":1000,"reset":{"interval":"month"},"price":{"tiers":[{"to":10000,"amount":0.001},{"to":100000,"amount":0.0005},{"to":"inf","amount":0.0001}],"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}] }); ``` @example ```typescript // Create a plan with free trial const response = await client.plans.create({ planId: "premium_plan", name: "Premium", price: {"amount":99,"interval":"month"}, freeTrial: {"durationLength":14,"durationType":"day","cardRequired":true}, }); ``` @param planId - The ID of the plan to create. @param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional) @param name - Display name of the plan. @param description - Optional description of the plan. (optional) @param addOn - If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. (optional) @param autoEnable - If true, plan is automatically attached when a customer is created. Use for free tiers. (optional) @param price - Base recurring price for the plan. Omit for free or usage-only plans. (optional) @param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional) @param freeTrial - Free trial configuration. Customers can try this plan before being charged. (optional) @param config - Miscellaneous plan-level configuration flags. (optional) @returns The created plan object. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: The ID of the plan to create. group: type: string default: "" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. name: type: string minLength: 1 description: Display name of the plan. description: anyOf: - type: string - type: "null" default: null description: Optional description of the plan. add_on: type: boolean default: false description: If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. auto_enable: type: boolean default: false description: If true, plan is automatically attached when a customer is created. Use for free tiers. price: type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval description: Base recurring price for the plan. Omit for free or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length description: Free trial configuration. Customers can try this plan before being charged. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. create_in_stripe: type: boolean default: true required: - plan_id - name title: CreatePlanParams examples: - plan_id: free_plan name: Free auto_enable: true items: - feature_id: messages included: 100 reset: interval: month - plan_id: pro_plan name: Pro Plan price: amount: 10 interval: month items: - feature_id: messages included: 1000 reset: interval: month price: amount: 0.01 interval: month billing_units: 1 billing_method: usage_based - plan_id: team_plan name: Team Plan price: amount: 49 interval: month items: - feature_id: seats included: 5 price: amount: 10 interval: month billing_units: 1 billing_method: prepaid responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this price in pricing pages. required: - amount - interval - type: "null" description: Base recurring price for the plan. Null for free plans or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature this item configures. feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system type: string description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type description: The full feature object if expanded. included: type: number description: Number of free units included. For consumable features, balance resets to this number each interval. unlimited: type: boolean description: Whether the customer has unlimited access to this feature. reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: 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: type: number description: Number of intervals between resets. Defaults to 1. required: - interval - type: "null" description: Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. price: anyOf: - type: object properties: amount: type: number description: Price per billing_units after included usage is consumed. Mutually exclusive with tiers. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval for this price. For consumable features, should match reset.interval. interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number description: 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: enum: - prepaid - usage_based type: string description: "'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage." max_purchase: anyOf: - type: number - type: "null" description: 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. required: - interval - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration for usage beyond included units. Null if feature is entirely free. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this item in pricing pages. rollover: type: object properties: max: anyOf: - type: number - type: "null" description: Maximum rollover units. Null for unlimited rollover. max_percentage: anyOf: - type: number - type: "null" description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - max - expiry_duration_type description: Rollover configuration for unused units. If set, unused included units roll over to the next period. required: - feature_id - included - unlimited - reset - price description: Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string description: Unit of time for the trial duration ('day', 'month', 'year'). card_required: type: boolean description: Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. 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. required: - duration_length - duration_type - card_required description: Free trial configuration. If set, new customers can try this plan before being charged. created_at: type: number description: Unix timestamp (ms) when the plan was created. env: enum: - sandbox - live type: string description: Environment this plan belongs to ('sandbox' or 'live'). archived: type: boolean description: Whether the plan is archived. Archived plans cannot be attached to new customers. base_variant_id: anyOf: - type: string - type: "null" description: If this is a variant, the ID of the base plan it was created from. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. customer_eligibility: type: object properties: trial_available: type: boolean description: 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: enum: - active - scheduled type: string description: The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. canceling: type: boolean description: Whether the customer's active instance of this plan is set to cancel. trialing: type: boolean description: Whether the customer is currently on a free trial of this plan. attach_action: enum: - activate - upgrade - downgrade - none - purchase type: string description: The action that would occur if this plan were attached to the customer. required: - attach_action required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id - config description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - id: pro name: Pro Plan description: null group: null version: 1 addOn: false autoEnable: false price: amount: 10 interval: month display: primaryText: $10 secondaryText: per month items: - featureId: messages included: 100 unlimited: false reset: interval: month price: amount: 0.5 interval: month billingUnits: 100 billingMethod: usage_based maxPurchase: null display: primaryText: 100 messages secondaryText: then $0.5 per 100 messages - featureId: users included: 0 unlimited: false reset: null price: amount: 10 interval: month billingUnits: 1 billingMethod: prepaid maxPurchase: null display: primaryText: $10 per Users createdAt: 1771513979217 env: sandbox archived: false baseVariantId: null config: ignore_past_due: false x-speakeasy-name-override: create parameters: - *a1 /v1/plans.get: post: operationId: getPlan summary: Get a plan description: >- Retrieves a single plan by its ID. Use this to fetch the full configuration of a specific plan, including its features and pricing. @example ```typescript // Get a plan by ID const response = await client.plans.get({ planId: "pro_plan" }); ``` @example ```typescript // Get a specific version of a plan const response = await client.plans.get({ planId: "pro_plan", version: 2 }); ``` @param planId - The ID of the plan to retrieve. @param version - The version of the plan to get. Defaults to the latest version. (optional) @returns The plan object with its full configuration. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 description: The ID of the plan to retrieve. version: type: number description: The version of the plan to get. Defaults to the latest version. required: - plan_id title: GetPlanParams examples: - plan_id: pro_plan - plan_id: pro_plan version: 2 responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this price in pricing pages. required: - amount - interval - type: "null" description: Base recurring price for the plan. Null for free plans or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature this item configures. feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system type: string description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type description: The full feature object if expanded. included: type: number description: Number of free units included. For consumable features, balance resets to this number each interval. unlimited: type: boolean description: Whether the customer has unlimited access to this feature. reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: 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: type: number description: Number of intervals between resets. Defaults to 1. required: - interval - type: "null" description: Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. price: anyOf: - type: object properties: amount: type: number description: Price per billing_units after included usage is consumed. Mutually exclusive with tiers. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval for this price. For consumable features, should match reset.interval. interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number description: 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: enum: - prepaid - usage_based type: string description: "'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage." max_purchase: anyOf: - type: number - type: "null" description: 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. required: - interval - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration for usage beyond included units. Null if feature is entirely free. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this item in pricing pages. rollover: type: object properties: max: anyOf: - type: number - type: "null" description: Maximum rollover units. Null for unlimited rollover. max_percentage: anyOf: - type: number - type: "null" description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - max - expiry_duration_type description: Rollover configuration for unused units. If set, unused included units roll over to the next period. required: - feature_id - included - unlimited - reset - price description: Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string description: Unit of time for the trial duration ('day', 'month', 'year'). card_required: type: boolean description: Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. 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. required: - duration_length - duration_type - card_required description: Free trial configuration. If set, new customers can try this plan before being charged. created_at: type: number description: Unix timestamp (ms) when the plan was created. env: enum: - sandbox - live type: string description: Environment this plan belongs to ('sandbox' or 'live'). archived: type: boolean description: Whether the plan is archived. Archived plans cannot be attached to new customers. base_variant_id: anyOf: - type: string - type: "null" description: If this is a variant, the ID of the base plan it was created from. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. customer_eligibility: type: object properties: trial_available: type: boolean description: 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: enum: - active - scheduled type: string description: The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. canceling: type: boolean description: Whether the customer's active instance of this plan is set to cancel. trialing: type: boolean description: Whether the customer is currently on a free trial of this plan. attach_action: enum: - activate - upgrade - downgrade - none - purchase type: string description: The action that would occur if this plan were attached to the customer. required: - attach_action required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id - config description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - id: pro name: Pro Plan description: null group: null version: 1 addOn: false autoEnable: false price: amount: 10 interval: month display: primaryText: $10 secondaryText: per month items: - featureId: messages included: 100 unlimited: false reset: interval: month price: amount: 0.5 interval: month billingUnits: 100 billingMethod: usage_based maxPurchase: null display: primaryText: 100 messages secondaryText: then $0.5 per 100 messages - featureId: users included: 0 unlimited: false reset: null price: amount: 10 interval: month billingUnits: 1 billingMethod: prepaid maxPurchase: null display: primaryText: $10 per Users createdAt: 1771513979217 env: sandbox archived: false baseVariantId: null config: ignore_past_due: false x-speakeasy-name-override: get parameters: - *a1 /v1/plans.list: post: operationId: listPlans summary: List all plans description: >- Lists all plans in the current environment. Use this to retrieve all plans for displaying pricing pages or managing plan configurations. @returns A list of all plans with their pricing and feature configurations. tags: - plans requestBody: required: false content: application/json: schema: type: object properties: customer_id: type: string description: Customer ID to include eligibility info (trial availability, attach scenario). entity_id: type: string description: Entity ID for entity-scoped plans. include_archived: type: boolean description: If true, includes archived plans in the response. title: ListPlansParams examples: - {} - customer_id: cus_123 - include_archived: true responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this price in pricing pages. required: - amount - interval - type: "null" description: Base recurring price for the plan. Null for free plans or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature this item configures. feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system type: string description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type description: The full feature object if expanded. included: type: number description: Number of free units included. For consumable features, balance resets to this number each interval. unlimited: type: boolean description: Whether the customer has unlimited access to this feature. reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: 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: type: number description: Number of intervals between resets. Defaults to 1. required: - interval - type: "null" description: Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. price: anyOf: - type: object properties: amount: type: number description: Price per billing_units after included usage is consumed. Mutually exclusive with tiers. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval for this price. For consumable features, should match reset.interval. interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number description: 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: enum: - prepaid - usage_based type: string description: "'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage." max_purchase: anyOf: - type: number - type: "null" description: 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. required: - interval - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration for usage beyond included units. Null if feature is entirely free. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this item in pricing pages. rollover: type: object properties: max: anyOf: - type: number - type: "null" description: Maximum rollover units. Null for unlimited rollover. max_percentage: anyOf: - type: number - type: "null" description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - max - expiry_duration_type description: Rollover configuration for unused units. If set, unused included units roll over to the next period. required: - feature_id - included - unlimited - reset - price description: Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string description: Unit of time for the trial duration ('day', 'month', 'year'). card_required: type: boolean description: Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. 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. required: - duration_length - duration_type - card_required description: Free trial configuration. If set, new customers can try this plan before being charged. created_at: type: number description: Unix timestamp (ms) when the plan was created. env: enum: - sandbox - live type: string description: Environment this plan belongs to ('sandbox' or 'live'). archived: type: boolean description: Whether the plan is archived. Archived plans cannot be attached to new customers. base_variant_id: anyOf: - type: string - type: "null" description: If this is a variant, the ID of the base plan it was created from. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. customer_eligibility: type: object properties: trial_available: type: boolean description: 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: enum: - active - scheduled type: string description: The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. canceling: type: boolean description: Whether the customer's active instance of this plan is set to cancel. trialing: type: boolean description: Whether the customer is currently on a free trial of this plan. attach_action: enum: - activate - upgrade - downgrade - none - purchase type: string description: The action that would occur if this plan were attached to the customer. required: - attach_action required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id - config description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. required: - list examples: - list: - id: pro name: Pro Plan description: null group: null version: 1 addOn: false autoEnable: false price: amount: 10 interval: month display: primaryText: $10 secondaryText: per month items: - featureId: messages included: 100 unlimited: false reset: interval: month price: amount: 0.5 interval: month billingUnits: 100 billingMethod: usage_based maxPurchase: null display: primaryText: 100 messages secondaryText: then $0.5 per 100 messages - featureId: users included: 0 unlimited: false reset: null price: amount: 10 interval: month billingUnits: 1 billingMethod: prepaid maxPurchase: null display: primaryText: $10 per Users createdAt: 1771513979217 env: sandbox archived: false baseVariantId: null config: ignore_past_due: false x-speakeasy-name-override: list parameters: - *a1 /v1/plans.update: post: operationId: updatePlan summary: Update a plan description: |- Updates an existing plan. Creates a new version unless `disableVersion` is set. Use this to modify plan properties, pricing, or feature configurations. See [Adding features to plans](/documentation/pricing/plan-features) for item configuration. @example ```typescript // Update plan name and price const response = await client.plans.update({ planId: "pro_plan", name: "Pro Plan (Updated)", price: {"amount":15,"interval":"month"} }); ``` @example ```typescript // Add a feature to an existing plan const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"}},{"featureId":"storage","included":10,"reset":{"interval":"month"}}] }); ``` @example ```typescript // Remove the base price (make usage-only) const response = await client.plans.update({ planId: "pro_plan", price: null }); ``` @example ```typescript // Archive a plan const response = await client.plans.update({ planId: "old_plan", archived: true }); ``` @example ```typescript // Update feature's included amount const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":2000,"reset":{"interval":"month"}}] }); ``` @param planId - The ID of the plan to update. @param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional) @param name - Display name of the plan. (optional) @param addOn - Whether the plan is an add-on. (optional) @param autoEnable - Whether the plan is automatically enabled. (optional) @param price - The price of the plan. Set to null to remove the base price. (optional) @param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional) @param freeTrial - The free trial of the plan. Set to null to remove the free trial. (optional) @param config - Miscellaneous plan-level configuration flags. (optional) @param newPlanId - The new ID to use for the plan. Can only be updated if the plan has not been used by any customers. (optional) @returns The updated plan object. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: The ID of the plan to update. group: type: string default: "" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. name: type: string minLength: 1 description: Display name of the plan. description: type: string add_on: type: boolean description: Whether the plan is an add-on. auto_enable: type: boolean description: Whether the plan is automatically enabled. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: The price of the plan. Set to null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: The free trial of the plan. Set to null to remove the free trial. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. create_in_stripe: type: boolean default: true version: type: number archived: type: boolean default: false new_plan_id: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: The new ID to use for the plan. Can only be updated if the plan has not been used by any customers. required: - plan_id title: UpdatePlanParams examples: - plan_id: pro_plan name: Pro Plan (Updated) price: amount: 15 interval: month - plan_id: pro_plan price: null - plan_id: old_plan archived: true responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this price in pricing pages. required: - amount - interval - type: "null" description: Base recurring price for the plan. Null for free plans or usage-only plans. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature this item configures. feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system type: string description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type description: The full feature object if expanded. included: type: number description: Number of free units included. For consumable features, balance resets to this number each interval. unlimited: type: boolean description: Whether the customer has unlimited access to this feature. reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: 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: type: number description: Number of intervals between resets. Defaults to 1. required: - interval - type: "null" description: Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles. price: anyOf: - type: object properties: amount: type: number description: Price per billing_units after included usage is consumed. Mutually exclusive with tiers. tiers: type: array items: anyOf: - {} - type: "null" description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval for this price. For consumable features, should match reset.interval. interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number description: 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: enum: - prepaid - usage_based type: string description: "'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage." max_purchase: anyOf: - type: number - type: "null" description: 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. required: - interval - billing_units - billing_method - max_purchase - type: "null" description: Pricing configuration for usage beyond included units. Null if feature is entirely free. display: type: object properties: primary_text: type: string description: Main display text (e.g. '$10' or '100 messages'). secondary_text: type: string description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). required: - primary_text description: Display text for showing this item in pricing pages. rollover: type: object properties: max: anyOf: - type: number - type: "null" description: Maximum rollover units. Null for unlimited rollover. max_percentage: anyOf: - type: number - type: "null" description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - max - expiry_duration_type description: Rollover configuration for unused units. If set, unused included units roll over to the next period. required: - feature_id - included - unlimited - reset - price description: Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature. free_trial: type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string description: Unit of time for the trial duration ('day', 'month', 'year'). card_required: type: boolean description: Whether a payment method is required to start the trial. If true, customer will be charged after trial ends. 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. required: - duration_length - duration_type - card_required description: Free trial configuration. If set, new customers can try this plan before being charged. created_at: type: number description: Unix timestamp (ms) when the plan was created. env: enum: - sandbox - live type: string description: Environment this plan belongs to ('sandbox' or 'live'). archived: type: boolean description: Whether the plan is archived. Archived plans cannot be attached to new customers. base_variant_id: anyOf: - type: string - type: "null" description: If this is a variant, the ID of the base plan it was created from. config: type: object properties: ignore_past_due: type: boolean default: false description: If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. description: Miscellaneous plan-level configuration flags. customer_eligibility: type: object properties: trial_available: type: boolean description: 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: enum: - active - scheduled type: string description: The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation. canceling: type: boolean description: Whether the customer's active instance of this plan is set to cancel. trialing: type: boolean description: Whether the customer is currently on a free trial of this plan. attach_action: enum: - activate - upgrade - downgrade - none - purchase type: string description: The action that would occur if this plan were attached to the customer. required: - attach_action required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id - config description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - id: pro name: Pro Plan description: null group: null version: 1 addOn: false autoEnable: false price: amount: 10 interval: month display: primaryText: $10 secondaryText: per month items: - featureId: messages included: 100 unlimited: false reset: interval: month price: amount: 0.5 interval: month billingUnits: 100 billingMethod: usage_based maxPurchase: null display: primaryText: 100 messages secondaryText: then $0.5 per 100 messages - featureId: users included: 0 unlimited: false reset: null price: amount: 10 interval: month billingUnits: 1 billingMethod: prepaid maxPurchase: null display: primaryText: $10 per Users createdAt: 1771513979217 env: sandbox archived: false baseVariantId: null config: ignore_past_due: false x-speakeasy-name-override: update parameters: - *a1 /v1/plans.delete: post: operationId: deletePlan summary: Delete a plan description: >- Deletes a plan by its ID. Use this to permanently remove a plan. Plans with active customers cannot be deleted - archive them instead. @example ```typescript // Delete a plan const response = await client.plans.delete({ planId: "unused_plan" }); ``` @example ```typescript // Delete all versions of a plan const response = await client.plans.delete({ planId: "legacy_plan", allVersions: true }); ``` @param planId - The ID of the plan to delete. @param allVersions - If true, deletes all versions of the plan. Otherwise, only deletes the latest version. (optional) @returns A success flag indicating the plan was deleted. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 description: The ID of the plan to delete. all_versions: type: boolean default: false description: If true, deletes all versions of the plan. Otherwise, only deletes the latest version. required: - plan_id title: DeletePlanParams examples: - plan_id: unused_plan - plan_id: legacy_plan all_versions: true responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - *a1 /v1/features.create: post: operationId: createFeature description: >- Creates a new feature. Use this to programmatically create features for metering usage, managing access, or building credit systems. @example ```typescript // Create a metered feature for API calls const response = await client.features.create({ featureId: "api-calls", name: "API Calls", type: "metered", consumable: true, }); ``` @example ```typescript // Create a boolean feature for a premium feature flag const response = await client.features.create({ featureId: "advanced-analytics", name: "Advanced Analytics", type: "boolean" }); ``` @param name - The name of the feature. @param type - The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. @param consumable - Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. (optional) @param display - Singular and plural display names for the feature in your user interface. (optional) @param creditSchema - A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. (optional) @param featureId - The ID of the feature to create. @returns The created feature object. tags: - features requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the feature. type: enum: - boolean - metered - credit_system type: string description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. consumable: type: boolean description: Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. display: type: object properties: singular: type: string plural: type: string required: - singular - plural description: Singular and plural display names for the feature in your user interface. credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. event_names: type: array items: type: string feature_id: type: string description: The ID of the feature to create. required: - name - type - feature_id title: CreateFeatureParams examples: - feature_id: api-calls name: API Calls type: metered consumable: true - feature_id: credits name: Credits type: credit_system consumable: true credit_schema: - metered_feature_id: api-calls credit_cost: 1 - metered_feature_id: image-generations credit_cost: 10 responses: "200": description: OK content: application/json: schema: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: create parameters: - *a1 /v1/features.get: post: operationId: getFeature description: |- Retrieves a single feature by its ID. Use this when you need to fetch the details of a specific feature. @example ```typescript // Get a feature by ID const response = await client.features.get({ featureId: "api-calls" }); ``` @param featureId - The ID of the feature. @returns The feature object with its full configuration. tags: - features requestBody: required: true content: application/json: schema: type: object properties: feature_id: type: string description: The ID of the feature. required: - feature_id title: GetFeatureParams examples: - feature_id: api-calls responses: "200": description: OK content: application/json: schema: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: get parameters: - *a1 /v1/features.list: post: operationId: listFeatures description: >- Lists all features in the current environment. Use this to retrieve all features configured for your organization to display in dashboards or for feature management. @returns A list of all features with their configuration and metadata. tags: - features responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived required: - list examples: - list: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls - id: credits name: Credits type: credit_system consumable: true archived: false credit_schema: - metered_feature_id: api-calls credit_cost: 1 - metered_feature_id: image-generations credit_cost: 10 display: singular: credit plural: credits x-speakeasy-name-override: list parameters: - *a1 /v1/features.update: post: operationId: updateFeature description: >- Updates an existing feature. Use this to modify feature properties like name, display settings, or to archive a feature. @example ```typescript // Update a feature's display name const response = await client.features.update({ featureId: "api-calls", name: "API Requests", display: {"singular":"API request","plural":"API requests"} }); ``` @example ```typescript // Archive a feature const response = await client.features.update({ featureId: "deprecated-feature", archived: true }); ``` @param name - The name of the feature. (optional) @param type - The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. (optional) @param consumable - Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. (optional) @param display - Singular and plural display names for the feature in your user interface. (optional) @param creditSchema - A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. (optional) @param archived - Whether the feature is archived. Archived features are hidden from the dashboard. (optional) @param featureId - The ID of the feature to update. @param newFeatureId - The new ID of the feature. Feature ID can only be updated if it's not being used by any customers. (optional) @returns The updated feature object. tags: - features requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 description: The name of the feature. type: enum: - boolean - metered - credit_system type: string description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. consumable: type: boolean description: Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. display: type: object properties: singular: type: string plural: type: string required: - singular - plural description: Singular and plural display names for the feature in your user interface. credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. event_names: type: array items: type: string archived: type: boolean description: Whether the feature is archived. Archived features are hidden from the dashboard. feature_id: type: string description: The ID of the feature to update. new_feature_id: type: string description: The new ID of the feature. Feature ID can only be updated if it's not being used by any customers. required: - feature_id title: UpdateFeatureParams examples: - feature_id: api-calls name: API Requests display: singular: API request plural: API requests - feature_id: old-feature archived: true responses: "200": description: OK content: application/json: schema: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: update parameters: - *a1 /v1/features.delete: post: operationId: deleteFeature description: >- Deletes a feature by its ID. Use this to permanently remove a feature. Note: features that are used in products cannot be deleted - archive them instead. @example ```typescript // Delete an unused feature const response = await client.features.delete({ featureId: "old-feature" }); ``` @param featureId - The ID of the feature to delete. @returns A success flag indicating the feature was deleted. tags: - features requestBody: required: true content: application/json: schema: type: object properties: feature_id: type: string description: The ID of the feature to delete. required: - feature_id title: DeleteFeatureParams examples: - feature_id: old-feature responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - success: true x-speakeasy-name-override: delete parameters: - *a1 /v1/billing.attach: post: operationId: attach description: >- Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades. Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product. @example ```typescript // Attach a plan to a customer const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan" }); ``` @example ```typescript // Attach with a free trial const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan", freeTrial: {"durationLength":14,"durationType":"day"} }); ``` @example ```typescript // Attach with custom pricing const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan", customize: {"price":{"amount":4900,"interval":"month"}} }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan. @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param customize - Customize the plan to attach. Can override the price, items, free trial, or a combination. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param prorationBehavior - How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param subscriptionId - A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param billingCycleAnchor - Reset the billing cycle anchor immediately with 'now'. (optional) @param planSchedule - When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) @param startsAt - Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription. (optional) @param endsAt - Unix timestamp in milliseconds for when the attached plan should end. (optional) @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @param customLineItems - Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans). (optional) @param processorSubscriptionId - The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one. (optional) @param carryOverBalances - Whether to carry over balances from the previous plan. (optional) @param carryOverUsages - Whether to carry over usages from the previous plan. (optional) @param metadata - Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped. (optional) @param noBillingChanges - If true, skips any billing changes for the attach operation. (optional) @param enablePlanImmediately - If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form. (optional) @param taxRateId - Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items. (optional) @returns A billing response with customer ID, invoice details, and payment URL (if checkout required). tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. version: type: number description: The version of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / update_items. add_items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Items to add to the plan. remove_items: type: array items: type: object properties: feature_id: type: string description: Match items linked to this feature. billing_method: enum: - prepaid - usage_based type: string description: Match items with this billing method (prepaid or usage_based). interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Match items with this interval. title: PlanItemFilter description: Filter for matching plan items. All provided fields must match (AND). description: Filters selecting items to remove from the plan. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. description: Customize the plan to attach. Can override the price, items, free trial, or a combination. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. proration_behavior: enum: - prorate_immediately - none type: string description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required subscription_id: type: string description: A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. new_billing_subscription: type: boolean description: Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now'. plan_schedule: enum: - immediate - end_of_cycle type: string description: When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. starts_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription. ends_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should end. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. custom_line_items: type: array items: type: object properties: amount: type: number description: Amount in dollars for this line item (e.g. 10.50). Can be negative for credits. description: type: string description: Description for the line item. required: - amount - description description: Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans). processor_subscription_id: type: string description: The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one. carry_over_balances: type: object properties: enabled: type: boolean description: Whether to carry over balances from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over balances from. If left undefined, all features will be carried over. required: - enabled description: Whether to carry over balances from the previous plan. carry_over_usages: type: object properties: enabled: type: boolean description: Whether to carry over usages from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over. required: - enabled description: Whether to carry over usages from the previous plan. metadata: type: object propertyNames: type: string additionalProperties: type: string description: Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped. no_billing_changes: type: boolean description: If true, skips any billing changes for the attach operation. enable_plan_immediately: type: boolean description: If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form. tax_rate_id: type: string description: Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items. required: - customer_id - plan_id title: AttachParams examples: - customer_id: cus_123 plan_id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity, if the plan was attached to an entity. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed type: string description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason description: Details about any action required to complete the payment. Present when the payment could not be processed automatically. required: - customer_id - payment_url examples: - customer_id: cus_123 payment_url: https://checkout.stripe.com/... x-speakeasy-name-override: attach parameters: - *a1 /v1/billing.create_schedule: post: operationId: createSchedule description: |- Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times. Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time. @example ```typescript // Schedule a transition from a trial plan to a paid plan const response = await client.billing.createSchedule({ customerId: "cus_123", phases: [{"startsAt":1780584084429,"plans":[{"planId":"trial_plan"}]},{"startsAt":1781793684429,"plans":[{"planId":"pro_plan"}]}] }); ``` @param customerId - The ID of the customer to create the schedule for. @param entityId - Optional entity ID for an entity-scoped schedule. (optional) @param invoiceMode - Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. (optional) @param discounts - List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @param redirectMode - Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if_required' only redirects when needed, and 'never' disables redirects. (optional) @param billingBehavior - Whether to prorate the immediate phase. 'none' skips proration charges and credits. (optional) @param billingCycleAnchor - Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time. (optional) @param enablePlanImmediately - If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed. (optional) @param phases - Ordered phase definitions for the schedule. @returns A create-schedule response with the schedule ID, persisted phases, and any required payment or checkout URL. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to create the schedule for. entity_id: type: string description: Optional entity ID for an entity-scoped schedule. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if_required' only redirects when needed, and 'never' disables redirects. default: if_required billing_behavior: enum: - prorate_immediately - none type: string description: Whether to prorate the immediate phase. 'none' skips proration charges and credits. billing_cycle_anchor: const: now description: Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time. enable_plan_immediately: type: boolean description: If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed. phases: type: array prefixItems: - type: object properties: starts_at: type: number description: When this phase should start, in epoch milliseconds. plans: type: array minItems: 1 items: type: object properties: plan_id: type: string description: The ID of the plan to schedule in this phase. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: Optional prepaid feature quantities for this phase's plan. version: type: number description: Optional explicit plan version to schedule. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: {} amount: {} flat_amount: {} description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan. additionalProperties: false description: Customize the plan to schedule. Can override the price, items, or both. subscription_id: type: string description: A unique ID to identify this subscription. Useful when scheduling the same plan multiple times. required: - plan_id description: Plans to materialize for this phase. required: - starts_at - plans items: type: object properties: starts_at: type: number description: When this phase should start, in epoch milliseconds. plans: type: array minItems: 1 items: type: object properties: plan_id: type: string description: The ID of the plan to schedule in this phase. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: Optional prepaid feature quantities for this phase's plan. version: type: number description: Optional explicit plan version to schedule. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: {} amount: {} flat_amount: {} description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan. additionalProperties: false description: Customize the plan to schedule. Can override the price, items, or both. subscription_id: type: string description: A unique ID to identify this subscription. Useful when scheduling the same plan multiple times. required: - plan_id description: Plans to materialize for this phase. required: - starts_at - plans description: Ordered phase definitions for the schedule. required: - customer_id - phases title: CreateScheduleParams examples: - customer_id: cus_123 phases: - starts_at: 1735689600000 plans: - plan_id: trial_plan - starts_at: 1736899200000 plans: - plan_id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: anyOf: - type: string - type: "null" description: The entity ID for the schedule, or null when customer-level. status: enum: - created - pending_payment type: string description: Whether the schedule is fully created or waiting for payment or confirmation to complete. schedule_id: anyOf: - type: string - type: "null" description: The ID of the created schedule. Null when the schedule is waiting on Autumn checkout confirmation. phases: type: array items: type: object properties: phase_id: type: string description: The ID of the persisted phase row. starts_at: type: number description: When this phase starts, in epoch milliseconds. customer_product_ids: type: array items: type: string description: Customer products materialized for this phase. required: - phase_id - starts_at - customer_product_ids description: Persisted phases in ascending starts_at order. Empty when waiting on Autumn checkout confirmation. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed type: string description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason required: - customer_id - entity_id - status - schedule_id - phases - payment_url title: CreateScheduleResponse examples: - customer_id: cus_123 entity_id: null status: created schedule_id: sch_1234 phases: - phase_id: sphs_1111 starts_at: 1735689600000 customer_product_ids: - cus_prod_1111 - phase_id: sphs_2222 starts_at: 1736899200000 customer_product_ids: - cus_prod_2222 invoice: null payment_url: null x-speakeasy-name-override: createSchedule parameters: - *a1 /v1/billing.multi_attach: post: operationId: multiAttach description: |- Attaches multiple plans to a customer in a single request. Creates a single Stripe subscription with all plans consolidated. Use this endpoint when you need to subscribe a customer to multiple plans at once, such as a base plan plus add-ons, or to create a bundle of products. @example ```typescript // Attach multiple plans to a customer const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_seats","featureQuantities":[{"featureId":"seats","quantity":5}]}] }); ``` @example ```typescript // Attach with free trial applied to all plans const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_storage"}], freeTrial: {"durationLength":14,"durationType":"day"} }); ``` @example ```typescript // Attach with custom pricing on one plan const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan","customize":{"price":{"amount":4900,"interval":"month"}}},{"planId":"addon_support"}] }); ``` @param customerId - The ID of the customer to attach the plans to. @param entityId - The ID of the entity to attach the plans to. (optional) @param plans - The list of plans to attach to the customer. @param freeTrial - Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param enablePlanImmediately - If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. (optional) @returns A billing response with customer ID, invoice details, and payment URL (if checkout required). tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plans to. entity_id: type: string description: The ID of the entity to attach the plans to. plans: type: array minItems: 1 items: type: object properties: plan_id: type: string description: The ID of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan. description: Customize the plan to attach. Can override the price or items. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. version: type: number description: The version of the plan to attach. subscription_id: type: string description: A unique ID to identify this subscription. Useful when attaching the same plan multiple times. required: - plan_id description: The list of plans to attach to the customer. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required new_billing_subscription: type: boolean description: Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. enable_plan_immediately: type: boolean description: If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. customer_data: $ref: "#/components/schemas/CustomerData" entity_data: type: object properties: feature_id: type: string description: The feature ID that this entity is associated with name: type: string description: Name of the entity billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. required: - feature_id required: - customer_id - plans title: MultiAttachParams examples: - customer_id: cus_123 plans: - plan_id: pro_plan - plan_id: addon_seats feature_quantities: - feature_id: seats quantity: 5 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity, if the plan was attached to an entity. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed type: string description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason description: Details about any action required to complete the payment. Present when the payment could not be processed automatically. required: - customer_id - payment_url examples: - customer_id: cus_123 invoice: status: paid stripe_id: in_1234 total: 4900 currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null x-speakeasy-name-override: multiAttach parameters: - *a1 /v1/billing.preview_attach: post: operationId: previewAttach description: >- Previews the billing changes that would occur when attaching a plan, without actually making any changes. Use this endpoint to show customers what they will be charged before confirming a subscription change. @example ```typescript // Preview attaching a plan const response = await client.billing.previewAttach({ customerId: "cus_123", planId: "pro_plan" }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan. @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param customize - Customize the plan to attach. Can override the price, items, free trial, or a combination. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param prorationBehavior - How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param subscriptionId - A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param billingCycleAnchor - Reset the billing cycle anchor immediately with 'now'. (optional) @param planSchedule - When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) @param startsAt - Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription. (optional) @param endsAt - Unix timestamp in milliseconds for when the attached plan should end. (optional) @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @param customLineItems - Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans). (optional) @param processorSubscriptionId - The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one. (optional) @param carryOverBalances - Whether to carry over balances from the previous plan. (optional) @param carryOverUsages - Whether to carry over usages from the previous plan. (optional) @param metadata - Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped. (optional) @param noBillingChanges - If true, skips any billing changes for the attach operation. (optional) @param enablePlanImmediately - If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form. (optional) @param taxRateId - Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items. (optional) @returns A preview response with line items, totals, and effective dates for the proposed changes. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. version: type: number description: The version of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / update_items. add_items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Items to add to the plan. remove_items: type: array items: type: object properties: feature_id: type: string description: Match items linked to this feature. billing_method: enum: - prepaid - usage_based type: string description: Match items with this billing method (prepaid or usage_based). interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Match items with this interval. title: PlanItemFilter description: Filter for matching plan items. All provided fields must match (AND). description: Filters selecting items to remove from the plan. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. description: Customize the plan to attach. Can override the price, items, free trial, or a combination. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. proration_behavior: enum: - prorate_immediately - none type: string description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required subscription_id: type: string description: A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. new_billing_subscription: type: boolean description: Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now'. plan_schedule: enum: - immediate - end_of_cycle type: string description: When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. starts_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription. ends_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should end. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. custom_line_items: type: array items: type: object properties: amount: type: number description: Amount in dollars for this line item (e.g. 10.50). Can be negative for credits. description: type: string description: Description for the line item. required: - amount - description description: Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans). processor_subscription_id: type: string description: The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one. carry_over_balances: type: object properties: enabled: type: boolean description: Whether to carry over balances from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over balances from. If left undefined, all features will be carried over. required: - enabled description: Whether to carry over balances from the previous plan. carry_over_usages: type: object properties: enabled: type: boolean description: Whether to carry over usages from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over. required: - enabled description: Whether to carry over usages from the previous plan. metadata: type: object propertyNames: type: string additionalProperties: type: string description: Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped. no_billing_changes: type: boolean description: If true, skips any billing changes for the attach operation. enable_plan_immediately: type: boolean description: If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form. tax_rate_id: type: string description: Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items. required: - customer_id - plan_id title: PreviewAttachParams examples: - customer_id: cus_123 plan_id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity subtotal: type: number description: The total amount in cents before discounts and tax for the current billing period. total: type: number description: The final amount in cents after discounts and tax for the current billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). next_cycle: type: object properties: starts_at: type: number description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number description: The total amount in cents before discounts and tax for the next cycle. total: type: number description: The final amount in cents after discounts and tax for the next cycle. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity description: List of line items for the next billing cycle. usage_line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. required: - display_name - plan_id - feature_id description: List of line items for usage-based features in the next cycle. required: - starts_at - subtotal - total - line_items - usage_line_items description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. expand: type: array items: type: string description: Expand the response with additional data. incoming: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being added or updated. outgoing: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being removed or ended. redirect_to_checkout: type: boolean description: Whether the customer will be redirected to a checkout page if attach is called. checkout_type: anyOf: - enum: - stripe_checkout - autumn_checkout type: string - type: "null" description: The type of checkout that will be used if the customer is redirected to a checkout page. tax: type: object properties: total: type: number description: Total tax amount in major currency units. amount_inclusive: type: number description: Tax included in line item subtotals. amount_exclusive: type: number description: Tax added on top of subtotals. currency: type: string description: Three-letter currency code. status: enum: - complete - incomplete type: string description: Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored). required: - total - amount_inclusive - amount_exclusive - currency - status description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. invoice_credits: type: object properties: balance: type: number description: Stripe customer credit balance available, expressed as a positive number in major currency units. currency: type: string description: Three-letter currency code. required: - balance - currency description: Stripe customer invoice credits preview. required: - customer_id - line_items - subtotal - total - currency - incoming - outgoing - redirect_to_checkout - checkout_type examples: - customerId: charles lineItems: - display_name: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) subtotal: 20 total: 20 discounts: [] subtotal: 20 total: 20 currency: usd x-speakeasy-name-override: previewAttach parameters: - *a1 /v1/billing.preview_multi_attach: post: operationId: previewMultiAttach description: |- Previews the billing changes that would occur when attaching multiple plans, without actually making any changes. Use this endpoint to show customers what they will be charged before confirming a multi-plan subscription. @example ```typescript // Preview attaching multiple plans const response = await client.billing.previewMultiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_seats","featureQuantities":[{"featureId":"seats","quantity":5}]}] }); ``` @param customerId - The ID of the customer to attach the plans to. @param entityId - The ID of the entity to attach the plans to. (optional) @param plans - The list of plans to attach to the customer. @param freeTrial - Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param enablePlanImmediately - If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. (optional) @returns A preview response with line items, totals, and effective dates for the proposed multi-plan attachment. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plans to. entity_id: type: string description: The ID of the entity to attach the plans to. plans: type: array minItems: 1 items: type: object properties: plan_id: type: string description: The ID of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan. description: Customize the plan to attach. Can override the price or items. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. version: type: number description: The version of the plan to attach. subscription_id: type: string description: A unique ID to identify this subscription. Useful when attaching the same plan multiple times. required: - plan_id description: The list of plans to attach to the customer. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required new_billing_subscription: type: boolean description: Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. enable_plan_immediately: type: boolean description: If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. customer_data: $ref: "#/components/schemas/CustomerData" entity_data: type: object properties: feature_id: type: string description: The feature ID that this entity is associated with name: type: string description: Name of the entity billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. required: - feature_id required: - customer_id - plans title: PreviewMultiAttachParams examples: - customer_id: cus_123 plans: - plan_id: pro_plan - plan_id: addon_seats feature_quantities: - feature_id: seats quantity: 5 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity subtotal: type: number description: The total amount in cents before discounts and tax for the current billing period. total: type: number description: The final amount in cents after discounts and tax for the current billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). next_cycle: type: object properties: starts_at: type: number description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number description: The total amount in cents before discounts and tax for the next cycle. total: type: number description: The final amount in cents after discounts and tax for the next cycle. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity description: List of line items for the next billing cycle. usage_line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. required: - display_name - plan_id - feature_id description: List of line items for usage-based features in the next cycle. required: - starts_at - subtotal - total - line_items - usage_line_items description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. expand: type: array items: type: string description: Expand the response with additional data. incoming: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being added or updated. outgoing: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being removed or ended. redirect_to_checkout: type: boolean description: Whether the customer will be redirected to a checkout page if attach is called. checkout_type: anyOf: - enum: - stripe_checkout - autumn_checkout type: string - type: "null" description: The type of checkout that will be used if the customer is redirected to a checkout page. tax: type: object properties: total: type: number description: Total tax amount in major currency units. amount_inclusive: type: number description: Tax included in line item subtotals. amount_exclusive: type: number description: Tax added on top of subtotals. currency: type: string description: Three-letter currency code. status: enum: - complete - incomplete type: string description: Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored). required: - total - amount_inclusive - amount_exclusive - currency - status description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. invoice_credits: type: object properties: balance: type: number description: Stripe customer credit balance available, expressed as a positive number in major currency units. currency: type: string description: Three-letter currency code. required: - balance - currency description: Stripe customer invoice credits preview. required: - customer_id - line_items - subtotal - total - currency - incoming - outgoing - redirect_to_checkout - checkout_type examples: - customerId: charles lineItems: - display_name: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) subtotal: 20 total: 20 discounts: [] subtotal: 20 total: 20 currency: usd x-speakeasy-name-override: previewMultiAttach parameters: - *a1 /v1/billing.update: post: operationId: billingUpdate description: >- Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration. Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings. @example ```typescript // Update prepaid feature quantity const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [{"featureId":"seats","quantity":10}] }); ``` @example ```typescript // Cancel a subscription at end of billing cycle const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", cancelAction: "cancel_end_of_cycle" }); ``` @example ```typescript // Uncancel a subscription at the end of the billing cycle const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", cancelAction: "uncancel" }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product. (optional) @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param customize - Customize the plan to attach. Can override the price, items, free trial, or a combination. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param prorationBehavior - How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param subscriptionId - A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param cancelAction - Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. (optional) @param billingCycleAnchor - Reset the billing cycle anchor immediately with 'now' (optional) @param noBillingChanges - If true, the subscription is updated internally without applying billing changes in Stripe. (optional) @param recalculateBalances - Controls whether balances should be recalculated during the subscription update. (optional) @returns A billing response with customer ID, invoice details, and payment URL (if next action is required). tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. version: type: number description: The version of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / update_items. add_items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Items to add to the plan. remove_items: type: array items: type: object properties: feature_id: type: string description: Match items linked to this feature. billing_method: enum: - prepaid - usage_based type: string description: Match items with this billing method (prepaid or usage_based). interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Match items with this interval. title: PlanItemFilter description: Filter for matching plan items. All provided fields must match (AND). description: Filters selecting items to remove from the plan. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. description: Customize the plan to attach. Can override the price, items, free trial, or a combination. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. proration_behavior: enum: - prorate_immediately - none type: string description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required subscription_id: type: string description: A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel type: string description: Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now' no_billing_changes: type: boolean description: If true, the subscription is updated internally without applying billing changes in Stripe. recalculate_balances: type: object properties: enabled: type: boolean description: If true, recalculates balances during the subscription update. Only applicable when updating feature quantities. required: - enabled description: Controls whether balances should be recalculated during the subscription update. required: - customer_id title: UpdateSubscriptionParams examples: - customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 10 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity, if the plan was attached to an entity. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed type: string description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason description: Details about any action required to complete the payment. Present when the payment could not be processed automatically. required: - customer_id - payment_url examples: - customer_id: cus_123 invoice: status: paid stripe_id: in_1234 total: 1500 currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null x-speakeasy-name-override: update parameters: - *a1 /v1/billing.preview_update: post: operationId: previewUpdate description: >- Previews the billing changes that would occur when updating a subscription, without actually making any changes. Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications. @example ```typescript // Preview updating seat quantity const response = await client.billing.previewUpdate({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [{"featureId":"seats","quantity":15}] }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product. (optional) @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param customize - Customize the plan to attach. Can override the price, items, free trial, or a combination. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param prorationBehavior - How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. (optional) @param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional) @param subscriptionId - A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param cancelAction - Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. (optional) @param billingCycleAnchor - Reset the billing cycle anchor immediately with 'now' (optional) @param noBillingChanges - If true, the subscription is updated internally without applying billing changes in Stripe. (optional) @param recalculateBalances - Controls whether balances should be recalculated during the subscription update. (optional) @returns A preview response with line items showing prorated charges or credits for the proposed changes. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. version: type: number description: The version of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / update_items. add_items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Items to add to the plan. remove_items: type: array items: type: object properties: feature_id: type: string description: Match items linked to this feature. billing_method: enum: - prepaid - usage_based type: string description: Match items with this billing method (prepaid or usage_based). interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Match items with this interval. title: PlanItemFilter description: Filter for matching plan items. All provided fields must match (AND). description: Filters selecting items to remove from the plan. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. description: Customize the plan to attach. Can override the price, items, free trial, or a combination. invoice_mode: type: object properties: enabled: type: boolean description: When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. enable_plan_immediately: type: boolean default: false description: If true, enables the plan immediately even though the invoice is not paid yet. finalize: type: boolean default: true description: If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. invoice_template_id: type: string description: ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. net_terms_days: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 description: Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). required: - enabled description: Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. proration_behavior: enum: - prorate_immediately - none type: string description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. redirect_mode: enum: - always - if_required - never type: string description: Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. default: if_required subscription_id: type: string description: A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel type: string description: Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now' no_billing_changes: type: boolean description: If true, the subscription is updated internally without applying billing changes in Stripe. recalculate_balances: type: object properties: enabled: type: boolean description: If true, recalculates balances during the subscription update. Only applicable when updating feature quantities. required: - enabled description: Controls whether balances should be recalculated during the subscription update. required: - customer_id title: PreviewUpdateParams examples: - customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 15 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity description: List of line items for the current billing period. subtotal: type: number description: The total amount in cents before discounts and tax for the current billing period. total: type: number description: The final amount in cents after discounts and tax for the current billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). next_cycle: type: object properties: starts_at: type: number description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number description: The total amount in cents before discounts and tax for the next cycle. total: type: number description: The final amount in cents after discounts and tax for the next cycle. line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. description: type: string description: A detailed description of the line item. subtotal: type: number description: The amount in cents before discounts and tax for this line item. total: type: number description: The final amount in cents after discounts and tax for this line item. discounts: type: array items: type: object properties: amount_off: type: number percent_off: type: number reward_id: type: string reward_name: type: string required: - amount_off default: [] description: List of discounts applied to this line item. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. quantity: type: number description: The quantity of the line item. required: - display_name - description - subtotal - total - plan_id - feature_id - quantity description: List of line items for the next billing cycle. usage_line_items: type: array items: type: object properties: display_name: type: string description: The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. plan_id: type: string description: The ID of the plan that this line item belongs to. feature_id: anyOf: - type: string - type: "null" description: The ID of the feature that this line item belongs to. period: type: object properties: start: type: number description: The start of the period in milliseconds since the Unix epoch. end: type: number description: The end of the period in milliseconds since the Unix epoch. required: - start - end description: The period of time that this line item is being charged for. required: - display_name - plan_id - feature_id description: List of line items for usage-based features in the next cycle. required: - starts_at - subtotal - total - line_items - usage_line_items description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. expand: type: array items: type: string description: Expand the response with additional data. incoming: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being added or updated. outgoing: type: array items: type: object properties: plan_id: type: string description: The ID of the plan affected by this preview change. plan: $ref: "#/components/schemas/Plan" description: The full plan object if it was expanded in the response. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the adjustable feature included in this change. quantity: type: number description: The quantity that will apply for this feature in the change. required: - feature_id - quantity description: The feature quantity selections associated with this plan change. effective_at: anyOf: - type: number - type: "null" description: When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. canceled_at: anyOf: - type: number - type: "null" description: When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. expires_at: anyOf: - type: number - type: "null" description: When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. required: - plan_id - feature_quantities - effective_at - canceled_at - expires_at description: Products or subscription changes being removed or ended. intent: enum: - update_plan - update_quantity - cancel_immediately - cancel_end_of_cycle - uncancel - none type: string tax: type: object properties: total: type: number description: Total tax amount in major currency units. amount_inclusive: type: number description: Tax included in line item subtotals. amount_exclusive: type: number description: Tax added on top of subtotals. currency: type: string description: Three-letter currency code. status: enum: - complete - incomplete type: string description: Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored). required: - total - amount_inclusive - amount_exclusive - currency - status description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. invoice_credits: type: object properties: balance: type: number description: Stripe customer credit balance available, expressed as a positive number in major currency units. currency: type: string description: Three-letter currency code. required: - balance - currency description: Stripe customer invoice credits preview. required: - customer_id - line_items - subtotal - total - currency - incoming - outgoing - intent examples: - customerId: charles lineItems: - display_name: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) subtotal: 20 total: 20 discounts: [] subtotal: 20 total: 20 currency: usd x-speakeasy-name-override: previewUpdate parameters: - *a1 /v1/billing.open_customer_portal: post: operationId: openCustomerPortal description: Create a billing portal session for a customer to manage their subscription. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to open the billing portal for. configuration_id: type: string description: Stripe billing portal configuration ID. Create configurations in your Stripe dashboard. return_url: type: string description: URL to redirect to when back button is clicked in the billing portal required: - customer_id title: OpenCustomerPortalParams examples: - customer_id: cus_123 return_url: https://useautumn.com responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the billing portal session url: type: string description: URL to the billing portal required: - customer_id - url examples: - customer_id: cus_123 url: https://billing.stripe.com/session/... x-speakeasy-name-override: openCustomerPortal parameters: - *a1 /v1/billing.setup_payment: post: operationId: setupPayment description: Create a payment setup session for a customer to add or update their payment method. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: If specified, the plan will be attached to the customer after setup. feature_quantities: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to set quantity for. quantity: type: number minimum: 0 description: The quantity of the feature. adjustable: type: boolean description: Whether the customer can adjust the quantity. required: - feature_id title: FeatureQuantity description: Quantity configuration for a prepaid feature. description: If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. version: type: number description: The version of the plan to attach. customize: type: object properties: price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval title: BasePrice description: Base price configuration for a plan. - type: "null" description: Override the base price of the plan. Pass null to remove the base price. items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / update_items. add_items: type: array items: type: object properties: feature_id: type: string description: The ID of the feature to configure. included: type: number description: Number of free units included. Balance resets to this each interval for consumable features. unlimited: type: boolean description: If true, customer has unlimited access to this feature. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. interval_count: type: number description: Number of intervals between resets. Defaults to 1. required: - interval description: Reset configuration for consumable features. Omit for non-consumable features like seats. price: type: object properties: amount: type: number description: Price per billing_units after included usage. Either 'amount' or 'tiers' is required. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: type: number required: - to description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume type: string interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Billing interval. For consumable features, should match reset.interval. interval_count: type: number default: 1 description: Number of intervals per billing cycle. Defaults to 1. billing_units: type: number default: 1 description: Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). billing_method: enum: - prepaid - usage_based type: string description: "'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go." max_purchase: type: number description: Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. required: - interval - billing_method description: Pricing for usage beyond included units. Omit for free features. proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string description: Credit behavior when quantity decreases mid-cycle. required: - on_increase - on_decrease description: Proration settings for prepaid features. Controls mid-cycle quantity change billing. rollover: type: object properties: max: type: number description: Max rollover units. Omit for unlimited rollover. max_percentage: type: number description: Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. expiry_duration_type: enum: - month - forever type: string description: When rolled over units expire. expiry_duration_length: type: number description: Number of periods before expiry. required: - expiry_duration_type description: Rollover config for unused units. If set, unused included units carry over. required: - feature_id title: PlanItem description: Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings. description: Items to add to the plan. remove_items: type: array items: type: object properties: feature_id: type: string description: Match items linked to this feature. billing_method: enum: - prepaid - usage_based type: string description: Match items with this billing method (prepaid or usage_based). interval: enum: - one_off - week - month - quarter - semi_annual - year type: string description: Match items with this interval. title: PlanItemFilter description: Filter for matching plan items. All provided fields must match (AND). description: Filters selecting items to remove from the plan. free_trial: anyOf: - type: object properties: duration_length: type: number description: Number of duration_type periods the trial lasts. duration_type: enum: - day - month - year type: string default: month description: Unit of time for the trial ('day', 'month', 'year'). card_required: type: boolean default: true description: If true, payment method required to start trial. Customer is charged after trial ends. on_end: enum: - bill - revert type: string description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. required: - duration_length title: FreeTrialParams description: Free trial configuration for a plan. - type: "null" description: Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. description: Customize the plan to attach. Can override the price, items, free trial, or a combination. proration_behavior: enum: - prorate_immediately - none type: string description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. subscription_id: type: string description: A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan. discounts: type: array items: type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. promotion_code: type: string description: The promotion code to apply as a discount. title: AttachDiscount description: A discount to apply. Can be either a reward ID or a promotion code. description: List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. success_url: type: string description: URL to redirect to after successful checkout. billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now'. starts_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription. ends_at: type: integer minimum: 0 maximum: 9007199254740991 description: Unix timestamp in milliseconds for when the attached plan should end. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. custom_line_items: type: array items: type: object properties: amount: type: number description: Amount in dollars for this line item (e.g. 10.50). Can be negative for credits. description: type: string description: Description for the line item. required: - amount - description description: Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans). processor_subscription_id: type: string description: The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one. carry_over_balances: type: object properties: enabled: type: boolean description: Whether to carry over balances from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over balances from. If left undefined, all features will be carried over. required: - enabled description: Whether to carry over balances from the previous plan. carry_over_usages: type: object properties: enabled: type: boolean description: Whether to carry over usages from the previous plan. feature_ids: type: array items: type: string description: The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over. required: - enabled description: Whether to carry over usages from the previous plan. metadata: type: object propertyNames: type: string additionalProperties: type: string description: Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped. no_billing_changes: type: boolean description: If true, skips any billing changes for the attach operation. enable_plan_immediately: type: boolean description: If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form. tax_rate_id: type: string description: Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items. required: - customer_id title: SetupPaymentParams examples: - customer_id: cus_123 success_url: https://example.com/account/billing responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer entity_id: type: string description: The ID of the entity the plan (if specified) will be attached to after setup. url: type: string description: URL to redirect the customer to setup their payment. required: - customer_id - url title: SetupPaymentResponse examples: - customer_id: cus_123 url: https://checkout.stripe.com/... x-speakeasy-name-override: setupPayment parameters: - *a1 /v1/balances.create: post: operationId: createBalance description: Create a balance for a customer feature. tags: - balances 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). included_grant: type: number description: The initial balance amount to grant. For metered features, this is the number of units the customer can use. unlimited: type: boolean description: If true, the balance has unlimited usage. Cannot be combined with 'included_grant'. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: The interval at which the balance resets (e.g., 'month', 'day', 'year'). interval_count: type: number description: "Number of intervals between resets. Defaults to 1 (e.g., interval_count: 2 with interval: 'month' resets every 2 months)." required: - interval description: Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets. rollover: 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 description: Rollover configuration for the balance. expires_at: type: number description: Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset. balance_id: type: string description: A unique identifier for this balance. Use this to target the balance in future update / delete calls. required: - customer_id - feature_id title: CreateBalanceParams examples: - customer_id: cus_123 feature_id: api_calls included: 1000 reset: interval: month responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: create parameters: - *a1 /v1/balances.update: post: operationId: updateBalance description: Update a customer balance. tags: - balances 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). remaining: type: number description: Set the remaining balance to this exact value. Cannot be combined with add_to_balance. add_to_balance: type: number description: Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance. usage: type: number description: The usage amount to update. Cannot be combined with remaining or add_to_balance. interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals. included_grant: type: number description: Set the granted balance to this exact value. balance_id: type: string description: Target a specific balance by its ID (set on create). Use when the customer has multiple balances for the same feature. next_reset_at: type: number description: The next reset time for the balance. If there are multiple breakdowns, this will update the breakdown with the next reset time. required: - customer_id - feature_id title: UpdateBalanceParams examples: - customer_id: cus_123 feature_id: api_calls remaining: 5 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: update parameters: - *a1 /v1/balances.delete: post: operationId: deleteBalance description: Delete a balance for a customer feature. Can only delete a balance that is not attached to a price (eg. you cannot delete messages that have an overage price). tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity. feature_id: type: string description: The ID of the feature. balance_id: type: string description: The ID of the balance to delete. recalculate_balances: type: boolean description: If true, deduct the deleted balance's remaining amount from the customer's other balances for the same feature after deletion. interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year type: string description: Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals. required: - customer_id title: DeleteBalanceParams examples: - customer_id: cus_123 feature_id: api_calls responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - *a1 /v1/balances.finalize: post: operationId: finalizeLock description: Finalize a previously locked balance. Use 'confirm' to commit the deduction, or 'release' to return the held balance. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: lock_id: type: string description: The lock ID that was passed into the previous check call. action: enum: - confirm - release type: string description: Use 'confirm' to commit the deduction, or 'release' to return the held balance. override_value: type: number description: Additional properties to attach to this finalize lock event. properties: type: object propertyNames: type: string additionalProperties: {} description: Additional properties to attach to this finalize lock event. required: - lock_id - action title: FinalizeBalanceParams examples: - lock_id: lock_abc123 action: confirm - lock_id: lock_abc123 action: confirm override_value: 3 - lock_id: lock_abc123 action: release responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success "202": description: Accepted. Autumn is experiencing degraded service from a downstream provider, so the finalize request was allowed fail-open. content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: finalize parameters: - *a1 /v1/balances.check: post: operationId: check 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. @example ```typescript // Check access for a feature const response = await client.check({ customerId: "cus_123", featureId: "messages" }); ``` @example ```typescript // Check and consume 3 units in one call const response = await client.check({ customerId: "cus_123", featureId: "messages", requiredBalance: 3, sendEvent: true, }); ``` @param customerId - The ID of the customer. @param featureId - The ID of the feature. @param entityId - The ID of the entity for entity-scoped balances (e.g., per-seat limits). (optional) @param requiredBalance - Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1. (optional) @param properties - Additional properties to attach to the usage event if send_event is true. (optional) @param sendEvent - 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. (optional) @param lock - Reserve units of a feature upfront by passing a lock_id, then call balances.finalize to confirm or release the hold. (optional) @param withPreview - If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls. (optional) @returns Whether access is allowed, plus the current balance for that feature. If Autumn is experiencing degraded service from a downstream provider, the API may return 202 and allow access fail-open. requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. feature_id: type: string description: The ID of the feature. entity_id: type: string description: The ID of the entity for entity-scoped balances (e.g., per-seat limits). required_balance: type: number description: "Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1." properties: type: object propertyNames: type: string additionalProperties: {} description: Additional properties to attach to the usage event if send_event is true. send_event: type: boolean description: If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call. lock: type: object properties: lock_id: type: string maxLength: 256 description: A unique identifier for this lock. Used to finalize the lock later via balances.finalize. enabled: const: true description: Must be true to enable locking. expires_at: type: number description: Unix timestamp (ms) when the lock automatically expires and releases the held balance. required: - lock_id - enabled description: Reserve units of a feature upfront by passing a lock_id, then call balances.finalize to confirm or release the hold. with_preview: type: boolean description: If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls. required: - customer_id - feature_id title: CheckParams examples: - customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages required_balance: 3 send_event: true 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard - type: "null" description: The flag associated with this check, if any. preview: type: object properties: scenario: enum: - usage_limit - feature_flag type: string description: The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan. title: type: string description: A title suitable for displaying in a paywall or upgrade modal. message: type: string description: A message explaining why access was denied. feature_id: type: string description: The ID of the feature that was checked. feature_name: type: string description: The display name of the feature. products: type: array items: type: object properties: id: type: string description: The ID of the product you set when creating the product name: type: string description: The name of the product group: anyOf: - type: string - type: "null" description: Product group which this product belongs to env: enum: - sandbox - live type: string description: The environment of the product is_add_on: type: boolean description: Whether the product is an add-on and can be purchased alongside other products is_default: type: boolean description: Whether the product is the default product archived: type: boolean description: Whether this product has been archived and is no longer available version: type: number description: The current version of the product created_at: type: number description: The timestamp of when the product was created in milliseconds since epoch items: type: array items: type: object properties: type: anyOf: - enum: - feature - priced_feature - price type: string - type: "null" description: The type of the product item feature_id: anyOf: - type: string - type: "null" description: The feature ID of the product item. If the item is a fixed price, should be `null` feature_type: anyOf: - enum: - single_use - continuous_use - boolean - static type: string - type: "null" description: Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats. included_usage: anyOf: - anyOf: - type: number - const: inf - type: "null" description: The amount of usage included for this feature. interval: anyOf: - enum: - minute - hour - day - week - month - quarter - semi_annual - year type: string - type: "null" description: The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off. interval_count: anyOf: - type: number - type: "null" description: The interval count of the product item. price: anyOf: - type: number - type: "null" description: The price of the product item. Should be `null` if tiered pricing is set. tiers: anyOf: - type: array items: anyOf: - {} - type: "null" - type: "null" description: Tiered pricing for the product item. Not applicable for fixed price items. tier_behavior: anyOf: - enum: - graduated - volume type: string - type: "null" description: "How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated." usage_model: anyOf: - enum: - prepaid - pay_per_use type: string - type: "null" description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. billing_units: anyOf: - type: number - type: "null" description: The amount per billing unit (eg. $9 / 250 units) reset_usage_when_enabled: anyOf: - type: boolean - type: "null" description: Whether the usage should be reset when the product is enabled. entity_feature_id: anyOf: - type: string - type: "null" description: The entity feature ID of the product item if applicable. display: anyOf: - type: object properties: primary_text: type: string secondary_text: anyOf: - type: string - type: "null" required: - primary_text - type: "null" description: The display of the product item. quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer has prepaid for. next_cycle_quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer will prepay for in the next cycle. config: anyOf: - type: object properties: rollover: anyOf: - type: object properties: max: anyOf: - type: number - type: "null" max_percentage: anyOf: - type: number - type: "null" duration: enum: - month - forever type: string default: month length: type: number required: - length - type: "null" on_increase: anyOf: - enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string - type: "null" on_decrease: anyOf: - enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string - type: "null" - type: "null" description: Configuration for rollover and proration behavior of the feature. description: Product item defining features and pricing within a product description: Array of product items that define the product's features and pricing free_trial: anyOf: - type: object properties: duration: enum: - day - month - year type: string description: The duration type of the free trial length: type: number description: The length of the duration type specified unique_fingerprint: type: boolean description: Whether the free trial is limited to one per customer fingerprint card_required: type: boolean description: Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file. on_end: anyOf: - enum: - bill - revert type: string - type: "null" description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. trial_available: anyOf: - type: boolean default: true - type: "null" description: Used in customer context. Whether the free trial is available for the customer if they were to attach the product. required: - duration - length - unique_fingerprint - card_required - type: "null" description: Free trial configuration for this product, if available base_variant_id: anyOf: - type: string - type: "null" description: ID of the base variant this product is derived from 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 "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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard - type: "null" description: The flag associated with this check, if any. preview: type: object properties: scenario: enum: - usage_limit - feature_flag type: string description: The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan. title: type: string description: A title suitable for displaying in a paywall or upgrade modal. message: type: string description: A message explaining why access was denied. feature_id: type: string description: The ID of the feature that was checked. feature_name: type: string description: The display name of the feature. products: type: array items: type: object properties: id: type: string description: The ID of the product you set when creating the product name: type: string description: The name of the product group: anyOf: - type: string - type: "null" description: Product group which this product belongs to env: enum: - sandbox - live type: string description: The environment of the product is_add_on: type: boolean description: Whether the product is an add-on and can be purchased alongside other products is_default: type: boolean description: Whether the product is the default product archived: type: boolean description: Whether this product has been archived and is no longer available version: type: number description: The current version of the product created_at: type: number description: The timestamp of when the product was created in milliseconds since epoch items: type: array items: type: object properties: type: anyOf: - enum: - feature - priced_feature - price type: string - type: "null" description: The type of the product item feature_id: anyOf: - type: string - type: "null" description: The feature ID of the product item. If the item is a fixed price, should be `null` feature_type: anyOf: - enum: - single_use - continuous_use - boolean - static type: string - type: "null" description: Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats. included_usage: anyOf: - anyOf: - type: number - const: inf - type: "null" description: The amount of usage included for this feature. interval: anyOf: - enum: - minute - hour - day - week - month - quarter - semi_annual - year type: string - type: "null" description: The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off. interval_count: anyOf: - type: number - type: "null" description: The interval count of the product item. price: anyOf: - type: number - type: "null" description: The price of the product item. Should be `null` if tiered pricing is set. tiers: anyOf: - type: array items: anyOf: - {} - type: "null" - type: "null" description: Tiered pricing for the product item. Not applicable for fixed price items. tier_behavior: anyOf: - enum: - graduated - volume type: string - type: "null" description: "How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated." usage_model: anyOf: - enum: - prepaid - pay_per_use type: string - type: "null" description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. billing_units: anyOf: - type: number - type: "null" description: The amount per billing unit (eg. $9 / 250 units) reset_usage_when_enabled: anyOf: - type: boolean - type: "null" description: Whether the usage should be reset when the product is enabled. entity_feature_id: anyOf: - type: string - type: "null" description: The entity feature ID of the product item if applicable. display: anyOf: - type: object properties: primary_text: type: string secondary_text: anyOf: - type: string - type: "null" required: - primary_text - type: "null" description: The display of the product item. quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer has prepaid for. next_cycle_quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer will prepay for in the next cycle. config: anyOf: - type: object properties: rollover: anyOf: - type: object properties: max: anyOf: - type: number - type: "null" max_percentage: anyOf: - type: number - type: "null" duration: enum: - month - forever type: string default: month length: type: number required: - length - type: "null" on_increase: anyOf: - enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle type: string - type: "null" on_decrease: anyOf: - enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations type: string - type: "null" - type: "null" description: Configuration for rollover and proration behavior of the feature. description: Product item defining features and pricing within a product description: Array of product items that define the product's features and pricing free_trial: anyOf: - type: object properties: duration: enum: - day - month - year type: string description: The duration type of the free trial length: type: number description: The length of the duration type specified unique_fingerprint: type: boolean description: Whether the free trial is limited to one per customer fingerprint card_required: type: boolean description: Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file. on_end: anyOf: - enum: - bill - revert type: string - type: "null" description: Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. trial_available: anyOf: - type: boolean default: true - type: "null" description: Used in customer context. Whether the free trial is available for the customer if they were to attach the product. required: - duration - length - unique_fingerprint - card_required - type: "null" description: Free trial configuration for this product, if available base_variant_id: anyOf: - type: string - type: "null" description: ID of the base variant this product is derived from 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 x-speakeasy-name-override: check parameters: - *a1 /v1/balances.track: post: operationId: track description: >- Records usage for a customer feature and returns updated balances. Use this after an action happens to decrement usage, or send a negative value to credit balance back. @example ```typescript // Track one message event const response = await client.track({ customerId: "cus_123", featureId: "messages", value: 1 }); ``` @example ```typescript // Track an event mapped to multiple features const response = await client.track({ customerId: "cus_123", eventName: "ai_chat_request", value: 1 }); ``` @param customerId - The ID of the customer. @param featureId - The ID of the feature to track usage for. Required if event_name is not provided. (optional) @param entityId - The ID of the entity for entity-scoped balances (e.g., per-seat limits). (optional) @param eventName - Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event. (optional) @param value - The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat). (optional) @param properties - Additional properties to attach to this usage event. (optional) @param async - If true, enqueue the event for asynchronous processing and return 202 immediately. The response will not include balance information. (optional) @returns The usage value recorded, with either a single updated balance or a map of updated balances. If Autumn is experiencing degraded service from a downstream provider, the API may return 202 after accepting the event for replay so it can be tracked as soon as the service is restored. 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 to track usage for. Required if event_name is not provided. entity_id: type: string description: The ID of the entity for entity-scoped balances (e.g., per-seat limits). event_name: type: string minLength: 1 description: Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event. value: type: number description: The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat). properties: type: object propertyNames: type: string additionalProperties: {} description: Additional properties to attach to this usage event. async: type: boolean description: If true, enqueue the event for asynchronous processing and return 202 immediately. The response will not include balance information. lock: type: object properties: lock_id: type: string maxLength: 256 description: A unique identifier for this lock. Used to finalize the lock later via balances.finalize. enabled: const: true description: Must be true to enable locking. expires_at: type: number description: Unix timestamp (ms) when the lock automatically expires and releases the held balance. required: - lock_id - enabled required: - customer_id title: TrackParams examples: - customer_id: cus_123 feature_id: messages value: 1 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer whose usage was tracked. entity_id: type: string description: The ID of the entity, if entity-scoped tracking was performed. event_name: type: string description: The event name that was tracked, if event_name was used instead of feature_id. value: type: number description: The amount of usage that was recorded. balance: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features. balances: type: object propertyNames: type: string additionalProperties: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: Map of feature_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature. deductions: type: array items: type: object properties: balance_id: type: string description: ID of the underlying balance row that was deducted from (customer_entitlement or rollover). feature_id: type: string description: The feature this balance belongs to. plan_id: anyOf: - type: string - type: "null" description: ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple). 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 the balance this deduction came from, or null if the balance doesn't reset. value: type: number description: Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value). required: - balance_id - feature_id - plan_id - reset - value description: Per-balance breakdown of what this event deducted. A single event can consume from multiple balance rows when credit systems or rollovers are involved; this surfaces each one so callers can build per-feature usage views without polling. required: - customer_id - value - balance examples: - customer_id: cus_123 value: 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 deductions: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 feature_id: messages plan_id: pro reset: interval: month resets_at: 1781288736881 value: 1 "202": description: Accepted. Autumn is experiencing degraded service from a downstream provider, so the event was accepted for replay and will be tracked as soon as the service is restored. content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer whose usage was tracked. entity_id: type: string description: The ID of the entity, if entity-scoped tracking was performed. event_name: type: string description: The event name that was tracked, if event_name was used instead of feature_id. value: type: number description: The amount of usage that was recorded. balance: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features. balances: type: object propertyNames: type: string additionalProperties: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: Map of feature_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature. deductions: type: array items: type: object properties: balance_id: type: string description: ID of the underlying balance row that was deducted from (customer_entitlement or rollover). feature_id: type: string description: The feature this balance belongs to. plan_id: anyOf: - type: string - type: "null" description: ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple). 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 the balance this deduction came from, or null if the balance doesn't reset. value: type: number description: Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value). required: - balance_id - feature_id - plan_id - reset - value description: Per-balance breakdown of what this event deducted. A single event can consume from multiple balance rows when credit systems or rollovers are involved; this surfaces each one so callers can build per-feature usage views without polling. required: - customer_id - value - balance examples: - customer_id: cus_123 value: 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 deductions: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 feature_id: messages plan_id: pro reset: interval: month resets_at: 1781288736881 value: 1 x-speakeasy-name-override: track parameters: - *a1 /v1/balances.batch_track: post: operationId: batchTrack description: Enqueue up to 1000 usage events for asynchronous processing. Items are validated synchronously up front; validated items are then enqueued via SQS for background deduction by workers. The response returns 202 immediately and does not include balance information. On partial enqueue failure (some items fail to enqueue, others succeed), the endpoint still returns 202 and logs the failures server-side; clients should NOT retry, because retrying re-enqueues the already-succeeded items. A 503 is returned only when zero items were successfully enqueued (queue entirely unavailable) — that case is safe to retry. requestBody: required: true content: application/json: schema: type: array minItems: 1 maxItems: 1000 items: type: object properties: customer_id: type: string description: The ID of the customer. feature_id: type: string description: The ID of the feature to track usage for. Required if event_name is not provided. entity_id: type: string description: The ID of the entity for entity-scoped balances (e.g., per-seat limits). event_name: type: string minLength: 1 description: Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event. value: type: number description: The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat). properties: type: object propertyNames: type: string additionalProperties: {} description: Additional properties to attach to this usage event. async: type: boolean description: If true, enqueue the event for asynchronous processing and return 202 immediately. The response will not include balance information. lock: type: object properties: lock_id: type: string maxLength: 256 description: A unique identifier for this lock. Used to finalize the lock later via balances.finalize. enabled: const: true description: Must be true to enable locking. expires_at: type: number description: Unix timestamp (ms) when the lock automatically expires and releases the held balance. required: - lock_id - enabled required: - customer_id title: BatchTrackParams examples: - - customer_id: cus_123 feature_id: messages value: 1 - customer_id: cus_123 event_name: message.sent value: 1 responses: "202": description: "Batch accepted. All items passed synchronous validation. Enqueue is best-effort: partial failures (some items enqueued, some not) are logged server-side and are NOT surfaced in the response body; clients must not retry on 202. See the endpoint description for full partial-failure semantics." content: application/json: schema: type: object properties: success: const: true required: - success examples: - success: true x-speakeasy-name-override: batchTrack parameters: - *a1 /v1/events.list: post: operationId: listEvents description: List usage events for your organization. Filter by customer, feature, or time range. tags: - events requestBody: required: true content: application/json: schema: type: object properties: start_cursor: type: string default: "" description: Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages. limit: type: integer minimum: 1 maximum: 5000 default: 50 description: Number of items to return. Default 50, hard ceiling 5000. customer_id: type: string description: Filter events by customer ID entity_id: type: string minLength: 1 description: Filter events by entity ID (e.g., per-seat or per-resource) feature_id: anyOf: - type: string minLength: 1 - type: array items: type: string minLength: 1 description: Filter by specific feature ID(s) custom_range: type: object properties: start: type: number description: Filter events after this timestamp (epoch milliseconds) end: type: number description: Filter events before this timestamp (epoch milliseconds) description: Filter events by time range title: EventsListParams examples: - start_cursor: "" customer_id: cus_123 limit: 50 - start_cursor: "" feature_id: api_calls custom_range: start: 1704067200000 end: 1706745600000 responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: Event ID (KSUID) timestamp: type: number description: Event timestamp (epoch milliseconds) feature_id: type: string description: ID of the feature that the event belongs to customer_id: type: string description: Customer identifier value: type: number description: Event value/count properties: type: object propertyNames: type: string additionalProperties: {} description: Event properties (JSON) deductions: anyOf: - type: array items: type: object properties: balance_id: type: string description: ID of the underlying balance row that was deducted from (customer_entitlement or rollover). feature_id: type: string description: The feature this balance belongs to. plan_id: anyOf: - type: string - type: "null" description: ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple). 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 the balance this deduction came from, or null if the balance doesn't reset. value: type: number description: Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value). required: - balance_id - feature_id - plan_id - reset - value - type: "null" description: Per-balance breakdown of what this event deducted. Null for events ingested before deductions were tracked; an empty array means the event was accepted but no balance moved. required: - id - timestamp - feature_id - customer_id - value - properties - deductions description: Items for current page. next_cursor: anyOf: - type: string - type: "null" description: Opaque cursor for the next page. Null when there are no more results. required: - list - next_cursor examples: - list: - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg timestamp: 1765958215459 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 30 properties: {} deductions: - balance_id: cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12 feature_id: credits plan_id: pro reset: interval: month resets_at: 1765958215459 value: 30 - id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM timestamp: 1765956512057 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 49 properties: {} deductions: null next_cursor: eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ x-speakeasy-name-override: list parameters: - *a1 /v1/events.aggregate: post: operationId: aggregateEvents description: Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property. tags: - events requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string minLength: 1 description: Customer ID to aggregate events for entity_id: type: string minLength: 1 description: Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits) feature_id: anyOf: - type: string minLength: 1 - type: array items: type: string minLength: 1 description: Feature ID(s) to aggregate events for group_by: type: string description: Property to group events by (e.g. "properties.region"), or "$customer_id" / "$entity_id" / "$plan_id" to group by those columns range: enum: - 24h - 7d - 30d - 90d - last_cycle - 1bc - 3bc type: string description: Time range to aggregate events for. Either range or custom_range must be provided bin_size: enum: - day - hour - month type: string default: day description: Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day custom_range: type: object properties: start: type: number end: type: number required: - start - end description: Custom time range to aggregate events for. If provided, range must not be provided filter_by: type: object propertyNames: type: string additionalProperties: type: string description: 'Filter events by property values, e.g. {"model": "gpt-4", "region": "us"}. Maximum 5 filters.' max_groups: type: integer minimum: 1 maximum: 250 description: Maximum number of distinct group values to return per time bin when using group_by. Remaining values are bundled into an 'Other' bucket. Defaults to 9 required: - feature_id title: EventsAggregateParams examples: - customer_id: cus_123 feature_id: api_calls range: 30d bin_size: day - customer_id: cus_123 feature_id: - api_calls - messages range: 7d group_by: properties.model responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: period: type: number description: Unix timestamp (epoch ms) for this time period values: type: object propertyNames: type: string additionalProperties: type: number description: "Aggregated values per feature: { [featureId]: number }" grouped_values: type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: number description: "Values broken down by group (only present when group_by is used): { [featureId]: { [groupValue]: number } }" required: - period - values description: Array of time periods with aggregated values total: type: object propertyNames: type: string additionalProperties: type: object properties: count: type: number description: Number of events for this feature sum: type: number description: Sum of event values for this feature required: - count - sum description: Total aggregations per feature. Keys are feature IDs, values contain count and sum. required: - list - total examples: - list: - period: 1762905600000 values: messages: 10 sessions: 3 - period: 1762992000000 values: messages: 3 sessions: 12 total: messages: count: 2 sum: 13 sessions: count: 2 sum: 15 - list: - period: 1762905600000 values: messages: 10 sessions: 3 grouped_values: messages: api: 5 web: 5 sessions: api: 2 web: 1 - period: 1762992000000 values: messages: 3 sessions: 12 grouped_values: messages: api: 1 web: 2 sessions: api: 10 web: 2 total: messages: count: 2 sum: 13 sessions: count: 2 sum: 15 x-speakeasy-name-override: aggregate parameters: - *a1 /v1/entities.create: post: operationId: createEntity description: >- Creates an entity for a customer and feature, then returns the entity with balances and subscriptions. Use entities when usage and access must be scoped to sub-resources (for example seats, projects, or workspaces) instead of only the customer. @example ```typescript // Create a seat entity const response = await client.entities.create({ customerId: "cus_123", entityId: "seat_42", featureId: "seats", name: "Seat 42", }); ``` @param name - The name of the entity (optional) @param featureId - The ID of the feature this entity is associated with @param billingControls - Billing controls for the entity. (optional) @param customerData - Customer attributes used to resolve the customer when customer_id is not provided. (optional) @param customerId - The ID of the customer to create the entity for. @param entityId - The ID of the entity. @returns The created entity object including its current subscriptions, purchases, and balances. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: name: anyOf: - type: string - type: "null" description: The name of the entity feature_id: type: string description: The ID of the feature this entity is associated with billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. customer_data: $ref: "#/components/schemas/CustomerData" description: Customer attributes used to resolve the customer when customer_id is not provided. customer_id: type: string description: The ID of the customer to create the entity for. entity_id: type: string description: The ID of the entity. required: - feature_id - customer_id - entity_id title: CreateEntityParams examples: - customer_id: cus_123 entity_id: seat_42 feature_id: seats name: Seat 42 responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this entity (only included when expand=invoices) required: - id - name - created_at - env - subscriptions - purchases - balances - flags examples: - 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: [] x-speakeasy-name-override: create parameters: - *a1 /v1/entities.get: post: operationId: getEntity description: >- Fetches an entity by its ID. Use this to read one entity's current state. Pass customerId when you want to scope the lookup to a specific customer. @example ```typescript // Fetch a seat entity const response = await client.entities.get({ entityId: "seat_42" }); ``` @example ```typescript // Fetch a seat entity for a specific customer const response = await client.entities.get({ customerId: "cus_123", entityId: "seat_42" }); ``` @param customerId - The ID of the customer to create the entity for. (optional) @param entityId - The ID of the entity. @returns The entity object including its current subscriptions, purchases, and balances. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to create the entity for. entity_id: type: string description: The ID of the entity. required: - entity_id title: GetEntityParams examples: - entity_id: seat_42 - customer_id: cus_123 entity_id: seat_42 responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this entity (only included when expand=invoices) required: - id - name - created_at - env - subscriptions - purchases - balances - flags examples: - 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: [] x-speakeasy-name-override: get parameters: - *a1 /v1/entities.list: post: operationId: listEntities description: >- Lists entities across the organization with pagination and optional filters. Use this to page through entities globally, including filtering by plans inherited from parent customers or attached directly to entities. @example ```typescript // List entities on a plan const response = await client.entities.list({ plans: [{"id":"pro_plan"}], limit: 10, offset: 0 }); ``` @example ```typescript // Search entities by ID or name const response = await client.entities.list({ search: "workspace" }); ``` @param offset - Number of items to skip (optional) @param limit - Number of items to return. Default 10, max 1000. (optional) @param plans - Filter by plan ID and version. Returns entities with active subscriptions to this plan, including plans inherited from the parent customer. (optional) @param subscriptionStatus - Filter customer products used for entity hydration and plan matching. Defaults to active and scheduled. (optional) @param search - Search entities by id or name. (optional) @param processors - Filter by parent customer processor type (stripe, revenuecat, vercel). (optional) @param customerId - Restrict the response to entities owned by this customer id. Use to bulk-fetch all entities for one customer in a single paginated call instead of iterating entities.get. (optional) @returns A paginated list of entity objects including their current subscriptions, purchases, balances, and flags. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: start_cursor: type: string default: "" description: Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages. limit: type: integer minimum: 1 maximum: 5000 default: 50 description: Number of items to return. Default 50, hard ceiling 5000. plans: type: array items: type: object properties: id: type: string versions: type: array items: type: number required: - id description: Filter by plan ID and version. Returns entities with active subscriptions to this plan, including plans inherited from the parent customer. subscription_status: enum: - active - scheduled type: string description: Filter customer products used for entity hydration and plan matching. Defaults to active and scheduled. search: type: string description: Search entities by id or name. processors: type: array items: enum: - stripe - revenuecat - vercel type: string description: Filter by parent customer processor type (stripe, revenuecat, vercel). customer_id: type: string minLength: 1 description: Restrict the response to entities owned by this customer id. Use to bulk-fetch all entities for one customer in a single paginated call instead of iterating entities.get. title: ListEntitiesParams examples: - start_cursor: "" limit: 10 - plans: - id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this entity (only included when expand=invoices) required: - id - name - created_at - env - subscriptions - purchases - balances - flags description: Items for current page. next_cursor: anyOf: - type: string - type: "null" description: Opaque cursor for the next page. Null when there are no more results. required: - list - next_cursor examples: - list: - 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: [] next_cursor: null x-speakeasy-name-override: list parameters: - *a1 /v1/entities.update: post: operationId: updateEntity description: |- Updates an existing entity and returns the refreshed entity object. Use this to change entity billing controls or other mutable entity fields after the entity has already been created. @example ```typescript // Update a seat entity's billing controls const response = await client.entities.update({ customerId: "cus_123", entityId: "seat_42", billingControls: {"spendLimits":[{"featureId":"messages","enabled":true,"overageLimit":25}]} }); ``` @param customerId - The ID of the customer that owns the entity. (optional) @param entityId - The ID of the entity. @param billingControls - Billing controls to replace on the entity. (optional) @returns The updated entity object including its current subscriptions, purchases, and balances. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer that owns the entity. entity_id: type: string description: The ID of the entity. billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls to replace on the entity. required: - entity_id title: UpdateEntityParams examples: - customer_id: cus_123 entity_id: seat_42 billing_controls: spend_limits: - feature_id: messages enabled: true overage_limit: 25 responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live type: string description: The environment (sandbox/live) subscriptions: type: array items: type: object properties: id: type: string description: 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: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the subscribed plan. auto_enable: type: boolean description: Whether the plan was automatically enabled for the customer. add_on: type: boolean description: Whether this is an add-on plan rather than a base subscription. status: enum: - active - scheduled type: string description: Current status of the subscription. past_due: type: boolean description: Whether the subscription has overdue payments. canceled_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription was canceled, or null if not canceled. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the subscription will expire, or null if no expiry set. trial_ends_at: anyOf: - type: number - type: "null" description: Timestamp when the trial period ends, or null if not on trial. started_at: type: number description: Timestamp when the subscription started. current_period_start: anyOf: - type: number - type: "null" description: Start timestamp of the current billing period. current_period_end: anyOf: - type: number - type: "null" description: End timestamp of the current billing period. quantity: type: number description: Number of units of this subscription (for per-seat plans). scope: enum: - customer - entity type: string description: Whether this subscription is attached at the customer level or entity level. required: - id - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" description: The full plan object if expanded. plan_id: type: string description: The unique identifier of the purchased plan. expires_at: anyOf: - type: number - type: "null" description: Timestamp when the purchase expires, or null for lifetime access. started_at: type: number description: Timestamp when the purchase was made. quantity: type: number description: Number of units purchased. scope: enum: - customer - entity type: string description: Whether this purchase is attached at the customer level or entity level. required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/Balance" flags: type: object propertyNames: type: string additionalProperties: 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 type: string description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived description: The full feature object if expanded. required: - id - plan_id - expires_at - feature_id examples: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan expires_at: null feature_id: dashboard billing_controls: type: object properties: 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 this spend limit is enabled. overage_limit: type: number minimum: 0 description: Maximum allowed overage spend for the target feature. description: List of overage spend limits per feature. usage_alerts: type: array items: type: object properties: feature_id: type: string description: The feature ID this alert applies to. enabled: type: boolean default: true description: Whether this usage alert is enabled. threshold: type: number minimum: 0 description: The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). threshold_type: enum: - usage - usage_percentage - remaining - remaining_percentage type: string description: Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. name: type: string description: Optional user-defined label to distinguish multiple alerts on the same feature. required: - threshold - threshold_type description: List of usage alert configurations per feature. overage_allowed: type: array items: type: object properties: feature_id: type: string description: The feature ID this overage allowed control applies to. enabled: type: boolean default: false description: Whether overage is allowed for this feature. required: - feature_id description: List of overage allowed controls per feature. When enabled, usage can exceed balance. description: Billing controls for the entity. invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID processor_type: enum: - stripe - revenuecat type: string default: stripe description: The billing processor that owns this invoice. status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at description: Invoices for this entity (only included when expand=invoices) required: - id - name - created_at - env - subscriptions - purchases - balances - flags examples: - 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: [] x-speakeasy-name-override: update parameters: - *a1 /v1/entities.delete: post: operationId: deleteEntity description: >- Deletes an entity by entity ID. Use this when the underlying resource is removed and you no longer want entity-scoped balances or subscriptions tracked for it. @example ```typescript // Delete a seat entity const response = await client.entities.delete({ entityId: "seat_42" }); ``` @param customerId - The ID of the customer. (optional) @param entityId - The ID of the entity. @returns A success flag indicating the entity was deleted. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity. required: - entity_id title: DeleteEntityParams examples: - customer_id: cus_123 entity_id: seat_42 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - success: true x-speakeasy-name-override: delete parameters: - *a1 /v1/referrals.create_code: post: operationId: createReferralCode description: Create or fetch a referral code for a customer in a referral program. tags: - referrals requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The unique identifier of the customer program_id: type: string description: ID of your referral program required: - customer_id - program_id title: CreateReferralCodeParams examples: - customer_id: cus_123 program_id: prog_123 responses: "200": description: OK content: application/json: schema: type: object properties: code: type: string description: The referral code that can be shared with customers customer_id: type: string description: Your unique identifier for the customer created_at: type: number description: The timestamp of when the referral code was created required: - code - customer_id - created_at examples: - code: customer_id: created_at: 123 x-speakeasy-name-override: createCode parameters: - *a1 /v1/referrals.redeem_code: post: operationId: redeemReferralCode description: Redeem a referral code for a customer. tags: - referrals requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: The referral code to redeem customer_id: type: string description: The unique identifier of the customer redeeming the code required: - code - customer_id title: RedeemReferralCodeParams examples: - code: REF123 customer_id: cus_456 responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: The ID of the redemption event customer_id: type: string description: Your unique identifier for the customer reward_id: type: string description: The ID of the reward that will be granted required: - id - customer_id - reward_id examples: - id: customer_id: reward_id: x-speakeasy-name-override: redeemCode parameters: - *a1 /v1/rewards.redeem: post: operationId: redeemRewardCode description: Redeem a reward promo code for a customer. tags: - rewards requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: The reward promo code to redeem customer_id: type: string description: The unique identifier of the customer redeeming the code required: - code - customer_id title: RedeemRewardCodeParams examples: - code: REWARD10 customer_id: cus_456 responses: "200": description: OK content: application/json: schema: type: object properties: reward_id: type: string description: The ID of the redeemed reward entitlements_granted: type: array items: type: object properties: feature_id: type: string description: The ID of the feature granted by the reward balance: type: number description: The balance granted for the feature required: - feature_id - balance description: The feature balances granted to the customer required: - reward_id - entitlements_granted examples: - reward_id: reward_789 entitlements_granted: - feature_id: messages balance: 100 x-speakeasy-name-override: redeemCode parameters: - *a1 /v1/platform.link_revenuecat: post: operationId: linkRevenueCat description: Generate a RevenueCat OAuth URL for linking a project to an organization. tags: - platform requestBody: required: true content: application/json: schema: type: object properties: organization_slug: type: string minLength: 1 env: enum: - test - live type: string project_name: type: string minLength: 1 maxLength: 255 redirect_url: type: string format: uri required: - organization_slug - env - project_name - redirect_url title: LinkRevenueCatParams examples: - organization_slug: acme env: test project_name: acme-mobile redirect_url: https://dashboard.useautumn.com/dev?tab=revenuecat responses: "200": description: OK content: application/json: schema: type: object properties: oauth_url: type: string required: - oauth_url title: LinkRevenueCatResponse examples: - oauth_url: https://api.revenuecat.com/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=project.read+project.write x-speakeasy-name-override: linkRevenueCat parameters: - *a1 /v1/platform.sync_revenuecat: post: operationId: syncRevenueCat description: Push an organization's plans into RevenueCat as products (creating or renaming them across the project's apps) and set test-store prices from each plan's price. Requires the org to have linked RevenueCat via OAuth. tags: - platform requestBody: required: true content: application/json: schema: type: object properties: organization_slug: type: string minLength: 1 env: enum: - test - sandbox - live type: string description: '"test" and "sandbox" both target the sandbox environment' product_ids: type: array items: type: string description: Plans to push. Omit to sync every plan in the org/env. required: - organization_slug - env title: SyncRevenueCatParams examples: - organization_slug: acme env: test product_ids: - pro - premium responses: "200": description: OK content: application/json: schema: type: object properties: results: type: array items: type: object properties: plan_id: type: string status: enum: - synced - skipped - error type: string store_identifier: type: string apps: type: array items: type: object properties: app_id: type: string app_type: type: string product: enum: - created - updated - exists type: string store_push: enum: - pushed - failed - skipped type: string price: enum: - set - skipped - failed type: string message: type: string required: - app_id - app_type - product message: type: string required: - plan_id - status required: - results title: SyncRevenueCatResponse examples: - results: - plan_id: pro status: synced store_identifier: autumn.sandbox.org_123.pro apps: - app_id: app_test app_type: test_store product: created store_push: skipped price: set x-speakeasy-name-override: syncRevenueCat parameters: - *a1 /v1/platform.get_revenuecat_keys: post: operationId: getRevenueCatKeys description: Retrieve a managed organization's RevenueCat public (SDK) API keys, grouped by app — for the test store, App Store, and Google Play Store. Use these to configure the RevenueCat SDK in the org's mobile app. tags: - platform requestBody: required: true content: application/json: schema: type: object properties: organization_slug: type: string minLength: 1 env: enum: - test - sandbox - live type: string description: '"test" and "sandbox" both target the sandbox environment' required: - organization_slug - env title: GetRevenueCatKeysParams examples: - organization_slug: acme env: test responses: "200": description: OK content: application/json: schema: type: object properties: apps: type: array items: type: object properties: app_id: type: string app_type: type: string description: RevenueCat store type, e.g. test_store / app_store / play_store name: type: string api_keys: type: array items: type: object properties: id: type: string key: type: string description: The public SDK API key value environment: anyOf: - type: string - type: "null" description: e.g. "production" / "sandbox" app_id: anyOf: - type: string - type: "null" created_at: type: number required: - id - key additionalProperties: {} required: - app_id - app_type - name - api_keys oauth_access_token: anyOf: - type: string - type: "null" description: Freshly-refreshed RevenueCat OAuth access token for the org (null for api-key orgs). The refresh token is never exposed — call this endpoint again for a new access token. required: - apps - oauth_access_token title: GetRevenueCatKeysResponse examples: - apps: - app_id: app1a2b3c4d app_type: test_store name: Acme (Test Store) api_keys: - id: apikey12345 key: test_aBcDeFgHiJkLmNoPqRsTuVwXyZ environment: production app_id: app1a2b3c4 oauth_access_token: atk_aBcDeFgHiJkLmNoPqRsTuVwXyZ x-speakeasy-name-override: getRevenueCatKeys parameters: - *a1 security: - secretKey: [] x-speakeasy-globals: parameters: - name: x-api-version in: header required: true schema: type: string default: 2.3.0 x-speakeasy-globals-hidden: true - name: fail-open in: header required: false schema: type: boolean default: true x-speakeasy-globals-hidden: true webhooks: balances.usage_alert_triggered: post: operationId: balancesUsageAlertTriggered summary: Usage Alert Triggered description: Fired when a customer crosses a configured usage alert threshold. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: balances.usage_alert_triggered description: The webhook event type. data: examples: - customer_id: org_123 feature_id: api_calls entity_id: workspace_abc usage_alert: name: 80% usage warning threshold: 80 threshold_type: usage_percentage_threshold type: object properties: customer_id: description: The ID of the customer whose usage alert was triggered. type: string feature_id: description: The feature ID the alert applies to. type: string entity_id: description: The entity ID the alert applies to, if the usage was entity-scoped. type: string usage_alert: description: Details of the usage alert that was triggered. type: object properties: name: description: User-defined label for the alert, if provided. type: string threshold: description: The threshold value that was crossed. type: number threshold_type: description: Whether the threshold is an absolute usage count or a percentage. type: string enum: - usage - usage_percentage - remaining - remaining_percentage required: - threshold - threshold_type additionalProperties: false required: - customer_id - feature_id - usage_alert additionalProperties: false example: type: balances.usage_alert_triggered data: customer_id: org_123 feature_id: api_calls entity_id: workspace_abc usage_alert: name: 80% usage warning threshold: 80 threshold_type: usage_percentage_threshold responses: "200": description: Webhook received successfully. balances.limit_reached: post: operationId: balancesLimitReached summary: Limit Reached description: Fired when a customer reaches the limit for a feature (included allowance, max purchase, or spend limit). requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: balances.limit_reached description: The webhook event type. data: examples: - customer_id: org_123 entity_id: workspace_abc feature_id: api_calls limit_type: included type: object properties: customer_id: description: The ID of the customer who hit the limit. type: string entity_id: description: The entity ID, if the limit was reached on a specific entity. type: string feature_id: description: The feature ID whose limit was reached. type: string limit_type: description: "Which limit was hit: included allowance, max purchase cap, or spend limit." type: string enum: - included - max_purchase - spend_limit required: - customer_id - feature_id - limit_type additionalProperties: false example: type: balances.limit_reached data: customer_id: org_123 entity_id: workspace_abc feature_id: api_calls limit_type: included responses: "200": description: Webhook received successfully. billing.auto_topup_succeeded: post: operationId: billingAutoTopupSucceeded summary: Auto Top-Up Succeeded description: Fired when an automatic top-up grants additional prepaid balance. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: billing.auto_topup_succeeded description: The webhook event type. data: examples: - customer_id: cus_123 feature_id: messages quantity_granted: 100 threshold: 20 balance_after: 115 invoice_mode: false invoice: stripe_id: in_1A2B3C4D5E6F7G8H status: paid total: 1000 currency: usd hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 type: object properties: customer_id: description: The ID of the customer whose balance was topped up. type: string feature_id: description: The feature ID that was automatically topped up. type: string quantity_granted: description: The normalized amount of balance granted by the top-up. type: number threshold: description: The configured balance threshold that triggered the top-up. type: number balance_after: description: The customer's remaining balance for the feature after the top-up. type: number invoice_mode: description: Whether the auto top-up created a send_invoice invoice instead of auto-charging. type: boolean invoice: description: The invoice created for the auto top-up. type: object properties: stripe_id: description: The Stripe invoice ID. Use this as a stable dedupe key. type: string status: description: The status of the invoice. "paid" for auto-charged top-ups; "open" for invoice-mode top-ups where credits were granted but the invoice has not yet been paid. anyOf: - type: string - type: "null" total: description: The total amount of the invoice in the smallest currency unit (e.g. cents for USD), matching Stripe's invoice.total. type: number currency: description: The ISO currency code for the invoice. type: string hosted_invoice_url: description: URL to the hosted invoice page, if available. anyOf: - type: string - type: "null" required: - stripe_id - total - currency additionalProperties: false required: - customer_id - feature_id - quantity_granted - threshold - balance_after - invoice_mode - invoice additionalProperties: false example: type: billing.auto_topup_succeeded data: customer_id: cus_123 feature_id: messages quantity_granted: 100 threshold: 20 balance_after: 115 invoice_mode: false invoice: stripe_id: in_1A2B3C4D5E6F7G8H status: paid total: 1000 currency: usd hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 responses: "200": description: Webhook received successfully. billing.updated: post: operationId: billingUpdated summary: Plans Updated description: Fired when a customer's plans change — activated, scheduled, updated, or expired. Each event carries a `plan_changes` array describing what happened and a `tags` array (e.g. `trial_ended`, `phase_changed`) describing why. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: billing.updated description: The webhook event type. data: examples: - object: billing.updated customer_id: cus_123 plan_changes: - action: activated subscription: plan_id: pro status: active past_due: false started_at: 1779000000000 canceled_at: null expires_at: null trial_ends_at: null current_period_start: 1779000000000 current_period_end: 1781592000000 previous_attributes: null item_changes: [] - action: expired subscription: plan_id: free status: expired past_due: false started_at: 1776000000000 canceled_at: 1779000000000 expires_at: 1779000000000 trial_ends_at: null current_period_start: null current_period_end: null previous_attributes: status: active item_changes: [] tags: [] type: object properties: object: type: string const: billing.updated customer_id: description: The ID of the customer whose plans changed. type: string entity_id: description: The ID of the entity, if the changes are scoped to a specific entity. anyOf: - type: string - type: "null" plan_changes: description: The plans that were activated, scheduled, updated, or expired. type: array items: type: object properties: action: description: "The lifecycle action applied to this plan: activated (newly active on the customer), scheduled (queued for a future start), updated (mutated in place), or expired (ended)." type: string enum: - activated - scheduled - updated - expired subscription: description: The subscription as it stands after this change. Present when the plan is billed as a recurring subscription. type: object properties: plan_id: description: The ID of the customer plan. type: string status: description: The current status of the subscription on the customer. type: string enum: - active - scheduled - expired past_due: description: Whether the subscription has overdue payments. type: boolean started_at: description: When the subscription started, in milliseconds since the Unix epoch. anyOf: - type: number - type: "null" canceled_at: description: When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled. anyOf: - type: number - type: "null" expires_at: description: When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set. anyOf: - type: number - type: "null" trial_ends_at: description: When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing. anyOf: - type: number - type: "null" current_period_start: description: Start of the current billing period, or null if not applicable. anyOf: - type: number - type: "null" current_period_end: description: End of the current billing period, or null if not applicable. anyOf: - type: number - type: "null" required: - plan_id - status - past_due - started_at - canceled_at - expires_at - trial_ends_at - current_period_start - current_period_end additionalProperties: false purchase: description: The purchase as it stands after this change. Present when the plan is a one-off purchase. type: object properties: plan_id: description: The ID of the customer plan. type: string status: description: The current status of the purchase on the customer. type: string enum: - active - scheduled - expired expires_at: description: When the purchase ends, in milliseconds since the Unix epoch, or null if no expiry is set. anyOf: - type: number - type: "null" required: - plan_id - status - expires_at additionalProperties: false previous_attributes: description: Sparse map of scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled. anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" item_changes: description: Features that were added to or removed from this plan. Only populated for updated plans. default: [] type: array items: type: object properties: action: description: Whether the feature was added to or removed from the plan. type: string enum: - created - deleted feature_id: description: The ID of the feature that was added or removed. type: string required: - action - feature_id additionalProperties: false required: - action - previous_attributes - item_changes additionalProperties: false tags: description: Reason tags describing why this event fired (e.g. 'trial_ended', 'phase_changed'). Always present; empty when no specific reason applies. default: [] type: array items: type: string required: - object - customer_id - plan_changes - tags additionalProperties: false example: type: billing.updated data: object: billing.updated customer_id: cus_123 plan_changes: - action: activated subscription: plan_id: pro status: active past_due: false started_at: 1779000000000 canceled_at: null expires_at: null trial_ends_at: null current_period_start: 1779000000000 current_period_end: 1781592000000 previous_attributes: null item_changes: [] - action: expired subscription: plan_id: free status: expired past_due: false started_at: 1776000000000 canceled_at: 1779000000000 expires_at: 1779000000000 trial_ends_at: null current_period_start: null current_period_end: null previous_attributes: status: active item_changes: [] tags: [] responses: "200": description: Webhook received successfully. vercel.resources.deleted: post: operationId: vercelResourcesDeleted summary: Resource Deleted description: When a Vercel resource is deleted, you'll need to handle de-provisioning any API keys or other non-Autumn controlled data for this user. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: vercel.resources.deleted description: The webhook event type. data: type: object properties: resource: description: The resource that was deleted. type: object properties: id: description: The unique identifier of the deleted resource. type: string required: - id additionalProperties: false installation_id: description: The Vercel integration configuration ID. type: string required: - resource - installation_id additionalProperties: false responses: "200": description: Webhook received successfully. vercel.resources.provisioned: post: operationId: vercelResourcesProvisioned summary: Resource Provisioned description: When a Vercel resource is created, you'll need to provision a secret key for your service. Then you can use the provided access token to patch the resource's secrets. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: vercel.resources.provisioned description: The webhook event type. data: type: object properties: resource: description: The resource that was provisioned. type: object properties: id: description: The unique identifier of the provisioned resource. type: string name: description: The display name of the provisioned resource. type: string required: - id - name additionalProperties: false installation_id: description: The Vercel integration configuration ID. type: string access_token: description: An access token that can be used to patch the resource's secrets. type: string required: - resource - installation_id - access_token additionalProperties: false responses: "200": description: Webhook received successfully. vercel.resources.rotate_secrets: post: operationId: vercelResourcesRotateSecrets summary: Rotate Secrets description: This event is sent when Vercel requires a resource's secrets to be rotated. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: vercel.resources.rotate_secrets description: The webhook event type. data: type: object properties: resource: description: The resource whose secrets should be rotated. type: object properties: id: description: The unique identifier of the resource. type: string required: - id additionalProperties: false installation_id: description: The Vercel integration configuration ID. type: string vercel_request_body: description: The raw request body from Vercel's rotation request. required: - resource - installation_id - vercel_request_body additionalProperties: false responses: "200": description: Webhook received successfully. vercel.webhooks.event: post: operationId: vercelWebhooksEvent summary: Webhook Event description: Passthrough webhook for Vercel events. requestBody: required: true content: application/json: schema: type: object required: - type - data properties: type: type: string const: vercel.webhooks.event description: The webhook event type. data: type: object properties: installation_id: description: The Vercel integration configuration ID. type: string event: description: The raw Vercel webhook event payload. required: - installation_id - event additionalProperties: false responses: "200": description: Webhook received successfully.