info: title: Autumn API version: 2.1.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 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 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 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. subscriptions: 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 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 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: - 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. 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 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 entities: type: array items: type: object properties: autumn_id: type: string 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 description: The environment (sandbox/live) required: - id - name - created_at - env 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 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 description: The type of reward discount_value: type: number description: The discount value (percentage or fixed amount) duration_type: enum: - one_off - months - forever 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" 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 payment_method: anyOf: - {} - type: "null" required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances examples: - &a2 id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false 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 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 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 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 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: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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. expiry_duration_type: enum: - month - forever 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 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 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. customer_eligibility: type: object properties: trial_available: type: boolean description: Whether a free trial is available for this customer. scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade). required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id 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 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 - const: multiple description: The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals. interval_count: type: number description: Number of intervals between resets (eg. 2 for bi-monthly). resets_at: anyOf: - type: number - type: "null" description: Timestamp when the balance will next reset. required: - interval - resets_at - type: "null" description: Reset configuration for this balance, or null if no reset. price: anyOf: - type: object properties: amount: type: number description: The per-unit price amount. tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration if applicable. tier_behavior: enum: - graduated - volume 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 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 expand: type: array items: $ref: "#/components/schemas/CustomerExpand" description: Customer expand options 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.1" 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.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 description: Filter by customer product status. Defaults to active and scheduled search: type: string description: Search customers by id, name, or email title: ListCustomersParams examples: - &a3 limit: 10 offset: 0 example: *a3 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 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. subscriptions: 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 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 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: - 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. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances examples: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false 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 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: - &a4 list: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false 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 has_more: false offset: 0 total: 1 limit: 10 example: *a4 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 new_customer_id: $ref: "#/components/schemas/CustomerId" description: New ID for the customer required: - customer_id title: UpdateCustomerParams examples: - &a5 customer_id: cus_123 name: Jane Doe email: jane@example.com example: *a5 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 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. subscriptions: 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 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 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: - 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. required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances examples: - &a6 id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com createdAt: 1771409161016 fingerprint: null stripeId: cus_U0BKxpq1mFhuJO env: sandbox metadata: {} sendEmailReceipts: false 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 example: *a6 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a7 customer_id: cus_123 delete_in_stripe: false example: *a7 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.1" 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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 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. required: - plan_id - name title: CreatePlanParams examples: - &a8 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: *a8 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 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 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 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: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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. expiry_duration_type: enum: - month - forever 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 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 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. customer_eligibility: type: object properties: trial_available: type: boolean description: Whether a free trial is available for this customer. scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade). required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - &a9 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 example: *a9 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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", }, }, ], ) /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: - &a10 plan_id: pro_plan - plan_id: pro_plan version: 2 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 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 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 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: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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. expiry_duration_type: enum: - month - forever 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 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 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. customer_eligibility: type: object properties: trial_available: type: boolean description: Whether a free trial is available for this customer. scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade). required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id 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 example: *a11 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a12 {} - customer_id: cus_123 - include_archived: true example: *a12 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 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 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 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: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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. expiry_duration_type: enum: - month - forever 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 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 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. customer_eligibility: type: object properties: trial_available: type: boolean description: Whether a free trial is available for this customer. scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade). required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. required: - list examples: - &a13 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 example: *a13 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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 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. 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: - &a14 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: *a14 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 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 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 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: type: object properties: to: anyOf: - type: number - const: inf amount: type: number flat_amount: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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. expiry_duration_type: enum: - month - forever 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 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 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. customer_eligibility: type: object properties: trial_available: type: boolean description: Whether a free trial is available for this customer. scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: The attach scenario for this customer (e.g. new_subscription, upgrade, downgrade). required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - &a15 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 example: *a15 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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", }, 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: - &a16 plan_id: unused_plan - plan_id: legacy_plan all_versions: true example: *a16 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.1" 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 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: - &a17 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: *a17 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 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: - &a18 id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls example: *a18 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a19 feature_id: api-calls 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 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: get parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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: - &a21 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: *a21 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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: - &a22 feature_id: api-calls name: API Requests display: singular: API request plural: API requests - feature_id: old-feature archived: true example: *a22 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 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: - &a23 id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls example: *a23 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a24 feature_id: old-feature example: *a24 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - &a25 success: true example: *a25 x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. 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. plan_schedule: enum: - immediate - end_of_cycle 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. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. required: - customer_id - plan_id title: AttachParams examples: - &a26 customer_id: cus_123 plan_id: pro_plan example: *a26 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 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: - &a27 customer_id: cus_123 payment_url: https://checkout.stripe.com/... example: *a27 x-speakeasy-name-override: attach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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", ) /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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 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. 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 required: - feature_id required: - customer_id - plans title: MultiAttachParams examples: - &a28 customer_id: cus_123 plans: - plan_id: pro_plan - plan_id: addon_seats feature_quantities: - feature_id: seats quantity: 5 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 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 invoice: status: paid stripe_id: in_1234 total: 4900 currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null example: *a29 x-speakeasy-name-override: multiAttach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. 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. plan_schedule: enum: - immediate - end_of_cycle 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. checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters to pass into the creation of the Stripe checkout session. required: - customer_id - plan_id title: PreviewAttachParams examples: - &a30 customer_id: cus_123 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. line_items: type: array items: type: object properties: title: type: string description: The title of the line item. description: type: string description: A detailed description of the line item. amount: type: number description: The amount in cents for this line item. discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] description: List of discounts applied to this line item. required: - title - description - amount description: List of line items for the current billing period. total: type: number description: The total amount in cents 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. total: type: number description: The total amount in cents for the next cycle. required: - starts_at - total description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. required: - customer_id - line_items - total - currency examples: - &a31 customerId: charles lineItems: - title: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) amount: 20 discounts: [] total: 20 currency: usd example: *a31 x-speakeasy-name-override: previewAttach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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", ) /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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 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. 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 required: - feature_id required: - customer_id - plans title: PreviewMultiAttachParams 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. line_items: type: array items: type: object properties: title: type: string description: The title of the line item. description: type: string description: A detailed description of the line item. amount: type: number description: The amount in cents for this line item. discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] description: List of discounts applied to this line item. required: - title - description - amount description: List of line items for the current billing period. total: type: number description: The total amount in cents 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. total: type: number description: The total amount in cents for the next cycle. required: - starts_at - total description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. required: - customer_id - line_items - total - currency examples: - &a33 customerId: charles lineItems: - title: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) amount: 20 discounts: [] total: 20 currency: usd example: *a33 x-speakeasy-name-override: previewMultiAttach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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. 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel 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. required: - customer_id - plan_id title: UpdateSubscriptionParams examples: - &a34 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 10 example: *a34 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 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: - &a35 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: *a35 x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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, }, ], ) /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. 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel 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. required: - customer_id - plan_id title: PreviewUpdateParams examples: - &a36 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 15 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: title: type: string description: The title of the line item. description: type: string description: A detailed description of the line item. amount: type: number description: The amount in cents for this line item. discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] description: List of discounts applied to this line item. required: - title - description - amount description: List of line items for the current billing period. total: type: number description: The total amount in cents 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. total: type: number description: The total amount in cents for the next cycle. required: - starts_at - total description: Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. required: - customer_id - line_items - total - currency examples: - &a37 customerId: charles lineItems: - title: Pro seed description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026) amount: 20 discounts: [] total: 20 currency: usd example: *a37 x-speakeasy-name-override: previewUpdate parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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, }, ], ) /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: - &a38 customer_id: cus_123 return_url: https://useautumn.com example: *a38 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: - &a39 customer_id: cus_123 url: https://billing.stripe.com/session/... example: *a39 x-speakeasy-name-override: openCustomerPortal parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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 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: anyOf: - type: number - type: "null" required: - to - amount description: Tiered pricing. Either 'amount' or 'tiers' is required. tier_behavior: enum: - graduated - volume interval: enum: - one_off - week - month - quarter - semi_annual - year 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 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 description: Billing behavior when quantity increases mid-cycle. on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations 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. expiry_duration_type: enum: - month - forever 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. 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 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 description: How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges. 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. required: - customer_id title: SetupPaymentParams examples: - &a40 customer_id: cus_123 success_url: https://example.com/account/billing example: *a40 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: - &a41 customer_id: cus_123 url: https://checkout.stripe.com/... example: *a41 x-speakeasy-name-override: setupPayment parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: 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'. reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year 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. expires_at: type: number description: Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset. required: - customer_id - feature_id title: CreateBalanceParams examples: - &a42 customer_id: cus_123 feature_id: api_calls included: 1000 reset: interval: month example: *a42 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.1" 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", included: 1000, 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", included=1000, 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 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 - feature_id title: UpdateBalanceParams examples: - &a43 customer_id: cus_123 feature_id: api_calls remaining: 5 example: *a43 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.1" 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.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. 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: - &a44 customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages required_balance: 3 send_event: true example: *a44 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. preview: type: object properties: scenario: enum: - usage_limit - feature_flag 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 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: "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: "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: "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: type: object properties: to: anyOf: - type: number - const: inf description: The maximum amount of usage for this tier. amount: type: number description: The price of the product item for this tier. flat_amount: anyOf: - type: number - type: "null" description: A flat fee charged for this tier, in addition to the per-unit amount. required: - to - amount - type: "null" description: Tiered pricing for the product item. Not applicable for fixed price items. tier_behavior: anyOf: - enum: - graduated - volume - 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: "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" duration: enum: - month - forever default: month length: type: number required: - max - length - type: "null" on_increase: anyOf: - enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle - type: "null" on_decrease: anyOf: - enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations - 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 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 - downgrade - cancel - expired - past_due 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 examples: - &a45 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: *a45 x-speakeasy-name-override: check parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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. required: - customer_id title: TrackParams examples: - &a46 customer_id: cus_123 feature_id: messages value: 1 example: *a46 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: $ref: "#/components/schemas/Balance" description: Map of feature_id to updated balance when tracking by event_name affects multiple features. required: - customer_id - value - balance examples: - &a47 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 example: *a47 x-speakeasy-name-override: track parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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: - &a48 customer_id: cus_123 limit: 50 - feature_id: api_calls custom_range: start: 1704067200000 end: 1706745600000 example: *a48 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 description: Event properties (JSONB) required: - id - timestamp - feature_id - customer_id - value - properties 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: - &a49 list: - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg timestamp: 1765958215459 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 30 properties: {} - id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM timestamp: 1765956512057 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 49 properties: {} total: 2 has_more: false offset: 0 limit: 100 example: *a49 x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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 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 pattern: ^properties\..* description: Property to group events by. If provided, each key in the response will be an object with distinct groups as the keys range: enum: - 24h - 7d - 30d - 90d - last_cycle - 1bc - 3bc description: Time range to aggregate events for. Either range or custom_range must be provided bin_size: enum: - day - hour - month 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 required: - customer_id - feature_id title: EventsAggregateParams examples: - &a50 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: *a50 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: - &a51 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: *a51 x-speakeasy-name-override: aggregate parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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( customer_id="cus_123", feature_id="api_calls", 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 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: - &a52 customer_id: cus_123 entity_id: seat_42 feature_id: seats name: Seat 42 example: *a52 responses: "200": description: OK content: application/json: schema: type: object properties: autumn_id: type: string 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 description: The environment (sandbox/live) subscriptions: 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 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 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: - 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" 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 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 examples: - &a53 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: *a53 x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a54 entity_id: seat_42 - customer_id: cus_123 entity_id: seat_42 example: *a54 responses: "200": description: OK content: application/json: schema: type: object properties: autumn_id: type: string 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 description: The environment (sandbox/live) subscriptions: 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 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 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: - 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" 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 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 examples: - &a55 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: *a55 x-speakeasy-name-override: get parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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.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: - &a56 customer_id: cus_123 entity_id: seat_42 example: *a56 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - &a57 success: true example: *a57 x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a58 customer_id: cus_123 program_id: prog_123 example: *a58 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: - &a59 code: customer_id: created_at: 123 example: *a59 x-speakeasy-name-override: createCode parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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: - &a60 code: REF123 customer_id: cus_456 example: *a60 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: - &a61 id: customer_id: reward_id: example: *a61 x-speakeasy-name-override: redeemCode parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" 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.1" x-speakeasy-globals-hidden: true