info: title: Autumn API version: 2.2.0 servers: - url: https://api.useautumn.com description: Production server openapi: 3.1.1 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). 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. 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: - &a2 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. 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. 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: - &a1 customer_id: cus_123 name: John Doe email: john@example.com example: *a1 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" example: *a2 x-speakeasy-name-override: getOrCreate parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.getOrCreate({ customerId: "cus_123", name: "John Doe", email: "john@example.com", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.get_or_create( customer_id="cus_123", name="John Doe", email="john@example.com", ) /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. 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: - &a3 customer_id: cus_123 - customer_id: cus_123 expand: - invoices - entities example: *a3 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). 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. 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: - &a4 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 example: *a4 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.get({ customerId: "cus_123", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.get(customer_id="cus_123") /v1/customers.list: post: operationId: listCustomers description: Lists customers with pagination and optional filters. tags: - customers requestBody: required: false content: application/json: schema: type: object properties: offset: type: integer minimum: 0 maximum: 9007199254740991 default: 0 description: Number of items to skip limit: type: integer minimum: 1 maximum: 1000 default: 10 description: Number of items to return. Default 10, max 1000. 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: - &a5 limit: 10 offset: 0 example: *a5 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). 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. 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: Array of items for current page has_more: type: boolean description: Whether more results exist after this page offset: type: number description: Current offset position limit: type: number description: Limit passed in the request total: type: number description: Total number of items returned in the current page total_count: type: number description: Total number of customers available in the current organization and environment total_filtered_count: type: number description: Total number of customers matching the current filter before pagination is applied required: - list - has_more - offset - limit - total - total_count - total_filtered_count examples: - &a6 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 has_more: false offset: 0 total: 1 limit: 10 total_count: 100 total_filtered_count: 42 example: *a6 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.list({}); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.list( request={}, ) /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: - &a7 customer_id: cus_123 name: Jane Doe email: jane@example.com example: *a7 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). 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. 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: - &a8 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 example: *a8 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.update({ customerId: "cus_123", name: "Jane Doe", email: "jane@example.com", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.update( customer_id="cus_123", name="Jane Doe", email="jane@example.com", ) /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: - &a9 customer_id: cus_123 delete_in_stripe: false example: *a9 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.delete({ customerId: "cus_123", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.delete( customer_id="cus_123", delete_in_stripe=False, ) /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. 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. 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: - &a10 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 example: *a10 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. 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: - &a11 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 example: *a11 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.create({ planId: "free_plan", name: "Free", autoEnable: true, items: [ { featureId: "messages", included: 100, reset: { interval: "month", }, }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.create( plan_id="free_plan", name="Free", group="", add_on=False, auto_enable=True, items=[ { "feature_id": "messages", "included": 100, "reset": { "interval": "month", }, }, ], create_in_stripe=True, ) /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. 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: - &a12 plan_id: pro_plan - plan_id: pro_plan version: 2 example: *a12 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. 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: - &a13 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 example: *a13 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.get({ planId: "pro_plan", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.get(plan_id="pro_plan") /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. 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: - &a14 {} - customer_id: cus_123 - include_archived: true example: *a14 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. 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: - &a15 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 example: *a15 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.list({}); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.list( request={}, ) /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. 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. 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: - &a16 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 example: *a16 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. 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: - &a17 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 example: *a17 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.update({ planId: "pro_plan", name: "Pro Plan (Updated)", price: { amount: 15, interval: "month", }, }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.update( plan_id="pro_plan", group="", name="Pro Plan (Updated)", price={ "amount": 15, "interval": "month", }, create_in_stripe=True, archived=False, ) /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. 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: - &a18 plan_id: unused_plan - plan_id: legacy_plan all_versions: true example: *a18 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.delete({ planId: "unused_plan", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.delete( plan_id="unused_plan", all_versions=False, ) /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. 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: - &a19 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 example: *a19 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: - &a20 id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls example: *a20 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.features.create({ name: "API Calls", type: "metered", consumable: true, featureId: "api-calls", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.features.create( name="API Calls", type_="metered", feature_id="api-calls", consumable=True, ) /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. 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: - &a21 feature_id: api-calls example: *a21 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: - &a22 id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls example: *a22 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.features.get({ featureId: "api-calls", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.features.get(feature_id="api-calls") /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. 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: - &a23 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 example: *a23 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.features.list(); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.features.list() /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. 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: - &a24 feature_id: api-calls name: API Requests display: singular: API request plural: API requests - feature_id: old-feature archived: true example: *a24 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: - &a25 id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls example: *a25 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.features.update({ name: "API Requests", display: { singular: "API request", plural: "API requests", }, featureId: "api-calls", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.features.update( feature_id="api-calls", name="API Requests", display={ "singular": "API request", "plural": "API requests", }, ) /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. 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: - &a26 feature_id: old-feature example: *a26 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - &a27 success: true example: *a27 x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.features.delete({ featureId: "old-feature", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.features.delete(feature_id="old-feature") /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. 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. 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. 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. 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. required: - customer_id - plan_id title: AttachParams examples: - &a28 customer_id: cus_123 plan_id: pro_plan example: *a28 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: - &a29 customer_id: cus_123 payment_url: https://checkout.stripe.com/... example: *a29 x-speakeasy-name-override: attach parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.attach({ customerId: "cus_123", planId: "pro_plan", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.attach( customer_id="cus_123", plan_id="pro_plan", redirect_mode="if_required", ) /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. 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. required: - enabled description: Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. 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: - &a30 customer_id: cus_123 phases: - starts_at: 1735689600000 plans: - plan_id: trial_plan - starts_at: 1736899200000 plans: - plan_id: pro_plan example: *a30 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: - &a31 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 example: *a31 x-speakeasy-name-override: createSchedule parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.createSchedule({ customerId: "cus_123", phases: [ { startsAt: 1735689600000, plans: [ { planId: "trial_plan", }, ], }, { startsAt: 1736899200000, plans: [ { planId: "pro_plan", }, ], }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.create_schedule( customer_id="cus_123", phases=[ { "starts_at": 1735689600000, "plans": [ { "plan_id": "trial_plan", }, ], }, { "starts_at": 1736899200000, "plans": [ { "plan_id": "pro_plan", }, ], }, ], redirect_mode="if_required", ) /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. 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. 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. 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: - &a32 customer_id: cus_123 plans: - plan_id: pro_plan - plan_id: addon_seats feature_quantities: - feature_id: seats quantity: 5 example: *a32 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: - &a33 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 example: *a33 x-speakeasy-name-override: multiAttach parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.multiAttach({ customerId: "cus_123", plans: [ { planId: "pro_plan", }, { planId: "addon_seats", featureQuantities: [ { featureId: "seats", quantity: 5, }, ], }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.multi_attach( customer_id="cus_123", plans=[ { "plan_id": "pro_plan", }, { "plan_id": "addon_seats", "feature_quantities": [ { "feature_id": "seats", "quantity": 5, }, ], }, ], redirect_mode="if_required", ) /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. 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. 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. 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. 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. required: - customer_id - plan_id title: PreviewAttachParams examples: - &a34 customer_id: cus_123 plan_id: pro_plan example: *a34 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: - &a35 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 example: *a35 x-speakeasy-name-override: previewAttach parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.previewAttach({ customerId: "cus_123", planId: "pro_plan", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.preview_attach( customer_id="cus_123", plan_id="pro_plan", redirect_mode="if_required", ) /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. 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. 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. 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: - &a36 customer_id: cus_123 plans: - plan_id: pro_plan - plan_id: addon_seats feature_quantities: - feature_id: seats quantity: 5 example: *a36 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: - &a37 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 example: *a37 x-speakeasy-name-override: previewMultiAttach parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.previewMultiAttach({ customerId: "cus_123", plans: [ { planId: "pro_plan", }, { planId: "addon_seats", featureQuantities: [ { featureId: "seats", quantity: 5, }, ], }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.preview_multi_attach( customer_id="cus_123", plans=[ { "plan_id": "pro_plan", }, { "plan_id": "addon_seats", "feature_quantities": [ { "feature_id": "seats", "quantity": 5, }, ], }, ], redirect_mode="if_required", ) /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. 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. 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. 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. 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: - &a38 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 10 example: *a38 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: - &a39 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 example: *a39 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.update({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [ { featureId: "seats", quantity: 10, }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.update( customer_id="cus_123", plan_id="pro_plan", feature_quantities=[ { "feature_id": "seats", "quantity": 10, }, ], redirect_mode="if_required", ) /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. 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. 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. 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. 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: - &a40 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 15 example: *a40 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: - &a41 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 example: *a41 x-speakeasy-name-override: previewUpdate parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.previewUpdate({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [ { featureId: "seats", quantity: 15, }, ], }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.preview_update( customer_id="cus_123", plan_id="pro_plan", feature_quantities=[ { "feature_id": "seats", "quantity": 15, }, ], redirect_mode="if_required", ) /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: - &a42 customer_id: cus_123 return_url: https://useautumn.com example: *a42 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: - &a43 customer_id: cus_123 url: https://billing.stripe.com/session/... example: *a43 x-speakeasy-name-override: openCustomerPortal parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.openCustomerPortal({ customerId: "cus_123", returnUrl: "https://useautumn.com", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.open_customer_portal( customer_id="cus_123", return_url="https://useautumn.com", ) /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. 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. 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. required: - customer_id title: SetupPaymentParams examples: - &a44 customer_id: cus_123 success_url: https://example.com/account/billing example: *a44 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: - &a45 customer_id: cus_123 url: https://checkout.stripe.com/... example: *a45 x-speakeasy-name-override: setupPayment parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.setupPayment({ customerId: "cus_123", successUrl: "https://example.com/account/billing", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.setup_payment( customer_id="cus_123", success_url="https://example.com/account/billing", ) /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: - &a46 customer_id: cus_123 feature_id: api_calls included: 1000 reset: interval: month example: *a46 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.create({ customerId: "cus_123", featureId: "api_calls", reset: { interval: "month", }, }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.create( customer_id="cus_123", feature_id="api_calls", reset={ "interval": "month", }, ) /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: - &a47 customer_id: cus_123 feature_id: api_calls remaining: 5 example: *a47 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.update({ customerId: "cus_123", featureId: "api_calls", remaining: 5, }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.update( customer_id="cus_123", feature_id="api_calls", remaining=5, ) /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: - &a48 customer_id: cus_123 feature_id: api_calls example: *a48 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.delete({ customerId: "cus_123", featureId: "api_calls", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.delete( customer_id="cus_123", feature_id="api_calls", ) /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: - &a49 lock_id: lock_abc123 action: confirm - lock_id: lock_abc123 action: confirm override_value: 3 - lock_id: lock_abc123 action: release example: *a49 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: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.finalize({ lockId: "lock_abc123", action: "confirm", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.finalize( lock_id="lock_abc123", action="confirm", ) /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. 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: - &a50 customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages required_balance: 3 send_event: true example: *a50 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. 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: - &a51 allowed: true customer_id: cus_123 entity_id: null required_balance: 1 balance: feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null example: *a51 "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. 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: - &a52 allowed: true customer_id: cus_123 entity_id: null required_balance: 1 balance: feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null example: *a52 x-speakeasy-name-override: check parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.check({ customerId: "cus_123", featureId: "messages", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.check( customer_id="cus_123", feature_id="messages", ) /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. 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. 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: - &a53 customer_id: cus_123 feature_id: messages value: 1 example: *a53 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: - &a54 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 example: *a54 "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: - &a55 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 example: *a55 x-speakeasy-name-override: track parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.track({ customerId: "cus_123", featureId: "messages", value: 1, }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.track( customer_id="cus_123", feature_id="messages", value=1, ) /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: offset: type: integer minimum: 0 maximum: 9007199254740991 default: 0 description: Number of items to skip limit: type: integer minimum: 1 maximum: 1000 default: 100 description: Number of items to return. Default 100, max 1000. 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: - &a56 customer_id: cus_123 limit: 50 - feature_id: api_calls custom_range: start: 1704067200000 end: 1706745600000 example: *a56 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: Array of items for current page has_more: type: boolean description: Whether more results exist after this page offset: type: number description: Current offset position limit: type: number description: Limit passed in the request total: type: number description: Total number of items returned in the current page required: - list - has_more - offset - limit - total examples: - &a57 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 total: 2 has_more: false offset: 0 limit: 100 example: *a57 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.events.list({ limit: 50, customerId: "cus_123", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.events.list( offset=0, limit=50, customer_id="cus_123", ) /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" 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: - &a58 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 example: *a58 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: - &a59 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 example: *a59 x-speakeasy-name-override: aggregate parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.events.aggregate({ customerId: "cus_123", featureId: "api_calls", range: "30d", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.events.aggregate( feature_id="api_calls", customer_id="cus_123", range="30d", bin_size="day", ) /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. 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: - &a60 customer_id: cus_123 entity_id: seat_42 feature_id: seats name: Seat 42 example: *a60 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). 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. 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: - &a61 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: [] example: *a61 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.entities.create({ name: "Seat 42", featureId: "seats", customerId: "cus_123", entityId: "seat_42", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.entities.create( feature_id="seats", customer_id="cus_123", entity_id="seat_42", name="Seat 42", ) /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. 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: - &a62 entity_id: seat_42 - customer_id: cus_123 entity_id: seat_42 example: *a62 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). 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. 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: - &a63 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: [] example: *a63 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.entities.get({ entityId: "seat_42", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.entities.get(entity_id="seat_42") /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. tags: - entities requestBody: required: false content: application/json: schema: type: object properties: offset: type: integer minimum: 0 maximum: 9007199254740991 default: 0 description: Number of items to skip limit: type: integer minimum: 1 maximum: 1000 default: 10 description: Number of items to return. Default 10, max 1000. 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). title: ListEntitiesParams examples: - &a64 limit: 10 offset: 0 - plans: - id: pro_plan example: *a64 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). 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. 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: Array of items for current page has_more: type: boolean description: Whether more results exist after this page offset: type: number description: Current offset position limit: type: number description: Limit passed in the request total: type: number description: Total number of items returned in the current page total_count: type: number description: Total number of entities available in the current organization and environment total_filtered_count: type: number description: Total number of entities matching the current filter before pagination is applied required: - list - has_more - offset - limit - total - total_count - total_filtered_count examples: - &a65 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: [] has_more: false offset: 0 total: 1 limit: 10 total_count: 100 total_filtered_count: 42 example: *a65 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.entities.list({}); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.entities.list( request={}, ) /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. 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: - &a66 customer_id: cus_123 entity_id: seat_42 billing_controls: spend_limits: - feature_id: messages enabled: true overage_limit: 25 example: *a66 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). 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. 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: - &a67 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: [] example: *a67 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.entities.update({ customerId: "cus_123", entityId: "seat_42", billingControls: { spendLimits: [ { featureId: "messages", enabled: true, overageLimit: 25, }, ], }, }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.entities.update( entity_id="seat_42", customer_id="cus_123", billing_controls={ "spend_limits": [ { "feature_id": "messages", "enabled": True, "overage_limit": 25, }, ], }, ) /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. 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: - &a68 customer_id: cus_123 entity_id: seat_42 example: *a68 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - &a69 success: true example: *a69 x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.entities.delete({ customerId: "cus_123", entityId: "seat_42", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.entities.delete( entity_id="seat_42", customer_id="cus_123", ) /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: - &a70 customer_id: cus_123 program_id: prog_123 example: *a70 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: - &a71 code: customer_id: created_at: 123 example: *a71 x-speakeasy-name-override: createCode parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.referrals.createCode({ customerId: "cus_123", programId: "prog_123", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.referrals.create_code( customer_id="cus_123", program_id="prog_123", ) /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: - &a72 code: REF123 customer_id: cus_456 example: *a72 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: - &a73 id: customer_id: reward_id: example: *a73 x-speakeasy-name-override: redeemCode parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.0 x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.referrals.redeemCode({ code: "REF123", customerId: "cus_456", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.referrals.redeem_code( code="REF123", customer_id="cus_456", ) security: - secretKey: [] x-speakeasy-globals: parameters: - name: x-api-version in: header required: true schema: type: string default: 2.2.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. 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.