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: - 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 required: - to - amount description: Tiered pricing configuration. Each tier's 'up_to' does NOT include the included amount. Either 'tiers' or 'amount' is required. 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. 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 required: - to - amount description: Tiered pricing configuration if applicable. 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. @example ```typescript // Create or fetch a customer by external ID const response = await client.getOrCreate({ customerId: "cus_123", name: "John Doe", email: "john@example.com" }); ``` @param name - Customer's name (optional) @param email - Customer's email address (optional) @param fingerprint - Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse (optional) @param metadata - Additional metadata for the customer (optional) @param stripeId - Stripe customer ID if you already have one (optional) @param createInStripe - Whether to create the customer in Stripe (optional) @param autoEnablePlanId - The ID of the free plan to auto-enable for the customer (optional) @param sendEmailReceipts - Whether to send email receipts to this customer (optional) @param expand - Customer expand options (optional) tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: anyOf: - $ref: "#/components/schemas/CustomerId" - type: "null" name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one create_in_stripe: type: boolean description: Whether to create the customer in Stripe auto_enable_plan_id: type: string description: The ID of the free plan to auto-enable for the customer send_email_receipts: type: boolean description: Whether to send email receipts to this customer expand: type: array items: $ref: "#/components/schemas/CustomerExpand" description: Customer expand options required: - customer_id title: GetOrCreateCustomerParams examples: - customer_id: cus_123 name: John Doe email: john@example.com responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" x-speakeasy-name-override: getOrCreate parameters: - &a1 name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true /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: - limit: 10 offset: 0 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: - 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 x-speakeasy-name-override: list parameters: - *a1 /v1/customers.update: post: operationId: updateCustomer description: Updates an existing customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to update name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one send_email_receipts: type: boolean description: Whether to send email receipts to this customer new_customer_id: $ref: "#/components/schemas/CustomerId" description: New ID for the customer required: - customer_id title: UpdateCustomerParams examples: - customer_id: cus_123 name: Jane Doe email: jane@example.com responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live 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 x-speakeasy-name-override: update parameters: - *a1 /v1/customers.delete: post: operationId: deleteCustomer description: Deletes a customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to delete delete_in_stripe: type: boolean default: false description: Whether to also delete the customer in Stripe required: - customer_id title: DeleteCustomerParams examples: - customer_id: cus_123 delete_in_stripe: false responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - *a1 /v1/plans.create: post: operationId: createPlan summary: Create a plan description: |- Creates a new plan with optional base price and feature configurations. Use this to programmatically create pricing plans. See [How plans work](/documentation/pricing/plans) for concepts. @example ```typescript // Create a free plan with limited features const response = await client.plans.create({ planId: "free_plan", name: "Free", autoEnable: true, items: [{"featureId":"messages","included":100,"reset":{"interval":"month"}}], }); ``` @example ```typescript // Create a paid plan with base price and usage-based feature const response = await client.plans.create({ planId: "pro_plan", name: "Pro Plan", price: {"amount":10,"interval":"month"}, items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"},"price":{"amount":0.01,"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}], }); ``` @example ```typescript // Create a plan with prepaid seats const response = await client.plans.create({ planId: "team_plan", name: "Team Plan", price: {"amount":49,"interval":"month"}, items: [{"featureId":"seats","included":5,"price":{"amount":10,"interval":"month","billingUnits":1,"billingMethod":"prepaid"}}], }); ``` @example ```typescript // Create an add-on plan const response = await client.plans.create({ planId: "analytics_addon", name: "Advanced Analytics", addOn: true, price: {"amount":20,"interval":"month"}, }); ``` @example ```typescript // Create a plan with tiered pricing const response = await client.plans.create({ planId: "api_plan", name: "API Plan", items: [{"featureId":"api_calls","included":1000,"reset":{"interval":"month"},"price":{"tiers":[{"to":10000,"amount":0.001},{"to":100000,"amount":0.0005},{"to":"inf","amount":0.0001}],"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}] }); ``` @example ```typescript // Create a plan with free trial const response = await client.plans.create({ planId: "premium_plan", name: "Premium", price: {"amount":99,"interval":"month"}, freeTrial: {"durationLength":14,"durationType":"day","cardRequired":true}, }); ``` @param planId - The ID of the plan to create. @param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional) @param name - Display name of the plan. @param description - Optional description of the plan. (optional) @param addOn - If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. (optional) @param autoEnable - If true, plan is automatically attached when a customer is created. Use for free tiers. (optional) @param price - Base recurring price for the plan. Omit for free or usage-only plans. (optional) @param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional) @param freeTrial - Free trial configuration. Customers can try this plan before being charged. (optional) @returns The created plan object. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: The ID of the plan to create. group: type: string default: "" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. name: type: string minLength: 1 description: Display name of the plan. description: anyOf: - type: string - type: "null" default: null description: Optional description of the plan. add_on: type: boolean default: false description: If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. auto_enable: type: boolean default: false description: If true, plan is automatically attached when a customer is created. Use for free tiers. price: type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 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: - plan_id: free_plan name: Free auto_enable: true items: - feature_id: messages included: 100 reset: interval: month - plan_id: pro_plan name: Pro Plan price: amount: 10 interval: month items: - feature_id: messages included: 1000 reset: interval: month price: amount: 0.01 interval: month billing_units: 1 billing_method: usage_based - plan_id: team_plan name: Team Plan price: amount: 49 interval: month items: - feature_id: seats included: 5 price: amount: 10 interval: month billing_units: 1 billing_method: prepaid responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year 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 required: - to - amount description: Tiered pricing configuration. Each tier's 'up_to' does NOT include the included amount. Either 'tiers' or 'amount' is required. 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. 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: - 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 x-speakeasy-name-override: create parameters: - *a1 /v1/plans.get: post: operationId: getPlan summary: Get a plan description: >- Retrieves a single plan by its ID. Use this to fetch the full configuration of a specific plan, including its features and pricing. @example ```typescript // Get a plan by ID const response = await client.plans.get({ planId: "pro_plan" }); ``` @example ```typescript // Get a specific version of a plan const response = await client.plans.get({ planId: "pro_plan", version: 2 }); ``` @param planId - The ID of the plan to retrieve. @param version - The version of the plan to get. Defaults to the latest version. (optional) @returns The plan object with its full configuration. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 description: The ID of the plan to retrieve. version: type: number description: The version of the plan to get. Defaults to the latest version. required: - plan_id title: GetPlanParams examples: - plan_id: pro_plan - plan_id: pro_plan version: 2 responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year 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 required: - to - amount description: Tiered pricing configuration. Each tier's 'up_to' does NOT include the included amount. Either 'tiers' or 'amount' is required. 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. 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: - 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 x-speakeasy-name-override: get parameters: - *a1 /v1/plans.list: post: operationId: listPlans summary: List all plans description: >- Lists all plans in the current environment. Use this to retrieve all plans for displaying pricing pages or managing plan configurations. @returns A list of all plans with their pricing and feature configurations. tags: - plans requestBody: required: false content: application/json: schema: type: object properties: customer_id: type: string description: Customer ID to include eligibility info (trial availability, attach scenario). entity_id: type: string description: Entity ID for entity-scoped plans. include_archived: type: boolean description: If true, includes archived plans in the response. title: ListPlansParams examples: - {} - customer_id: cus_123 - include_archived: true responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year 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 required: - to - amount description: Tiered pricing configuration. Each tier's 'up_to' does NOT include the included amount. Either 'tiers' or 'amount' is required. 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. 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: - 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 x-speakeasy-name-override: list parameters: - *a1 /v1/plans.update: post: operationId: updatePlan summary: Update a plan description: |- Updates an existing plan. Creates a new version unless `disableVersion` is set. Use this to modify plan properties, pricing, or feature configurations. See [Adding features to plans](/documentation/pricing/plan-features) for item configuration. @example ```typescript // Update plan name and price const response = await client.plans.update({ planId: "pro_plan", name: "Pro Plan (Updated)", price: {"amount":15,"interval":"month"} }); ``` @example ```typescript // Add a feature to an existing plan const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"}},{"featureId":"storage","included":10,"reset":{"interval":"month"}}] }); ``` @example ```typescript // Remove the base price (make usage-only) const response = await client.plans.update({ planId: "pro_plan", price: null }); ``` @example ```typescript // Archive a plan const response = await client.plans.update({ planId: "old_plan", archived: true }); ``` @example ```typescript // Update feature's included amount const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":2000,"reset":{"interval":"month"}}] }); ``` @param planId - The ID of the plan to update. @param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional) @param name - Display name of the plan. (optional) @param addOn - Whether the plan is an add-on. (optional) @param autoEnable - Whether the plan is automatically enabled. (optional) @param price - The price of the plan. Set to null to remove the base price. (optional) @param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional) @param freeTrial - The free trial of the plan. Set to null to remove the free trial. (optional) @param newPlanId - The new ID to use for the plan. Can only be updated if the plan has not been used by any customers. (optional) @returns The updated plan object. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: The ID of the plan to update. group: type: string default: "" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. name: type: string minLength: 1 description: Display name of the plan. description: type: string add_on: type: boolean description: Whether the plan is an add-on. auto_enable: type: boolean description: Whether the plan is automatically enabled. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year description: Billing interval (e.g. 'month', 'year'). interval_count: type: number description: Number of intervals per billing cycle. Defaults to 1. required: - amount - interval - 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 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 - 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: - plan_id: pro_plan name: Pro Plan (Updated) price: amount: 15 interval: month - plan_id: pro_plan price: null - plan_id: old_plan archived: true responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: Unique identifier for the plan. name: type: string description: Display name of the plan. description: anyOf: - type: string - type: "null" description: Optional description of the plan. group: anyOf: - type: string - type: "null" description: Group identifier for organizing related plans. Plans in the same group are mutually exclusive. version: type: number description: Version number of the plan. Incremented when plan configuration changes. add_on: type: boolean description: Whether this is an add-on plan that can be attached alongside a main plan. auto_enable: type: boolean description: If true, this plan is automatically attached when a customer is created. Used for free plans. price: anyOf: - type: object properties: amount: type: number description: Base price amount for the plan. interval: enum: - one_off - week - month - quarter - semi_annual - year 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 required: - to - amount description: Tiered pricing configuration. Each tier's 'up_to' does NOT include the included amount. Either 'tiers' or 'amount' is required. 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. 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: - 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 x-speakeasy-name-override: update parameters: - *a1 /v1/plans.delete: post: operationId: deletePlan summary: Delete a plan description: >- Deletes a plan by its ID. Use this to permanently remove a plan. Plans with active customers cannot be deleted - archive them instead. @example ```typescript // Delete a plan const response = await client.plans.delete({ planId: "unused_plan" }); ``` @example ```typescript // Delete all versions of a plan const response = await client.plans.delete({ planId: "legacy_plan", allVersions: true }); ``` @param planId - The ID of the plan to delete. @param allVersions - If true, deletes all versions of the plan. Otherwise, only deletes the latest version. (optional) @returns A success flag indicating the plan was deleted. tags: - plans requestBody: required: true content: application/json: schema: type: object properties: plan_id: type: string minLength: 1 description: The ID of the plan to delete. all_versions: type: boolean default: false description: If true, deletes all versions of the plan. Otherwise, only deletes the latest version. required: - plan_id title: DeletePlanParams examples: - plan_id: unused_plan - plan_id: legacy_plan all_versions: true responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - *a1 /v1/features.create: post: operationId: createFeature description: >- Creates a new feature. Use this to programmatically create features for metering usage, managing access, or building credit systems. @example ```typescript // Create a metered feature for API calls const response = await client.features.create({ featureId: "api-calls", name: "API Calls", type: "metered", consumable: true, }); ``` @example ```typescript // Create a boolean feature for a premium feature flag const response = await client.features.create({ featureId: "advanced-analytics", name: "Advanced Analytics", type: "boolean" }); ``` @param name - The name of the feature. @param type - The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. @param consumable - Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. (optional) @param display - Singular and plural display names for the feature in your user interface. (optional) @param creditSchema - A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. (optional) @param featureId - The ID of the feature to create. @returns The created feature object. tags: - features requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the feature. type: enum: - boolean - metered - credit_system description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. consumable: type: boolean description: Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. display: type: object properties: singular: type: string plural: type: string required: - singular - plural description: Singular and plural display names for the feature in your user interface. credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. event_names: type: array items: type: string feature_id: type: string description: The ID of the feature to create. required: - name - type - feature_id title: CreateFeatureParams examples: - feature_id: api-calls name: API Calls type: metered consumable: true - feature_id: credits name: Credits type: credit_system consumable: true credit_schema: - metered_feature_id: api-calls credit_cost: 1 - metered_feature_id: image-generations credit_cost: 10 responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: The unique identifier for this feature, used in /check and /track calls. name: type: string description: Human-readable name displayed in the dashboard and billing UI. type: enum: - boolean - metered - credit_system description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: create parameters: - *a1 /v1/features.get: post: operationId: getFeature description: |- Retrieves a single feature by its ID. Use this when you need to fetch the details of a specific feature. @example ```typescript // Get a feature by ID const response = await client.features.get({ featureId: "api-calls" }); ``` @param featureId - The ID of the feature. @returns The feature object with its full configuration. tags: - features requestBody: required: true content: application/json: schema: type: object properties: feature_id: type: string description: The ID of the feature. required: - feature_id title: GetFeatureParams examples: - feature_id: api-calls responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: The unique identifier for this feature, used in /check and /track calls. name: type: string description: Human-readable name displayed in the dashboard and billing UI. type: enum: - boolean - metered - credit_system description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: get parameters: - *a1 /v1/features.list: post: operationId: listFeatures description: >- Lists all features in the current environment. Use this to retrieve all features configured for your organization to display in dashboards or for feature management. @returns A list of all features with their configuration and metadata. tags: - features responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: The unique identifier for this feature, used in /check and /track calls. name: type: string description: Human-readable name displayed in the dashboard and billing UI. type: enum: - boolean - metered - credit_system description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived required: - list examples: - list: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls - id: credits name: Credits type: credit_system consumable: true archived: false credit_schema: - metered_feature_id: api-calls credit_cost: 1 - metered_feature_id: image-generations credit_cost: 10 display: singular: credit plural: credits x-speakeasy-name-override: list parameters: - *a1 /v1/features.update: post: operationId: updateFeature description: >- Updates an existing feature. Use this to modify feature properties like name, display settings, or to archive a feature. @example ```typescript // Update a feature's display name const response = await client.features.update({ featureId: "api-calls", name: "API Requests", display: {"singular":"API request","plural":"API requests"} }); ``` @example ```typescript // Archive a feature const response = await client.features.update({ featureId: "deprecated-feature", archived: true }); ``` @param name - The name of the feature. (optional) @param type - The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. (optional) @param consumable - Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. (optional) @param display - Singular and plural display names for the feature in your user interface. (optional) @param creditSchema - A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. (optional) @param archived - Whether the feature is archived. Archived features are hidden from the dashboard. (optional) @param featureId - The ID of the feature to update. @param newFeatureId - The new ID of the feature. Feature ID can only be updated if it's not being used by any customers. (optional) @returns The updated feature object. tags: - features requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 description: The name of the feature. type: enum: - boolean - metered - credit_system description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. consumable: type: boolean description: Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features. display: type: object properties: singular: type: string plural: type: string required: - singular - plural description: Singular and plural display names for the feature in your user interface. credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. event_names: type: array items: type: string archived: type: boolean description: Whether the feature is archived. Archived features are hidden from the dashboard. feature_id: type: string description: The ID of the feature to update. new_feature_id: type: string description: The new ID of the feature. Feature ID can only be updated if it's not being used by any customers. required: - feature_id title: UpdateFeatureParams examples: - feature_id: api-calls name: API Requests display: singular: API request plural: API requests - feature_id: old-feature archived: true responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: The unique identifier for this feature, used in /check and /track calls. name: type: string description: Human-readable name displayed in the dashboard and billing UI. type: enum: - boolean - metered - credit_system description: "Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools." consumable: type: boolean description: "For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage)." event_names: type: array items: type: string description: Event names that trigger this feature's balance. Allows multiple features to respond to a single event. credit_schema: type: array items: type: object properties: metered_feature_id: type: string description: ID of the metered feature that draws from this credit system. credit_cost: type: number description: Credits consumed per unit of the metered feature. required: - metered_feature_id - credit_cost description: "For credit_system features: maps metered features to their credit costs." display: type: object properties: singular: anyOf: - type: string - type: "null" description: Singular form for UI display (e.g., 'API call', 'seat'). plural: anyOf: - type: string - type: "null" description: Plural form for UI display (e.g., 'API calls', 'seats'). description: Display names for the feature in billing UI and customer-facing components. archived: type: boolean description: Whether the feature is archived and hidden from the dashboard. required: - id - name - type - consumable - archived examples: - id: api-calls name: API Calls type: metered consumable: true archived: false display: singular: API call plural: API calls x-speakeasy-name-override: update parameters: - *a1 /v1/features.delete: post: operationId: deleteFeature description: >- Deletes a feature by its ID. Use this to permanently remove a feature. Note: features that are used in products cannot be deleted - archive them instead. @example ```typescript // Delete an unused feature const response = await client.features.delete({ featureId: "old-feature" }); ``` @param featureId - The ID of the feature to delete. @returns A success flag indicating the feature was deleted. tags: - features requestBody: required: true content: application/json: schema: type: object properties: feature_id: type: string description: The ID of the feature to delete. required: - feature_id title: DeleteFeatureParams examples: - feature_id: old-feature responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - success: true x-speakeasy-name-override: delete parameters: - *a1 /v1/billing.attach: post: operationId: billingAttach description: >- Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades. Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product. @example ```typescript // Attach a plan to a customer const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan" }); ``` @example ```typescript // Attach with a free trial const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan", freeTrial: {"durationLength":14,"durationType":"day"} }); ``` @example ```typescript // Attach with custom pricing const response = await client.billing.attach({ customerId: "cus_123", planId: "pro_plan", customize: {"price":{"amount":4900,"interval":"month"}} }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan. @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param freeTrial - Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. (optional) @param customize - Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param billingBehavior - How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param planSchedule - When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) @returns A billing response with customer ID, invoice details, and payment URL (if checkout required). tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id 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. 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 - 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. 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 - type: "null" 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. 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. billing_behavior: enum: - prorate_immediately - next_cycle_only description: How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. discounts: type: array items: anyOf: - type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. required: - reward_id - type: object properties: promotion_code: type: string description: The promotion code to apply as a discount. required: - promotion_code 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. required: - customer_id - plan_id title: AttachParams examples: - customer_id: cus_123 plan_id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity, if the plan was attached to an entity. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason description: Details about any action required to complete the payment. Present when the payment could not be processed automatically. required: - customer_id - payment_url examples: - customer_id: cus_123 payment_url: https://checkout.stripe.com/... x-speakeasy-name-override: attach parameters: - *a1 /v1/billing.preview_attach: post: operationId: previewAttach description: >- Previews the billing changes that would occur when attaching a plan, without actually making any changes. Use this endpoint to show customers what they will be charged before confirming a subscription change. @example ```typescript // Preview attaching a plan const response = await client.billing.previewAttach({ customerId: "cus_123", planId: "pro_plan" }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param planId - The ID of the plan. @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param freeTrial - Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. (optional) @param customize - Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param billingBehavior - How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. (optional) @param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional) @param successUrl - URL to redirect to after successful checkout. (optional) @param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional) @param planSchedule - When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) @returns A preview response with line items, totals, and effective dates for the proposed changes. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id 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. 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 - 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. 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 - type: "null" 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. 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. billing_behavior: enum: - prorate_immediately - next_cycle_only description: How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. discounts: type: array items: anyOf: - type: object properties: reward_id: type: string description: The ID of the reward to apply as a discount. required: - reward_id - type: object properties: promotion_code: type: string description: The promotion code to apply as a discount. required: - promotion_code 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. required: - customer_id - plan_id title: PreviewAttachParams examples: - customer_id: cus_123 plan_id: pro_plan responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. line_items: type: array items: type: object properties: 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: - 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 x-speakeasy-name-override: previewAttach parameters: - *a1 /v1/billing.update: post: operationId: billingUpdate description: >- Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration. Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings. @example ```typescript // Update prepaid feature quantity const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [{"featureId":"seats","quantity":10}] }); ``` @example ```typescript // Cancel a subscription at end of billing cycle const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", cancelAction: "cancel_end_of_cycle" }); ``` @example ```typescript // Uncancel a subscription at the end of the billing cycle const response = await client.billing.update({ customerId: "cus_123", planId: "pro_plan", cancelAction: "uncancel" }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param freeTrial - Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. (optional) @param customize - Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param billingBehavior - How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. (optional) @param cancelAction - Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. (optional) @returns A billing response with customer ID, invoice details, and payment URL (if next action is required). tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id 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. 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 - 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. 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 - type: "null" 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. 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. billing_behavior: enum: - prorate_immediately - next_cycle_only description: How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. 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: - customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 10 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity, if the plan was attached to an entity. invoice: type: object properties: status: anyOf: - type: string - type: "null" description: The status of the invoice (e.g., 'paid', 'open', 'draft'). stripe_id: type: string description: The Stripe invoice ID. total: type: number description: The total amount of the invoice in cents. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the hosted invoice page where the customer can view and pay the invoice. required: - status - stripe_id - total - currency - hosted_invoice_url description: Invoice details if an invoice was created. Only present when a charge was made. payment_url: anyOf: - type: string - type: "null" description: URL to redirect the customer to complete payment. Null if no payment action is required. required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed description: The type of action required to complete the payment. reason: type: string description: A human-readable explanation of why this action is required. required: - code - reason description: Details about any action required to complete the payment. Present when the payment could not be processed automatically. required: - customer_id - payment_url examples: - customer_id: cus_123 invoice: status: paid stripe_id: in_1234 total: 1500 currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null x-speakeasy-name-override: update parameters: - *a1 /v1/billing.preview_update: post: operationId: previewUpdate description: >- Previews the billing changes that would occur when updating a subscription, without actually making any changes. Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications. @example ```typescript // Preview updating seat quantity const response = await client.billing.previewUpdate({ customerId: "cus_123", planId: "pro_plan", featureQuantities: [{"featureId":"seats","quantity":15}] }); ``` @param customerId - The ID of the customer to attach the plan to. @param entityId - The ID of the entity to attach the plan to. (optional) @param featureQuantities - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. (optional) @param version - The version of the plan to attach. (optional) @param freeTrial - Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. (optional) @param customize - Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. (optional) @param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method. (optional) @param billingBehavior - How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. (optional) @param cancelAction - Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation. (optional) @returns A preview response with line items showing prorated charges or credits for the proposed changes. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: type: string description: The ID of the entity to attach the plan to. plan_id: type: string description: The ID of the plan. feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id 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. 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 - 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. 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 - type: "null" 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 required: - to - amount description: Tiered pricing. Each tier's 'to' does NOT include included amount. Either 'amount' or 'tiers' is required. 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 description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. 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. billing_behavior: enum: - prorate_immediately - next_cycle_only description: How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. 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: - customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 15 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. line_items: type: array items: type: object properties: 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: - 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 x-speakeasy-name-override: previewUpdate parameters: - *a1 /v1/billing.open_customer_portal: post: operationId: openCustomerPortal description: Create a billing portal session for a customer to manage their subscription. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to open the billing portal for. configuration_id: type: string description: Stripe billing portal configuration ID. Create configurations in your Stripe dashboard. return_url: type: string description: URL to redirect to when back button is clicked in the billing portal required: - customer_id title: OpenCustomerPortalParams examples: - customer_id: cus_123 return_url: https://useautumn.com responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the billing portal session url: type: string description: URL to the billing portal required: - customer_id - url examples: - customer_id: cus_123 url: https://billing.stripe.com/session/... x-speakeasy-name-override: openCustomerPortal parameters: - *a1 /v1/billing.setup_payment: post: operationId: setupPayment description: Create a payment setup session for a customer to add or update their payment method. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer success_url: type: string description: URL to redirect to after successful payment setup. Must start with either http:// or https:// customer_data: $ref: "#/components/schemas/CustomerData" checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters for the checkout session required: - customer_id title: SetupPaymentParams examples: - customer_id: cus_123 success_url: https://example.com/account/billing responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer url: type: string description: URL to the payment setup page required: - customer_id - url examples: - customer_id: cus_123 payment_url: https://checkout.stripe.com/... x-speakeasy-name-override: setupPayment parameters: - *a1 /v1/balances.create: post: operationId: createBalance description: Create a balance for a customer feature. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. feature_id: type: string description: The ID of the feature. entity_id: type: string description: The ID of the entity for entity-scoped balances (e.g., per-seat limits). included: 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: - customer_id: cus_123 feature_id: api_calls included: 1000 reset: interval: month responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: create parameters: - *a1 /v1/balances.update: post: operationId: updateBalance description: Update a customer balance. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. feature_id: type: string description: The ID of the feature. entity_id: type: string description: The ID of the entity for entity-scoped balances (e.g., per-seat limits). remaining: type: number description: Set the remaining balance to this exact value. Cannot be combined with add_to_balance. add_to_balance: type: number description: Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance. 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: - customer_id: cus_123 feature_id: api_calls remaining: 5 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: update parameters: - *a1 /v1/balances.check: post: operationId: check description: >- Checks whether a customer currently has enough balance to use a feature. Use this to gate access before a feature action. Enable sendEvent when you want to check and consume balance atomically in one request. @example ```typescript // Check access for a feature const response = await client.check({ customerId: "cus_123", featureId: "messages" }); ``` @example ```typescript // Check and consume 3 units in one call const response = await client.check({ customerId: "cus_123", featureId: "messages", requiredBalance: 3, sendEvent: true, }); ``` @param customerId - The ID of the customer. @param featureId - The ID of the feature. @param entityId - The ID of the entity for entity-scoped balances (e.g., per-seat limits). (optional) @param requiredBalance - Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1. (optional) @param properties - Additional properties to attach to the usage event if send_event is true. (optional) @param sendEvent - If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call. (optional) @param withPreview - If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls. (optional) @returns Whether access is allowed, plus the current balance for that feature. 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: - customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages required_balance: 3 send_event: true responses: "200": description: OK content: application/json: schema: type: object properties: allowed: type: boolean description: Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean. customer_id: type: string description: The ID of the customer that was checked. entity_id: anyOf: - type: string - type: "null" description: The ID of the entity, if an entity-scoped check was performed. required_balance: type: number description: The required balance that was checked against. balance: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: The customer's balance for this feature. Null if the customer has no balance for this feature. 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. required: - to - amount - type: "null" description: Tiered pricing for the product item. Not applicable for fixed price items. 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: - allowed: true customer_id: cus_123 entity_id: null required_balance: 1 balance: feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null x-speakeasy-name-override: check parameters: - *a1 /v1/balances.track: post: operationId: track description: >- Records usage for a customer feature and returns updated balances. Use this after an action happens to decrement usage, or send a negative value to credit balance back. @example ```typescript // Track one message event const response = await client.track({ customerId: "cus_123", featureId: "messages", value: 1 }); ``` @example ```typescript // Track an event mapped to multiple features const response = await client.track({ customerId: "cus_123", eventName: "ai_chat_request", value: 1 }); ``` @param customerId - The ID of the customer. @param featureId - The ID of the feature to track usage for. Required if event_name is not provided. (optional) @param entityId - The ID of the entity for entity-scoped balances (e.g., per-seat limits). (optional) @param eventName - Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event. (optional) @param value - The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat). (optional) @param properties - Additional properties to attach to this usage event. (optional) @returns The usage value recorded, with either a single updated balance or a map of updated 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 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: - customer_id: cus_123 feature_id: messages value: 1 responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer whose usage was tracked. entity_id: type: string description: The ID of the entity, if entity-scoped tracking was performed. event_name: type: string description: The event name that was tracked, if event_name was used instead of feature_id. value: type: number description: The amount of usage that was recorded. balance: anyOf: - $ref: "#/components/schemas/Balance" - type: "null" description: The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features. balances: type: object propertyNames: type: string additionalProperties: $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: - 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 x-speakeasy-name-override: track parameters: - *a1 /v1/events.list: post: operationId: listEvents description: List usage events for your organization. Filter by customer, feature, or time range. tags: - events requestBody: required: true content: application/json: schema: type: object properties: 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: - customer_id: cus_123 limit: 50 - feature_id: api_calls custom_range: start: 1704067200000 end: 1706745600000 responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string description: Event ID (KSUID) timestamp: type: number description: Event timestamp (epoch milliseconds) feature_id: type: string description: ID of the feature that the event belongs to customer_id: type: string description: Customer identifier value: type: number description: Event value/count properties: type: object 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: - 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 x-speakeasy-name-override: list parameters: - *a1 /v1/events.aggregate: post: operationId: aggregateEvents description: Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property. tags: - events requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string minLength: 1 description: Customer ID to aggregate events for 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: - customer_id: cus_123 feature_id: api_calls range: 30d bin_size: day - customer_id: cus_123 feature_id: - api_calls - messages range: 7d group_by: properties.model responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: period: type: number description: Unix timestamp (epoch ms) for this time period values: type: object propertyNames: type: string additionalProperties: type: number description: "Aggregated values per feature: { [featureId]: number }" grouped_values: type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: number description: "Values broken down by group (only present when group_by is used): { [featureId]: { [groupValue]: number } }" required: - period - values description: Array of time periods with aggregated values total: type: object propertyNames: type: string additionalProperties: type: object properties: count: type: number description: Number of events for this feature sum: type: number description: Sum of event values for this feature required: - count - sum description: Total aggregations per feature. Keys are feature IDs, values contain count and sum. required: - list - total examples: - list: - period: 1762905600000 values: messages: 10 sessions: 3 - period: 1762992000000 values: messages: 3 sessions: 12 total: messages: count: 2 sum: 13 sessions: count: 2 sum: 15 - list: - period: 1762905600000 values: messages: 10 sessions: 3 grouped_values: messages: api: 5 web: 5 sessions: api: 2 web: 1 - period: 1762992000000 values: messages: 3 sessions: 12 grouped_values: messages: api: 1 web: 2 sessions: api: 10 web: 2 total: messages: count: 2 sum: 13 sessions: count: 2 sum: 15 x-speakeasy-name-override: aggregate parameters: - *a1 /v1/entities.create: post: operationId: createEntity description: >- Creates an entity for a customer and feature, then returns the entity with balances and subscriptions. Use entities when usage and access must be scoped to sub-resources (for example seats, projects, or workspaces) instead of only the customer. @example ```typescript // Create a seat entity const response = await client.entities.create({ customerId: "cus_123", entityId: "seat_42", featureId: "seats", name: "Seat 42", }); ``` @param name - The name of the entity (optional) @param featureId - The ID of the feature this entity is associated with @param customerData - Customer attributes used to resolve the customer when customer_id is not provided. (optional) @param customerId - The ID of the customer to create the entity for. @param entityId - The ID of the entity. @returns The created entity object including its current subscriptions, purchases, and balances. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: name: anyOf: - type: string - type: "null" description: The name of the entity feature_id: type: string description: The ID of the feature this entity is associated with customer_data: $ref: "#/components/schemas/CustomerData" description: Customer attributes used to resolve the customer when customer_id is not provided. customer_id: type: string description: The ID of the customer to create the entity for. entity_id: type: string description: The ID of the entity. required: - feature_id - customer_id - entity_id title: CreateEntityParams examples: - customer_id: cus_123 entity_id: seat_42 feature_id: seats name: Seat 42 responses: "200": description: OK content: application/json: schema: type: object properties: 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: - id: seat_42 name: Seat 42 customer_id: cus_123 feature_id: seats created_at: 1771409161016 env: sandbox subscriptions: - plan_id: pro_plan auto_enable: true add_on: false status: active past_due: false canceled_at: null expires_at: null trial_ends_at: null started_at: 1771431921437 current_period_start: 1771431921437 current_period_end: 1771999921437 quantity: 1 purchases: [] balances: messages: feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null invoices: [] x-speakeasy-name-override: create parameters: - *a1 /v1/entities.get: post: operationId: getEntity description: >- Fetches an entity by its ID. Use this to read one entity's current state. Pass customerId when you want to scope the lookup to a specific customer. @example ```typescript // Fetch a seat entity const response = await client.entities.get({ entityId: "seat_42" }); ``` @example ```typescript // Fetch a seat entity for a specific customer const response = await client.entities.get({ customerId: "cus_123", entityId: "seat_42" }); ``` @param customerId - The ID of the customer to create the entity for. (optional) @param entityId - The ID of the entity. @returns The entity object including its current subscriptions, purchases, and balances. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to create the entity for. entity_id: type: string description: The ID of the entity. required: - entity_id title: GetEntityParams examples: - entity_id: seat_42 - customer_id: cus_123 entity_id: seat_42 responses: "200": description: OK content: application/json: schema: type: object properties: 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: - id: seat_42 name: Seat 42 customer_id: cus_123 feature_id: seats created_at: 1771409161016 env: sandbox subscriptions: - plan_id: pro_plan auto_enable: true add_on: false status: active past_due: false canceled_at: null expires_at: null trial_ends_at: null started_at: 1771431921437 current_period_start: 1771431921437 current_period_end: 1771999921437 quantity: 1 purchases: [] balances: messages: feature_id: messages granted: 100 remaining: 72 usage: 28 unlimited: false overage_allowed: false max_purchase: null next_reset_at: 1773851121437 breakdown: - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV plan_id: pro_plan included_grant: 100 prepaid_grant: 0 remaining: 72 usage: 28 unlimited: false reset: interval: month resets_at: 1773851121437 price: null expires_at: null invoices: [] x-speakeasy-name-override: get parameters: - *a1 /v1/entities.delete: post: operationId: deleteEntity description: >- Deletes an entity by entity ID. Use this when the underlying resource is removed and you no longer want entity-scoped balances or subscriptions tracked for it. @example ```typescript // Delete a seat entity const response = await client.entities.delete({ entityId: "seat_42" }); ``` @param customerId - The ID of the customer. (optional) @param entityId - The ID of the entity. @returns A success flag indicating the entity was deleted. tags: - entities requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity. required: - entity_id title: DeleteEntityParams examples: - customer_id: cus_123 entity_id: seat_42 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success examples: - success: true x-speakeasy-name-override: delete parameters: - *a1 /v1/referrals.create_code: post: operationId: createReferralCode description: Create or fetch a referral code for a customer in a referral program. tags: - referrals requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The unique identifier of the customer program_id: type: string description: ID of your referral program required: - customer_id - program_id title: CreateReferralCodeParams examples: - customer_id: cus_123 program_id: prog_123 responses: "200": description: OK content: application/json: schema: type: object properties: code: type: string description: The referral code that can be shared with customers customer_id: type: string description: Your unique identifier for the customer created_at: type: number description: The timestamp of when the referral code was created required: - code - customer_id - created_at examples: - code: customer_id: created_at: 123 x-speakeasy-name-override: createCode parameters: - *a1 /v1/referrals.redeem_code: post: operationId: redeemReferralCode description: Redeem a referral code for a customer. tags: - referrals requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: The referral code to redeem customer_id: type: string description: The unique identifier of the customer redeeming the code required: - code - customer_id title: RedeemReferralCodeParams examples: - code: REF123 customer_id: cus_456 responses: "200": description: OK content: application/json: schema: type: object properties: id: type: string description: The ID of the redemption event customer_id: type: string description: Your unique identifier for the customer reward_id: type: string description: The ID of the reward that will be granted required: - id - customer_id - reward_id examples: - id: customer_id: reward_id: x-speakeasy-name-override: redeemCode parameters: - *a1 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