From 33ac5a942daa4154890ce4abc648636fd6ed7118 Mon Sep 17 00:00:00 2001 From: amianthus <49116958+SirTenzin@users.noreply.github.com> Date: Wed, 6 May 2026 12:00:13 +0100 Subject: [PATCH] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20openapi=20contracts=20fo?= =?UTF-8?q?r=20schedules=20and=20get=20customer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/openapi/openapi-stripped.yml | 5142 +++++++++++------ packages/openapi/openapi.yml | 1802 +++++- .../openapi/v2.1/contracts/billingContract.ts | 63 + .../v2.1/contracts/customersContract.ts | 38 +- packages/openapi/v2.1/contracts/index.ts | 4 + packages/openapi/v2.1/jsDocs/billingJsDocs.ts | 30 + .../openapi/v2.1/jsDocs/customerJsDocs.ts | 29 +- packages/openapi/v2.1/openapi2.1.ts | 2 + 8 files changed, 5354 insertions(+), 1756 deletions(-) diff --git a/packages/openapi/openapi-stripped.yml b/packages/openapi/openapi-stripped.yml index fe719adfb..0ce71624b 100644 --- a/packages/openapi/openapi-stripped.yml +++ b/packages/openapi/openapi-stripped.yml @@ -1791,7 +1791,7 @@ paths: expand: type: array items: - type: string + $ref: "#/components/schemas/CustomerExpand" description: Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature. @@ -1822,6 +1822,782 @@ paths: type: string default: 2.2.0 x-speakeasy-globals-hidden: true + /v1/customers.get: + post: + operationId: getCustomer + description: >- + Fetches a customer by ID, optionally expanding related data such as + invoices or entities. + + + Use this when you know the customer exists or assert they exist without + creating them. + tags: + - customers + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + title: CustomerId + description: ID of the customer to fetch + expand: + type: array + items: + $ref: "#/components/schemas/CustomerExpand" + description: Expand related customer data like invoices or entities, or expand + nested objects like balances.feature, flags.feature, + subscriptions.plan, and purchases.plan. + required: + - customer_id + title: GetCustomerParams + examples: + - &a3 + customer_id: cus_123 + - customer_id: cus_123 + expand: + - invoices + - entities + example: *a3 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: Your unique identifier for the customer. + name: + anyOf: + - type: string + - type: "null" + description: The name of the customer. + email: + anyOf: + - type: string + - type: "null" + description: The email address of the customer. + created_at: + type: number + description: Timestamp of customer creation in milliseconds since epoch. + fingerprint: + anyOf: + - type: string + - type: "null" + description: "A unique identifier (eg. serial number) to de-duplicate customers + across devices or browsers. For example: apple device ID." + stripe_id: + anyOf: + - type: string + - type: "null" + description: Stripe customer ID. + env: + enum: + - sandbox + - live + type: string + description: The environment this customer was created in. + metadata: + type: object + propertyNames: {} + additionalProperties: {} + description: The metadata for the customer. + send_email_receipts: + type: boolean + description: Whether to send email receipts to the customer. + billing_controls: + type: object + properties: + auto_topups: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature (credit balance) to auto top-up. + enabled: + type: boolean + default: false + description: Whether auto top-up is enabled. + threshold: + type: number + minimum: 0 + description: When the balance drops below this threshold, an auto top-up will be + purchased. + quantity: + type: number + minimum: 1 + description: Amount of credits to add per auto top-up. + purchase_limit: + anyOf: + - type: object + properties: + interval: + enum: + - hour + - day + - week + - month + type: string + description: The time interval for the purchase limit window. + interval_count: + type: number + minimum: 1 + default: 1 + description: Number of intervals in the purchase limit window. + limit: + type: number + minimum: 1 + description: Maximum number of auto top-ups allowed within the interval. + required: + - interval + - limit + - type: object + properties: + interval: + anyOf: + - enum: + - hour + - day + - week + - month + type: string + - type: "null" + description: The time interval for the purchase limit window. Null when no + purchase limit is configured. + interval_count: + anyOf: + - type: number + minimum: 1 + - type: "null" + description: Number of intervals in the purchase limit window. Null when no + purchase limit is configured. + limit: + anyOf: + - type: number + minimum: 1 + - type: "null" + description: Maximum number of auto top-ups allowed within the interval. Null + when no purchase limit is configured. + count: + type: number + description: Number of auto top-ups already consumed in the current window. + next_reset_at: + type: number + description: Unix ms timestamp when the current purchase window ends and the + count resets. + required: + - interval + - interval_count + - limit + - count + - next_reset_at + description: Optional rate limit to cap how often auto top-ups occur. Expand + billing_controls.auto_topups.purchase_limit for + a count of top ups and the next_reset_at. + invoice_mode: + type: boolean + description: When true, auto top-up creates a send_invoice invoice instead of + auto-charging. + required: + - feature_id + - threshold + - quantity + description: List of auto top-up configurations per feature. + spend_limits: + type: array + items: + type: object + properties: + feature_id: + type: string + description: Optional feature ID this spend limit applies to. + enabled: + type: boolean + default: false + description: Whether this spend limit is enabled. + overage_limit: + type: number + minimum: 0 + description: Maximum allowed overage spend for the target feature. + description: List of overage spend limits per feature. + usage_alerts: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this alert applies to. + enabled: + type: boolean + default: true + description: Whether this usage alert is enabled. + threshold: + type: number + minimum: 0 + description: The threshold value that triggers the alert. For usage or + remaining, this is an absolute count. For + usage_percentage or remaining_percentage, this + is a percentage (0-100). + threshold_type: + enum: + - usage + - usage_percentage + - remaining + - remaining_percentage + type: string + description: Whether the threshold is an absolute count or a percentage of the + usage allowance or remaining balance. + name: + type: string + description: Optional user-defined label to distinguish multiple alerts on the + same feature. + required: + - threshold + - threshold_type + description: List of usage alert configurations per feature. + overage_allowed: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this overage allowed control applies to. + enabled: + type: boolean + default: false + description: Whether overage is allowed for this feature. + required: + - feature_id + description: List of overage allowed controls per feature. When enabled, usage + can exceed balance. + description: Billing controls for the customer (auto top-ups, etc.) + subscriptions: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier of this subscription. If a subscription_id + was provided at attach time, it is used; otherwise, + falls back to the internal ID. + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the subscribed plan. + auto_enable: + type: boolean + description: Whether the plan was automatically enabled for the customer. + add_on: + type: boolean + description: Whether this is an add-on plan rather than a base subscription. + status: + enum: + - active + - scheduled + type: string + description: Current status of the subscription. + past_due: + type: boolean + description: Whether the subscription has overdue payments. + canceled_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription was canceled, or null if not + canceled. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription will expire, or null if no expiry + set. + trial_ends_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the trial period ends, or null if not on trial. + started_at: + type: number + description: Timestamp when the subscription started. + current_period_start: + anyOf: + - type: number + - type: "null" + description: Start timestamp of the current billing period. + current_period_end: + anyOf: + - type: number + - type: "null" + description: End timestamp of the current billing period. + quantity: + type: number + description: Number of units of this subscription (for per-seat plans). + required: + - id + - plan_id + - auto_enable + - add_on + - status + - past_due + - canceled_at + - expires_at + - trial_ends_at + - started_at + - current_period_start + - current_period_end + - quantity + description: Active and scheduled recurring plans that this customer has + attached. + purchases: + type: array + items: + type: object + properties: + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the purchased plan. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the purchase expires, or null for lifetime access. + started_at: + type: number + description: Timestamp when the purchase was made. + quantity: + type: number + description: Number of units purchased. + required: + - plan_id + - expires_at + - started_at + - quantity + description: One-time purchases made by the customer. + balances: + type: object + propertyNames: + type: string + additionalProperties: + $ref: "#/components/schemas/Balance" + description: Feature balances keyed by feature ID, showing usage limits and + remaining amounts. + flags: + type: object + propertyNames: + type: string + additionalProperties: + type: object + properties: + id: + type: string + description: The unique identifier for this flag. + plan_id: + anyOf: + - type: string + - type: "null" + description: The plan ID this flag originates from, or null for standalone + flags. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when this flag expires, or null for no expiration. + feature_id: + type: string + description: The feature ID this flag is for. + feature: + type: object + properties: + id: + type: string + description: The unique identifier for this feature, used in /check and /track + calls. + name: + type: string + description: Human-readable name displayed in the dashboard and billing UI. + type: + enum: + - boolean + - metered + - credit_system + type: string + description: "Feature type: 'boolean' for on/off access, 'metered' for + usage-tracked features, 'credit_system' for + unified credit pools." + consumable: + type: boolean + description: "For metered features: true if usage resets periodically (API + calls, credits), false if allocated persistently + (seats, storage)." + event_names: + type: array + items: + type: string + description: Event names that trigger this feature's balance. Allows multiple + features to respond to a single event. + credit_schema: + type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: ID of the metered feature that draws from this credit system. + credit_cost: + type: number + description: Credits consumed per unit of the metered feature. + required: + - metered_feature_id + - credit_cost + description: "For credit_system features: maps metered features to their credit + costs." + display: + type: object + properties: + singular: + anyOf: + - type: string + - type: "null" + description: Singular form for UI display (e.g., 'API call', 'seat'). + plural: + anyOf: + - type: string + - type: "null" + description: Plural form for UI display (e.g., 'API calls', 'seats'). + description: Display names for the feature in billing UI and customer-facing + components. + archived: + type: boolean + description: Whether the feature is archived and hidden from the dashboard. + required: + - id + - name + - type + - consumable + - archived + description: The full feature object if expanded. + required: + - id + - plan_id + - expires_at + - feature_id + examples: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + expires_at: null + feature_id: dashboard + description: Boolean feature flags keyed by feature ID, showing enabled access + for on/off features. + config: + type: object + properties: + disable_pooled_balance: + type: boolean + description: Whether to disable the shared customer-level pool for entities. + description: Configuration for the customer. + 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 customer. + entities: + type: array + items: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: The unique identifier of the entity + name: + anyOf: + - type: string + - type: "null" + description: The name of the entity + customer_id: + anyOf: + - type: string + - type: "null" + description: The customer ID this entity belongs to + feature_id: + anyOf: + - type: string + - type: "null" + description: The feature ID this entity belongs to + created_at: + type: number + description: Unix timestamp when the entity was created + env: + enum: + - sandbox + - live + type: string + description: The environment (sandbox/live) + required: + - id + - name + - created_at + - env + description: Entities associated with this customer. + trials_used: + type: array + items: + type: object + properties: + plan_id: + type: string + customer_id: + type: string + fingerprint: + anyOf: + - type: string + - type: "null" + required: + - plan_id + - customer_id + description: Trial usage history for this customer. + rewards: + anyOf: + - type: object + properties: + discounts: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier for this discount + name: + type: string + description: The name of the discount or coupon + type: + enum: + - percentage_discount + - fixed_discount + - free_product + - invoice_credits + type: string + description: The type of reward + discount_value: + type: number + description: The discount value (percentage or fixed amount) + duration_type: + enum: + - one_off + - months + - forever + type: string + description: How long the discount lasts + duration_value: + anyOf: + - type: number + - type: "null" + description: Number of billing periods the discount applies for repeating + durations + currency: + anyOf: + - type: string + - type: "null" + description: The currency code for fixed amount discounts + start: + anyOf: + - type: number + - type: "null" + description: Timestamp when the discount becomes active + end: + anyOf: + - type: number + - type: "null" + description: Timestamp when the discount expires + subscription_id: + anyOf: + - type: string + - type: "null" + description: The Stripe subscription ID this discount is applied to + total_discount_amount: + anyOf: + - type: number + - type: "null" + description: Total amount saved from this discount + required: + - id + - name + - type + - discount_value + - duration_type + description: Array of active discounts applied to the customer + required: + - discounts + - type: "null" + description: Rewards earned or applied for this customer. + referrals: + type: array + items: + type: object + properties: + program_id: + type: string + customer: + type: object + properties: + id: + type: string + name: + anyOf: + - type: string + - type: "null" + email: + anyOf: + - type: string + - type: "null" + required: + - id + reward_applied: + type: boolean + created_at: + type: number + required: + - program_id + - customer + - reward_applied + - created_at + description: Referral records for this customer. + payment_method: + anyOf: + - {} + - type: "null" + description: The customer's default payment method. + required: + - id + - name + - email + - created_at + - fingerprint + - stripe_id + - env + - metadata + - send_email_receipts + - billing_controls + - subscriptions + - purchases + - balances + - flags + examples: + - &a4 + id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 + name: Patrick + email: patrick@useautumn.com + createdAt: 1771409161016 + fingerprint: null + stripeId: cus_U0BKxpq1mFhuJO + env: sandbox + metadata: {} + sendEmailReceipts: false + billingControls: + autoTopups: [] + subscriptions: + - planId: pro_plan + autoEnable: true + addOn: false + status: active + pastDue: false + canceledAt: null + expiresAt: null + trialEndsAt: null + startedAt: 1771431921437 + currentPeriodStart: 1771431921437 + currentPeriodEnd: 1771999921437 + quantity: 1 + purchases: [] + balances: + messages: + featureId: messages + granted: 100 + remaining: 0 + usage: 100 + unlimited: false + overageAllowed: false + maxPurchase: null + nextResetAt: 1773851121437 + breakdown: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + planId: pro_plan + includedGrant: 100 + prepaidGrant: 0 + remaining: 0 + usage: 100 + unlimited: false + reset: + interval: month + resetsAt: 1773851121437 + price: null + expiresAt: null + flags: + advanced_workflows: + id: cus_ent_abc123 + plan_id: pro_plan + expires_at: null + feature_id: advanced_workflows + config: + disable_pooled_balance: false + example: *a4 + x-speakeasy-name-override: get + parameters: + - *a5 /v1/customers.list: post: operationId: listCustomers @@ -1882,10 +2658,10 @@ paths: description: Filter by customer processor type (stripe, revenuecat, vercel) title: ListCustomersParams examples: - - &a3 + - &a6 limit: 10 offset: 0 - example: *a3 + example: *a6 responses: "200": description: OK @@ -2447,7 +3223,7 @@ paths: - total_count - total_filtered_count examples: - - &a4 + - &a7 list: - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick @@ -2511,7 +3287,7 @@ paths: limit: 10 total_count: 100 total_filtered_count: 42 - example: *a4 + example: *a7 x-speakeasy-name-override: list parameters: - *a5 @@ -2706,11 +3482,11 @@ paths: - customer_id title: UpdateCustomerParams examples: - - &a6 + - &a8 customer_id: cus_123 name: Jane Doe email: jane@example.com - example: *a6 + example: *a8 responses: "200": description: OK @@ -3178,7 +3954,7 @@ paths: - balances - flags examples: - - &a7 + - &a9 id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 name: Patrick email: patrick@useautumn.com @@ -3235,7 +4011,7 @@ paths: feature_id: advanced_workflows config: disable_pooled_balance: false - example: *a7 + example: *a9 x-speakeasy-name-override: update parameters: - *a5 @@ -3264,10 +4040,10 @@ paths: - customer_id title: DeleteCustomerParams examples: - - &a8 + - &a10 customer_id: cus_123 delete_in_stripe: false - example: *a8 + example: *a10 responses: "200": description: OK @@ -3552,7 +4328,7 @@ paths: - name title: CreatePlanParams examples: - - &a9 + - &a11 plan_id: free_plan name: Free auto_enable: true @@ -3589,489 +4365,6 @@ paths: interval: month billing_units: 1 billing_method: prepaid - example: *a9 - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - id: - type: string - description: Unique identifier for the plan. - name: - type: string - description: Display name of the plan. - description: - anyOf: - - type: string - - type: "null" - description: Optional description of the plan. - group: - anyOf: - - type: string - - type: "null" - description: Group identifier for organizing related plans. Plans in the same - group are mutually exclusive. - version: - type: number - description: Version number of the plan. Incremented when plan configuration - changes. - add_on: - type: boolean - description: Whether this is an add-on plan that can be attached alongside a - main plan. - auto_enable: - type: boolean - description: If true, this plan is automatically attached when a customer is - created. Used for free plans. - price: - anyOf: - - type: object - properties: - amount: - type: number - description: Base price amount for the plan. - interval: - enum: - - one_off - - week - - month - - quarter - - semi_annual - - year - type: string - description: Billing interval (e.g. 'month', 'year'). - interval_count: - type: number - description: Number of intervals per billing cycle. Defaults to 1. - display: - type: object - properties: - primary_text: - type: string - description: Main display text (e.g. '$10' or '100 messages'). - secondary_text: - type: string - description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - required: - - primary_text - description: Display text for showing this price in pricing pages. - required: - - amount - - interval - - type: "null" - description: Base recurring price for the plan. Null for free plans or - usage-only plans. - items: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The ID of the feature this item configures. - feature: - type: object - properties: - id: - type: string - description: The ID of the feature, used to refer to it in other API calls like - /track or /check. - name: - anyOf: - - type: string - - type: "null" - description: The name of the feature. - type: - enum: - - static - - boolean - - single_use - - continuous_use - - credit_system - type: string - description: The type of the feature - display: - anyOf: - - type: object - properties: - singular: - type: string - description: The singular display name for the feature. - plural: - type: string - description: The plural display name for the feature. - required: - - singular - - plural - - type: "null" - description: Singular and plural display names for the feature. - credit_schema: - anyOf: - - type: array - items: - type: object - properties: - metered_feature_id: - type: string - description: The ID of the metered feature (should be a single_use feature). - credit_cost: - type: number - description: The credit cost of the metered feature. - required: - - metered_feature_id - - credit_cost - - type: "null" - description: Credit cost schema for credit system features. - archived: - anyOf: - - type: boolean - - type: "null" - description: Whether or not the feature is archived. - required: - - id - - type - description: The full feature object if expanded. - included: - type: number - description: Number of free units included. For consumable features, balance - resets to this number each interval. - unlimited: - type: boolean - description: Whether the customer has unlimited access to this feature. - reset: - anyOf: - - type: object - properties: - interval: - enum: - - one_off - - minute - - hour - - day - - week - - month - - quarter - - semi_annual - - year - type: string - description: The interval at which the feature balance resets (e.g. 'month', - 'year'). For consumable features, usage - resets to 0 and included units are restored. - interval_count: - type: number - description: Number of intervals between resets. Defaults to 1. - required: - - interval - - type: "null" - description: Reset configuration for consumable features. Null for - non-consumable features like seats where usage - persists across billing cycles. - price: - anyOf: - - type: object - properties: - amount: - type: number - description: Price per billing_units after included usage is consumed. Mutually - exclusive with tiers. - tiers: - type: array - items: - anyOf: - - {} - - type: "null" - description: Tiered pricing configuration. Each tier's 'to' INCLUDES the - included amount. Either 'tiers' or 'amount' - is required. - tier_behavior: - enum: - - graduated - - volume - type: string - interval: - enum: - - one_off - - week - - month - - quarter - - semi_annual - - year - type: string - description: Billing interval for this price. For consumable features, should - match reset.interval. - interval_count: - type: number - description: Number of intervals per billing cycle. Defaults to 1. - billing_units: - type: number - description: Number of units per price increment. Usage is rounded UP to the - nearest billing_units when billed (e.g. - billing_units=100 means 101 usage rounds to - 200). - billing_method: - enum: - - prepaid - - usage_based - type: string - description: "'prepaid' for features like seats where customers pay upfront, - 'usage_based' for pay-as-you-go after - included usage." - max_purchase: - anyOf: - - type: number - - type: "null" - description: Maximum units a customer can purchase beyond included. E.g. if - included=100 and max_purchase=300, customer - can use up to 400 total before usage is - capped. Null for no limit. - required: - - interval - - billing_units - - billing_method - - max_purchase - - type: "null" - description: Pricing configuration for usage beyond included units. Null if - feature is entirely free. - display: - type: object - properties: - primary_text: - type: string - description: Main display text (e.g. '$10' or '100 messages'). - secondary_text: - type: string - description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). - required: - - primary_text - description: Display text for showing this item in pricing pages. - rollover: - type: object - properties: - max: - anyOf: - - type: number - - type: "null" - description: Maximum rollover units. Null for unlimited rollover. - max_percentage: - anyOf: - - type: number - - type: "null" - description: Maximum rollover as a percentage (0-100) of included + prepaid - grant. Mutually exclusive with max. - expiry_duration_type: - enum: - - month - - forever - type: string - description: When rolled over units expire. - expiry_duration_length: - type: number - description: Number of periods before expiry. - required: - - max - - expiry_duration_type - description: Rollover configuration for unused units. If set, unused included - units roll over to the next period. - required: - - feature_id - - included - - unlimited - - reset - - price - description: Feature configurations included in this plan. Each item defines - included units, pricing, and reset behavior for a feature. - free_trial: - type: object - properties: - duration_length: - type: number - description: Number of duration_type periods the trial lasts. - duration_type: - enum: - - day - - month - - year - type: string - description: Unit of time for the trial duration ('day', 'month', 'year'). - card_required: - type: boolean - description: Whether a payment method is required to start the trial. If true, - customer will be charged after trial ends. - required: - - duration_length - - duration_type - - card_required - description: Free trial configuration. If set, new customers can try this plan - before being charged. - created_at: - type: number - description: Unix timestamp (ms) when the plan was created. - env: - enum: - - sandbox - - live - type: string - description: Environment this plan belongs to ('sandbox' or 'live'). - archived: - type: boolean - description: Whether the plan is archived. Archived plans cannot be attached to - new customers. - base_variant_id: - anyOf: - - type: string - - type: "null" - description: If this is a variant, the ID of the base plan it was created from. - config: - type: object - properties: - ignore_past_due: - type: boolean - default: false - description: If true, entitlements attached to this plan will still reset on - schedule even when the customer's product is in a - past_due state. - description: Miscellaneous plan-level configuration flags. - customer_eligibility: - type: object - properties: - trial_available: - type: boolean - description: Whether the trial on this plan is available to this customer. For - example, if the customer used the trial in the past, - this will be false. - status: - enum: - - active - - scheduled - type: string - description: The customer's current status with this plan. 'active' if attached, - 'scheduled' if pending activation. - canceling: - type: boolean - description: Whether the customer's active instance of this plan is set to - cancel. - trialing: - type: boolean - description: Whether the customer is currently on a free trial of this plan. - attach_action: - enum: - - activate - - upgrade - - downgrade - - none - - purchase - type: string - description: The action that would occur if this plan were attached to the - customer. - required: - - attach_action - required: - - id - - name - - description - - group - - version - - add_on - - auto_enable - - price - - items - - created_at - - env - - archived - - base_variant_id - - config - description: A plan defines a set of features, pricing, and entitlements that - can be attached to customers. - examples: - - &a10 - id: pro - name: Pro Plan - description: null - group: null - version: 1 - addOn: false - autoEnable: false - price: - amount: 10 - interval: month - display: - primaryText: $10 - secondaryText: per month - items: - - featureId: messages - included: 100 - unlimited: false - reset: - interval: month - price: - amount: 0.5 - interval: month - billingUnits: 100 - billingMethod: usage_based - maxPurchase: null - display: - primaryText: 100 messages - secondaryText: then $0.5 per 100 messages - - featureId: users - included: 0 - unlimited: false - reset: null - price: - amount: 10 - interval: month - billingUnits: 1 - billingMethod: prepaid - maxPurchase: null - display: - primaryText: $10 per Users - createdAt: 1771513979217 - env: sandbox - archived: false - baseVariantId: null - config: - ignore_past_due: false - example: *a10 - x-speakeasy-name-override: create - parameters: - - *a5 - /v1/plans.get: - post: - operationId: getPlan - summary: Get a plan - description: >- - Retrieves a single plan by its ID. - - - Use this to fetch the full configuration of a specific plan, including - its features and pricing. - tags: - - plans - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - plan_id: - type: string - minLength: 1 - description: The ID of the plan to retrieve. - version: - type: number - description: The version of the plan to get. Defaults to the latest version. - required: - - plan_id - title: GetPlanParams - examples: - - &a11 - plan_id: pro_plan - - plan_id: pro_plan - version: 2 example: *a11 responses: "200": @@ -4518,6 +4811,489 @@ paths: config: ignore_past_due: false example: *a12 + x-speakeasy-name-override: create + parameters: + - *a5 + /v1/plans.get: + post: + operationId: getPlan + summary: Get a plan + description: >- + Retrieves a single plan by its ID. + + + Use this to fetch the full configuration of a specific plan, including + its features and pricing. + tags: + - plans + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + plan_id: + type: string + minLength: 1 + description: The ID of the plan to retrieve. + version: + type: number + description: The version of the plan to get. Defaults to the latest version. + required: + - plan_id + title: GetPlanParams + examples: + - &a13 + plan_id: pro_plan + - plan_id: pro_plan + version: 2 + example: *a13 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: Unique identifier for the plan. + name: + type: string + description: Display name of the plan. + description: + anyOf: + - type: string + - type: "null" + description: Optional description of the plan. + group: + anyOf: + - type: string + - type: "null" + description: Group identifier for organizing related plans. Plans in the same + group are mutually exclusive. + version: + type: number + description: Version number of the plan. Incremented when plan configuration + changes. + add_on: + type: boolean + description: Whether this is an add-on plan that can be attached alongside a + main plan. + auto_enable: + type: boolean + description: If true, this plan is automatically attached when a customer is + created. Used for free plans. + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Base price amount for the plan. + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval (e.g. 'month', 'year'). + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + display: + type: object + properties: + primary_text: + type: string + description: Main display text (e.g. '$10' or '100 messages'). + secondary_text: + type: string + description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). + required: + - primary_text + description: Display text for showing this price in pricing pages. + required: + - amount + - interval + - type: "null" + description: Base recurring price for the plan. Null for free plans or + usage-only plans. + items: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature this item configures. + feature: + type: object + properties: + id: + type: string + description: The ID of the feature, used to refer to it in other API calls like + /track or /check. + name: + anyOf: + - type: string + - type: "null" + description: The name of the feature. + type: + enum: + - static + - boolean + - single_use + - continuous_use + - credit_system + type: string + description: The type of the feature + display: + anyOf: + - type: object + properties: + singular: + type: string + description: The singular display name for the feature. + plural: + type: string + description: The plural display name for the feature. + required: + - singular + - plural + - type: "null" + description: Singular and plural display names for the feature. + credit_schema: + anyOf: + - type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: The ID of the metered feature (should be a single_use feature). + credit_cost: + type: number + description: The credit cost of the metered feature. + required: + - metered_feature_id + - credit_cost + - type: "null" + description: Credit cost schema for credit system features. + archived: + anyOf: + - type: boolean + - type: "null" + description: Whether or not the feature is archived. + required: + - id + - type + description: The full feature object if expanded. + included: + type: number + description: Number of free units included. For consumable features, balance + resets to this number each interval. + unlimited: + type: boolean + description: Whether the customer has unlimited access to this feature. + reset: + anyOf: + - type: object + properties: + interval: + enum: + - one_off + - minute + - hour + - day + - week + - month + - quarter + - semi_annual + - year + type: string + description: The interval at which the feature balance resets (e.g. 'month', + 'year'). For consumable features, usage + resets to 0 and included units are restored. + interval_count: + type: number + description: Number of intervals between resets. Defaults to 1. + required: + - interval + - type: "null" + description: Reset configuration for consumable features. Null for + non-consumable features like seats where usage + persists across billing cycles. + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Price per billing_units after included usage is consumed. Mutually + exclusive with tiers. + tiers: + type: array + items: + anyOf: + - {} + - type: "null" + description: Tiered pricing configuration. Each tier's 'to' INCLUDES the + included amount. Either 'tiers' or 'amount' + is required. + tier_behavior: + enum: + - graduated + - volume + type: string + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval for this price. For consumable features, should + match reset.interval. + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + billing_units: + type: number + description: Number of units per price increment. Usage is rounded UP to the + nearest billing_units when billed (e.g. + billing_units=100 means 101 usage rounds to + 200). + billing_method: + enum: + - prepaid + - usage_based + type: string + description: "'prepaid' for features like seats where customers pay upfront, + 'usage_based' for pay-as-you-go after + included usage." + max_purchase: + anyOf: + - type: number + - type: "null" + description: Maximum units a customer can purchase beyond included. E.g. if + included=100 and max_purchase=300, customer + can use up to 400 total before usage is + capped. Null for no limit. + required: + - interval + - billing_units + - billing_method + - max_purchase + - type: "null" + description: Pricing configuration for usage beyond included units. Null if + feature is entirely free. + display: + type: object + properties: + primary_text: + type: string + description: Main display text (e.g. '$10' or '100 messages'). + secondary_text: + type: string + description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100'). + required: + - primary_text + description: Display text for showing this item in pricing pages. + rollover: + type: object + properties: + max: + anyOf: + - type: number + - type: "null" + description: Maximum rollover units. Null for unlimited rollover. + max_percentage: + anyOf: + - type: number + - type: "null" + description: Maximum rollover as a percentage (0-100) of included + prepaid + grant. Mutually exclusive with max. + expiry_duration_type: + enum: + - month + - forever + type: string + description: When rolled over units expire. + expiry_duration_length: + type: number + description: Number of periods before expiry. + required: + - max + - expiry_duration_type + description: Rollover configuration for unused units. If set, unused included + units roll over to the next period. + required: + - feature_id + - included + - unlimited + - reset + - price + description: Feature configurations included in this plan. Each item defines + included units, pricing, and reset behavior for a feature. + free_trial: + type: object + properties: + duration_length: + type: number + description: Number of duration_type periods the trial lasts. + duration_type: + enum: + - day + - month + - year + type: string + description: Unit of time for the trial duration ('day', 'month', 'year'). + card_required: + type: boolean + description: Whether a payment method is required to start the trial. If true, + customer will be charged after trial ends. + required: + - duration_length + - duration_type + - card_required + description: Free trial configuration. If set, new customers can try this plan + before being charged. + created_at: + type: number + description: Unix timestamp (ms) when the plan was created. + env: + enum: + - sandbox + - live + type: string + description: Environment this plan belongs to ('sandbox' or 'live'). + archived: + type: boolean + description: Whether the plan is archived. Archived plans cannot be attached to + new customers. + base_variant_id: + anyOf: + - type: string + - type: "null" + description: If this is a variant, the ID of the base plan it was created from. + config: + type: object + properties: + ignore_past_due: + type: boolean + default: false + description: If true, entitlements attached to this plan will still reset on + schedule even when the customer's product is in a + past_due state. + description: Miscellaneous plan-level configuration flags. + customer_eligibility: + type: object + properties: + trial_available: + type: boolean + description: Whether the trial on this plan is available to this customer. For + example, if the customer used the trial in the past, + this will be false. + status: + enum: + - active + - scheduled + type: string + description: The customer's current status with this plan. 'active' if attached, + 'scheduled' if pending activation. + canceling: + type: boolean + description: Whether the customer's active instance of this plan is set to + cancel. + trialing: + type: boolean + description: Whether the customer is currently on a free trial of this plan. + attach_action: + enum: + - activate + - upgrade + - downgrade + - none + - purchase + type: string + description: The action that would occur if this plan were attached to the + customer. + required: + - attach_action + required: + - id + - name + - description + - group + - version + - add_on + - auto_enable + - price + - items + - created_at + - env + - archived + - base_variant_id + - config + description: A plan defines a set of features, pricing, and entitlements that + can be attached to customers. + examples: + - &a14 + id: pro + name: Pro Plan + description: null + group: null + version: 1 + addOn: false + autoEnable: false + price: + amount: 10 + interval: month + display: + primaryText: $10 + secondaryText: per month + items: + - featureId: messages + included: 100 + unlimited: false + reset: + interval: month + price: + amount: 0.5 + interval: month + billingUnits: 100 + billingMethod: usage_based + maxPurchase: null + display: + primaryText: 100 messages + secondaryText: then $0.5 per 100 messages + - featureId: users + included: 0 + unlimited: false + reset: null + price: + amount: 10 + interval: month + billingUnits: 1 + billingMethod: prepaid + maxPurchase: null + display: + primaryText: $10 per Users + createdAt: 1771513979217 + env: sandbox + archived: false + baseVariantId: null + config: + ignore_past_due: false + example: *a14 x-speakeasy-name-override: get parameters: - *a5 @@ -4552,10 +5328,10 @@ paths: description: If true, includes archived plans in the response. title: ListPlansParams examples: - - &a13 {} + - &a15 {} - customer_id: cus_123 - include_archived: true - example: *a13 + example: *a15 responses: "200": description: OK @@ -4963,7 +5739,7 @@ paths: required: - list examples: - - &a14 + - &a16 list: - id: pro name: Pro Plan @@ -5011,7 +5787,7 @@ paths: baseVariantId: null config: ignore_past_due: false - example: *a14 + example: *a16 x-speakeasy-name-override: list parameters: - *a5 @@ -5293,7 +6069,7 @@ paths: - plan_id title: UpdatePlanParams examples: - - &a15 + - &a17 plan_id: pro_plan name: Pro Plan (Updated) price: @@ -5303,7 +6079,7 @@ paths: price: null - plan_id: old_plan archived: true - example: *a15 + example: *a17 responses: "200": description: OK @@ -5701,7 +6477,7 @@ paths: description: A plan defines a set of features, pricing, and entitlements that can be attached to customers. examples: - - &a16 + - &a18 id: pro name: Pro Plan description: null @@ -5748,7 +6524,7 @@ paths: baseVariantId: null config: ignore_past_due: false - example: *a16 + example: *a18 x-speakeasy-name-override: update parameters: - *a5 @@ -5784,11 +6560,11 @@ paths: - plan_id title: DeletePlanParams examples: - - &a17 + - &a19 plan_id: unused_plan - plan_id: legacy_plan all_versions: true - example: *a17 + example: *a19 responses: "200": description: OK @@ -5881,7 +6657,7 @@ paths: - feature_id title: CreateFeatureParams examples: - - &a18 + - &a20 feature_id: api-calls name: API Calls type: metered @@ -5895,121 +6671,6 @@ paths: credit_cost: 1 - metered_feature_id: image-generations credit_cost: 10 - example: *a18 - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - id: - type: string - description: The unique identifier for this feature, used in /check and /track - calls. - name: - type: string - description: Human-readable name displayed in the dashboard and billing UI. - type: - enum: - - boolean - - metered - - credit_system - type: string - description: "Feature type: 'boolean' for on/off access, 'metered' for - usage-tracked features, 'credit_system' for unified credit - pools." - consumable: - type: boolean - description: "For metered features: true if usage resets periodically (API - calls, credits), false if allocated persistently (seats, - storage)." - event_names: - type: array - items: - type: string - description: Event names that trigger this feature's balance. Allows multiple - features to respond to a single event. - credit_schema: - type: array - items: - type: object - properties: - metered_feature_id: - type: string - description: ID of the metered feature that draws from this credit system. - credit_cost: - type: number - description: Credits consumed per unit of the metered feature. - required: - - metered_feature_id - - credit_cost - description: "For credit_system features: maps metered features to their credit - costs." - display: - type: object - properties: - singular: - anyOf: - - type: string - - type: "null" - description: Singular form for UI display (e.g., 'API call', 'seat'). - plural: - anyOf: - - type: string - - type: "null" - description: Plural form for UI display (e.g., 'API calls', 'seats'). - description: Display names for the feature in billing UI and customer-facing - components. - archived: - type: boolean - description: Whether the feature is archived and hidden from the dashboard. - required: - - id - - name - - type - - consumable - - archived - examples: - - &a19 - id: api-calls - name: API Calls - type: metered - consumable: true - archived: false - display: - singular: API call - plural: API calls - example: *a19 - x-speakeasy-name-override: create - parameters: - - *a5 - /v1/features.get: - post: - operationId: getFeature - description: |- - Retrieves a single feature by its ID. - - Use this when you need to fetch the details of a specific feature. - tags: - - features - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - feature_id: - type: string - description: The ID of the feature. - required: - - feature_id - title: GetFeatureParams - examples: - - &a20 - feature_id: api-calls example: *a20 responses: "200": @@ -6097,6 +6758,121 @@ paths: singular: API call plural: API calls example: *a21 + x-speakeasy-name-override: create + parameters: + - *a5 + /v1/features.get: + post: + operationId: getFeature + description: |- + Retrieves a single feature by its ID. + + Use this when you need to fetch the details of a specific feature. + tags: + - features + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + feature_id: + type: string + description: The ID of the feature. + required: + - feature_id + title: GetFeatureParams + examples: + - &a22 + feature_id: api-calls + example: *a22 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: The unique identifier for this feature, used in /check and /track + calls. + name: + type: string + description: Human-readable name displayed in the dashboard and billing UI. + type: + enum: + - boolean + - metered + - credit_system + type: string + description: "Feature type: 'boolean' for on/off access, 'metered' for + usage-tracked features, 'credit_system' for unified credit + pools." + consumable: + type: boolean + description: "For metered features: true if usage resets periodically (API + calls, credits), false if allocated persistently (seats, + storage)." + event_names: + type: array + items: + type: string + description: Event names that trigger this feature's balance. Allows multiple + features to respond to a single event. + credit_schema: + type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: ID of the metered feature that draws from this credit system. + credit_cost: + type: number + description: Credits consumed per unit of the metered feature. + required: + - metered_feature_id + - credit_cost + description: "For credit_system features: maps metered features to their credit + costs." + display: + type: object + properties: + singular: + anyOf: + - type: string + - type: "null" + description: Singular form for UI display (e.g., 'API call', 'seat'). + plural: + anyOf: + - type: string + - type: "null" + description: Plural form for UI display (e.g., 'API calls', 'seats'). + description: Display names for the feature in billing UI and customer-facing + components. + archived: + type: boolean + description: Whether the feature is archived and hidden from the dashboard. + required: + - id + - name + - type + - consumable + - archived + examples: + - &a23 + id: api-calls + name: API Calls + type: metered + consumable: true + archived: false + display: + singular: API call + plural: API calls + example: *a23 x-speakeasy-name-override: get parameters: - *a5 @@ -6194,7 +6970,7 @@ paths: required: - list examples: - - &a22 + - &a24 list: - id: api-calls name: API Calls @@ -6217,7 +6993,7 @@ paths: display: singular: credit plural: credits - example: *a22 + example: *a24 x-speakeasy-name-override: list parameters: - *a5 @@ -6305,7 +7081,7 @@ paths: - feature_id title: UpdateFeatureParams examples: - - &a23 + - &a25 feature_id: api-calls name: API Requests display: @@ -6313,7 +7089,7 @@ paths: plural: API requests - feature_id: old-feature archived: true - example: *a23 + example: *a25 responses: "200": description: OK @@ -6390,7 +7166,7 @@ paths: - consumable - archived examples: - - &a24 + - &a26 id: api-calls name: API Calls type: metered @@ -6399,7 +7175,7 @@ paths: display: singular: API call plural: API calls - example: *a24 + example: *a26 x-speakeasy-name-override: update parameters: - *a5 @@ -6428,9 +7204,9 @@ paths: - feature_id title: DeleteFeatureParams examples: - - &a25 + - &a27 feature_id: old-feature - example: *a25 + example: *a27 responses: "200": description: OK @@ -6444,9 +7220,9 @@ paths: required: - success examples: - - &a26 + - &a28 success: true - example: *a26 + example: *a28 x-speakeasy-name-override: delete parameters: - *a5 @@ -6801,6 +7577,12 @@ paths: 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -6883,10 +7665,10 @@ paths: - plan_id title: AttachParams examples: - - &a27 + - &a29 customer_id: cus_123 plan_id: pro_plan - example: *a27 + example: *a29 responses: "200": description: OK @@ -6960,13 +7742,718 @@ paths: - customer_id - payment_url examples: - - &a28 + - &a30 customer_id: cus_123 payment_url: https://checkout.stripe.com/... - example: *a28 + example: *a30 x-speakeasy-name-override: attach parameters: - *a5 + /v1/billing.create_schedule: + post: + operationId: createSchedule + description: >- + Creates a multi-phase subscription schedule for a customer. The first + phase starts immediately and subsequent phases automatically transition + at their scheduled start times. + + + Use this endpoint to schedule future plan changes (e.g. switch from a + trial plan to a paid plan on a specific date) or to define a sequence of + plans that should activate over time. + tags: + - billing + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer to create the schedule for. + entity_id: + type: string + description: Optional entity ID for an entity-scoped schedule. + invoice_mode: + type: object + properties: + enabled: + type: boolean + description: When true, creates an invoice and sends it to the customer instead + of charging their card immediately. Uses Stripe's + send_invoice collection method. + enable_plan_immediately: + type: boolean + default: false + description: If true, enables the plan immediately even though the invoice is + not paid yet. + finalize: + type: boolean + default: true + description: If true, finalizes the invoice so it can be sent to the customer. + If false, keeps it as a draft for manual review. + required: + - enabled + description: Invoice mode creates and sends an invoice instead of charging the + customer's payment method immediately for the first phase. + success_url: + type: string + description: URL to redirect to after successful checkout. + checkout_session_params: + type: object + propertyNames: + type: string + additionalProperties: {} + description: Additional parameters to pass into the creation of the Stripe + checkout session. + redirect_mode: + enum: + - always + - if_required + - never + type: string + description: Controls when to return a checkout URL for the immediate phase. + 'always' forces a confirmation or checkout flow, + 'if_required' only redirects when needed, and 'never' + disables redirects. + default: if_required + billing_behavior: + enum: + - prorate_immediately + - none + type: string + description: Whether to prorate the immediate phase. 'none' skips proration + charges and credits. + billing_cycle_anchor: + const: now + description: Pass 'now' to reset the billing cycle anchor of the immediate phase + to the current time. + enable_plan_immediately: + type: boolean + description: If true, the immediate-phase cusProducts are activated immediately + (and scheduled-phase cusProducts pre-inserted) even when + payment is pending via Stripe checkout. The Autumn schedule + rows are persisted on checkout.session.completed. + phases: + type: array + prefixItems: + - type: object + properties: + starts_at: + type: number + description: When this phase should start, in epoch milliseconds. + plans: + type: array + minItems: 1 + items: + type: object + properties: + plan_id: + type: string + description: The ID of the plan to schedule in this phase. + feature_quantities: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to set quantity for. + quantity: + type: number + minimum: 0 + description: The quantity of the feature. + adjustable: + type: boolean + description: Whether the customer can adjust the quantity. + required: + - feature_id + title: FeatureQuantity + description: Quantity configuration for a prepaid feature. + description: Optional prepaid feature quantities for this phase's plan. + version: + type: number + description: Optional explicit plan version to schedule. + customize: + type: object + properties: + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Base price amount for the plan. + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval (e.g. 'month', 'year'). + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + required: + - amount + - interval + title: BasePrice + description: Base price configuration for a plan. + - type: "null" + description: Override the base price of the plan. Pass null to remove the base + price. + items: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to configure. + included: + type: number + description: Number of free units included. Balance resets to this each interval + for consumable features. + unlimited: + type: boolean + description: If true, customer has unlimited access to this feature. + reset: + type: object + properties: + interval: + enum: + - one_off + - minute + - hour + - day + - week + - month + - quarter + - semi_annual + - year + type: string + description: Interval at which balance resets (e.g. 'month', 'year'). For + consumable features only. + interval_count: + type: number + description: Number of intervals between resets. Defaults to 1. + required: + - interval + description: Reset configuration for consumable features. Omit for + non-consumable features like seats. + price: + type: object + properties: + amount: + type: number + description: Price per billing_units after included usage. Either 'amount' or + 'tiers' is required. + tiers: + type: array + items: + type: object + properties: + to: {} + amount: {} + flat_amount: {} + description: Tiered pricing. Either 'amount' or 'tiers' is required. + tier_behavior: + enum: + - graduated + - volume + type: string + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval. For consumable features, should match + reset.interval. + interval_count: + type: number + default: 1 + description: Number of intervals per billing cycle. Defaults to 1. + billing_units: + type: number + default: 1 + description: Units per price increment. Usage is rounded UP when billed (e.g. + billing_units=100 means 101 + rounds to 200). + billing_method: + enum: + - prepaid + - usage_based + type: string + description: "'prepaid' for upfront payment (seats), 'usage_based' for + pay-as-you-go." + max_purchase: + type: number + description: Max units purchasable beyond included. E.g. included=100, + max_purchase=300 allows 400 + total. + required: + - interval + - billing_method + description: Pricing for usage beyond included units. Omit for free features. + proration: + type: object + properties: + on_increase: + enum: + - bill_immediately + - prorate_immediately + - prorate_next_cycle + - bill_next_cycle + type: string + description: Billing behavior when quantity increases mid-cycle. + on_decrease: + enum: + - prorate + - prorate_immediately + - prorate_next_cycle + - none + - no_prorations + type: string + description: Credit behavior when quantity decreases mid-cycle. + required: + - on_increase + - on_decrease + description: Proration settings for prepaid features. Controls mid-cycle + quantity change billing. + rollover: + type: object + properties: + max: + type: number + description: Max rollover units. Omit for unlimited rollover. + max_percentage: + type: number + description: Maximum rollover as a percentage (0-100) of included + prepaid + grant. Mutually exclusive with + max. + expiry_duration_type: + enum: + - month + - forever + type: string + description: When rolled over units expire. + expiry_duration_length: + type: number + description: Number of periods before expiry. + required: + - expiry_duration_type + description: Rollover config for unused units. If set, unused included units + carry over. + required: + - feature_id + title: PlanItem + description: Configuration for a feature item in a plan, including usage limits, + pricing, and rollover settings. + description: Override the items in the plan. + additionalProperties: false + description: Customize the plan to schedule. Can override the price, items, or + both. + subscription_id: + type: string + description: Unsupported for create_schedule today. Requests that include this + field will be rejected. + required: + - plan_id + description: Plans to materialize for this phase. + required: + - starts_at + - plans + items: + type: object + properties: + starts_at: + type: number + description: When this phase should start, in epoch milliseconds. + plans: + type: array + minItems: 1 + items: + type: object + properties: + plan_id: + type: string + description: The ID of the plan to schedule in this phase. + feature_quantities: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to set quantity for. + quantity: + type: number + minimum: 0 + description: The quantity of the feature. + adjustable: + type: boolean + description: Whether the customer can adjust the quantity. + required: + - feature_id + title: FeatureQuantity + description: Quantity configuration for a prepaid feature. + description: Optional prepaid feature quantities for this phase's plan. + version: + type: number + description: Optional explicit plan version to schedule. + customize: + type: object + properties: + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Base price amount for the plan. + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval (e.g. 'month', 'year'). + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + required: + - amount + - interval + title: BasePrice + description: Base price configuration for a plan. + - type: "null" + description: Override the base price of the plan. Pass null to remove the base + price. + items: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to configure. + included: + type: number + description: Number of free units included. Balance resets to this each interval + for consumable features. + unlimited: + type: boolean + description: If true, customer has unlimited access to this feature. + reset: + type: object + properties: + interval: + enum: + - one_off + - minute + - hour + - day + - week + - month + - quarter + - semi_annual + - year + type: string + description: Interval at which balance resets (e.g. 'month', 'year'). For + consumable features only. + interval_count: + type: number + description: Number of intervals between resets. Defaults to 1. + required: + - interval + description: Reset configuration for consumable features. Omit for + non-consumable features like seats. + price: + type: object + properties: + amount: + type: number + description: Price per billing_units after included usage. Either 'amount' or + 'tiers' is required. + tiers: + type: array + items: + type: object + properties: + to: {} + amount: {} + flat_amount: {} + description: Tiered pricing. Either 'amount' or 'tiers' is required. + tier_behavior: + enum: + - graduated + - volume + type: string + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval. For consumable features, should match + reset.interval. + interval_count: + type: number + default: 1 + description: Number of intervals per billing cycle. Defaults to 1. + billing_units: + type: number + default: 1 + description: Units per price increment. Usage is rounded UP when billed (e.g. + billing_units=100 means 101 rounds + to 200). + billing_method: + enum: + - prepaid + - usage_based + type: string + description: "'prepaid' for upfront payment (seats), 'usage_based' for + pay-as-you-go." + max_purchase: + type: number + description: Max units purchasable beyond included. E.g. included=100, + max_purchase=300 allows 400 total. + required: + - interval + - billing_method + description: Pricing for usage beyond included units. Omit for free features. + proration: + type: object + properties: + on_increase: + enum: + - bill_immediately + - prorate_immediately + - prorate_next_cycle + - bill_next_cycle + type: string + description: Billing behavior when quantity increases mid-cycle. + on_decrease: + enum: + - prorate + - prorate_immediately + - prorate_next_cycle + - none + - no_prorations + type: string + description: Credit behavior when quantity decreases mid-cycle. + required: + - on_increase + - on_decrease + description: Proration settings for prepaid features. Controls mid-cycle + quantity change billing. + rollover: + type: object + properties: + max: + type: number + description: Max rollover units. Omit for unlimited rollover. + max_percentage: + type: number + description: Maximum rollover as a percentage (0-100) of included + prepaid + grant. Mutually exclusive with + max. + expiry_duration_type: + enum: + - month + - forever + type: string + description: When rolled over units expire. + expiry_duration_length: + type: number + description: Number of periods before expiry. + required: + - expiry_duration_type + description: Rollover config for unused units. If set, unused included units + carry over. + required: + - feature_id + title: PlanItem + description: Configuration for a feature item in a plan, including usage limits, + pricing, and rollover settings. + description: Override the items in the plan. + additionalProperties: false + description: Customize the plan to schedule. Can override the price, items, or + both. + subscription_id: + type: string + description: Unsupported for create_schedule today. Requests that include this + field will be rejected. + required: + - plan_id + description: Plans to materialize for this phase. + required: + - starts_at + - plans + description: Ordered phase definitions for the schedule. + required: + - customer_id + - phases + title: CreateScheduleParams + examples: + - &a31 + customer_id: cus_123 + phases: + - starts_at: 1735689600000 + plans: + - plan_id: trial_plan + - starts_at: 1736899200000 + plans: + - plan_id: pro_plan + example: *a31 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer. + entity_id: + anyOf: + - type: string + - type: "null" + description: The entity ID for the schedule, or null when customer-level. + status: + enum: + - created + - pending_payment + type: string + description: Whether the schedule is fully created or waiting for payment or + confirmation to complete. + schedule_id: + anyOf: + - type: string + - type: "null" + description: The ID of the created schedule. Null when the schedule is waiting + on Autumn checkout confirmation. + phases: + type: array + items: + type: object + properties: + phase_id: + type: string + description: The ID of the persisted phase row. + starts_at: + type: number + description: When this phase starts, in epoch milliseconds. + customer_product_ids: + type: array + items: + type: string + description: Customer products materialized for this phase. + required: + - phase_id + - starts_at + - customer_product_ids + description: Persisted phases in ascending starts_at order. Empty when waiting + on Autumn checkout confirmation. + invoice: + type: object + properties: + status: + anyOf: + - type: string + - type: "null" + description: The status of the invoice (e.g., 'paid', 'open', 'draft'). + stripe_id: + type: string + description: The Stripe invoice ID. + total: + type: number + description: The total amount of the invoice in cents. + currency: + type: string + description: The three-letter ISO currency code (e.g., 'usd'). + hosted_invoice_url: + anyOf: + - type: string + - type: "null" + description: URL to the hosted invoice page where the customer can view and pay + the invoice. + required: + - status + - stripe_id + - total + - currency + - hosted_invoice_url + description: Invoice details if an invoice was created. Only present when a + charge was made. + payment_url: + anyOf: + - type: string + - type: "null" + description: URL to redirect the customer to complete payment. Null if no + payment action is required. + required_action: + type: object + properties: + code: + enum: + - 3ds_required + - payment_method_required + - payment_failed + type: string + description: The type of action required to complete the payment. + reason: + type: string + description: A human-readable explanation of why this action is required. + required: + - code + - reason + required: + - customer_id + - entity_id + - status + - schedule_id + - phases + - payment_url + title: CreateScheduleResponse + examples: + - &a32 + customer_id: cus_123 + entity_id: null + status: created + schedule_id: sch_1234 + phases: + - phase_id: sphs_1111 + starts_at: 1735689600000 + customer_product_ids: + - cus_prod_1111 + - phase_id: sphs_2222 + starts_at: 1736899200000 + customer_product_ids: + - cus_prod_2222 + invoice: null + payment_url: null + example: *a32 + x-speakeasy-name-override: createSchedule + parameters: + - *a5 /v1/billing.multi_attach: post: operationId: multiAttach @@ -7406,7 +8893,7 @@ paths: - plans title: MultiAttachParams examples: - - &a29 + - &a33 customer_id: cus_123 plans: - plan_id: pro_plan @@ -7414,7 +8901,7 @@ paths: feature_quantities: - feature_id: seats quantity: 5 - example: *a29 + example: *a33 responses: "200": description: OK @@ -7488,7 +8975,7 @@ paths: - customer_id - payment_url examples: - - &a30 + - &a34 customer_id: cus_123 invoice: status: paid @@ -7497,7 +8984,7 @@ paths: currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null - example: *a30 + example: *a34 x-speakeasy-name-override: multiAttach parameters: - *a5 @@ -7852,6 +9339,12 @@ paths: 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -7934,10 +9427,10 @@ paths: - plan_id title: PreviewAttachParams examples: - - &a31 + - &a35 customer_id: cus_123 plan_id: pro_plan - example: *a31 + example: *a35 responses: "200": description: OK @@ -7964,10 +9457,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -8019,12 +9513,12 @@ paths: - quantity subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -8036,10 +9530,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -8055,10 +9551,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -8304,6 +9801,20 @@ paths: description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -8315,7 +9826,7 @@ paths: - redirect_to_checkout - checkout_type examples: - - &a32 + - &a36 customerId: charles lineItems: - display_name: Pro seed @@ -8326,7 +9837,7 @@ paths: subtotal: 20 total: 20 currency: usd - example: *a32 + example: *a36 x-speakeasy-name-override: previewAttach parameters: - *a5 @@ -8768,7 +10279,7 @@ paths: - plans title: PreviewMultiAttachParams examples: - - &a33 + - &a37 customer_id: cus_123 plans: - plan_id: pro_plan @@ -8776,7 +10287,7 @@ paths: feature_quantities: - feature_id: seats quantity: 5 - example: *a33 + example: *a37 responses: "200": description: OK @@ -8803,10 +10314,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -8858,12 +10370,12 @@ paths: - quantity subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -8875,10 +10387,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -8894,10 +10408,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -9143,6 +10658,20 @@ paths: description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -9154,7 +10683,7 @@ paths: - redirect_to_checkout - checkout_type examples: - - &a34 + - &a38 customerId: charles lineItems: - display_name: Pro seed @@ -9165,7 +10694,7 @@ paths: subtotal: 20 total: 20 currency: usd - example: *a34 + example: *a38 x-speakeasy-name-override: previewMultiAttach parameters: - *a5 @@ -9532,13 +11061,13 @@ paths: - customer_id title: UpdateSubscriptionParams examples: - - &a35 + - &a39 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 10 - example: *a35 + example: *a39 responses: "200": description: OK @@ -9612,7 +11141,7 @@ paths: - customer_id - payment_url examples: - - &a36 + - &a40 customer_id: cus_123 invoice: status: paid @@ -9621,7 +11150,7 @@ paths: currency: usd hosted_invoice_url: https://invoice.stripe.com/... payment_url: null - example: *a36 + example: *a40 x-speakeasy-name-override: update parameters: - *a5 @@ -9988,13 +11517,13 @@ paths: - customer_id title: PreviewUpdateParams examples: - - &a37 + - &a41 customer_id: cus_123 plan_id: pro_plan feature_quantities: - feature_id: seats quantity: 15 - example: *a37 + example: *a41 responses: "200": description: OK @@ -10021,10 +11550,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -10077,12 +11607,12 @@ paths: description: List of line items for the current billing period. subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -10094,10 +11624,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -10113,10 +11645,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -10327,6 +11860,51 @@ paths: - uncancel - none type: string + tax: + type: object + properties: + total: + type: number + description: Total tax amount in major currency units. + amount_inclusive: + type: number + description: Tax included in line item subtotals. + amount_exclusive: + type: number + description: Tax added on top of subtotals. + currency: + type: string + description: Three-letter currency code. + status: + enum: + - complete + - incomplete + type: string + description: Calculation status ('complete' when Stripe Tax succeeds or + 'incomplete' when Stripe Tax returned 0 or errored). + required: + - total + - amount_inclusive + - amount_exclusive + - currency + - status + description: Tax preview for the immediate charge. Contact us to enable the tax + flag on your organisation. Shows only with flag enabled, a + Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -10337,7 +11915,7 @@ paths: - outgoing - intent examples: - - &a38 + - &a42 customerId: charles lineItems: - display_name: Pro seed @@ -10348,7 +11926,7 @@ paths: subtotal: 20 total: 20 currency: usd - example: *a38 + example: *a42 x-speakeasy-name-override: previewUpdate parameters: - *a5 @@ -10381,10 +11959,10 @@ paths: - customer_id title: OpenCustomerPortalParams examples: - - &a39 + - &a43 customer_id: cus_123 return_url: https://useautumn.com - example: *a39 + example: *a43 responses: "200": description: OK @@ -10403,10 +11981,10 @@ paths: - customer_id - url examples: - - &a40 + - &a44 customer_id: cus_123 url: https://billing.stripe.com/session/... - example: *a40 + example: *a44 x-speakeasy-name-override: openCustomerPortal parameters: - *a5 @@ -10710,6 +12288,12 @@ paths: billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now'. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -10791,10 +12375,10 @@ paths: - customer_id title: SetupPaymentParams examples: - - &a41 + - &a45 customer_id: cus_123 success_url: https://example.com/account/billing - example: *a41 + example: *a45 responses: "200": description: OK @@ -10818,10 +12402,10 @@ paths: - url title: SetupPaymentResponse examples: - - &a42 + - &a46 customer_id: cus_123 url: https://checkout.stripe.com/... - example: *a42 + example: *a46 x-speakeasy-name-override: setupPayment parameters: - *a5 @@ -10917,13 +12501,13 @@ paths: - feature_id title: CreateBalanceParams examples: - - &a43 + - &a47 customer_id: cus_123 feature_id: api_calls included: 1000 reset: interval: month - example: *a43 + example: *a47 responses: "200": description: OK @@ -11006,11 +12590,11 @@ paths: - feature_id title: UpdateBalanceParams examples: - - &a44 + - &a48 customer_id: cus_123 feature_id: api_calls remaining: 5 - example: *a44 + example: *a48 responses: "200": description: OK @@ -11077,10 +12661,10 @@ paths: - customer_id title: DeleteBalanceParams examples: - - &a45 + - &a49 customer_id: cus_123 feature_id: api_calls - example: *a45 + example: *a49 responses: "200": description: OK @@ -11134,7 +12718,7 @@ paths: - action title: FinalizeBalanceParams examples: - - &a46 + - &a50 lock_id: lock_abc123 action: confirm - lock_id: lock_abc123 @@ -11142,7 +12726,7 @@ paths: override_value: 3 - lock_id: lock_abc123 action: release - example: *a46 + example: *a50 responses: "200": description: OK @@ -11241,14 +12825,14 @@ paths: - feature_id title: CheckParams examples: - - &a47 + - &a51 customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages required_balance: 3 send_event: true - example: *a47 + example: *a51 responses: "200": description: OK @@ -11749,7 +13333,7 @@ paths: - balance - flag examples: - - &a48 + - &a52 allowed: true customer_id: cus_123 entity_id: null @@ -11776,7 +13360,7 @@ paths: resets_at: 1773851121437 price: null expires_at: null - example: *a48 + example: *a52 "202": description: Accepted. Autumn is experiencing degraded service from a downstream provider, so access was allowed fail-open. @@ -12277,7 +13861,7 @@ paths: - balance - flag examples: - - &a49 + - &a53 allowed: true customer_id: cus_123 entity_id: null @@ -12304,7 +13888,7 @@ paths: resets_at: 1773851121437 price: null expires_at: null - example: *a49 + example: *a53 x-speakeasy-name-override: check parameters: - *a5 @@ -12372,11 +13956,11 @@ paths: - customer_id title: TrackParams examples: - - &a50 + - &a54 customer_id: cus_123 feature_id: messages value: 1 - example: *a50 + example: *a54 responses: "200": description: OK @@ -12417,7 +14001,7 @@ paths: - value - balance examples: - - &a51 + - &a55 customer_id: cus_123 value: 1 balance: @@ -12442,7 +14026,7 @@ paths: resets_at: 1773851121437 price: null expires_at: null - example: *a51 + example: *a55 "202": description: Accepted. Autumn is experiencing degraded service from a downstream provider, so the event was accepted for replay and will be tracked @@ -12484,7 +14068,7 @@ paths: - value - balance examples: - - &a52 + - &a56 customer_id: cus_123 value: 1 balance: @@ -12509,7 +14093,7 @@ paths: resets_at: 1773851121437 price: null expires_at: null - example: *a52 + example: *a56 x-speakeasy-name-override: track parameters: - *a5 @@ -12567,14 +14151,14 @@ paths: description: Filter events by time range title: EventsListParams examples: - - &a53 + - &a57 customer_id: cus_123 limit: 50 - feature_id: api_calls custom_range: start: 1704067200000 end: 1706745600000 - example: *a53 + example: *a57 responses: "200": description: OK @@ -12636,7 +14220,7 @@ paths: - limit - total examples: - - &a54 + - &a58 list: - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg timestamp: 1765958215459 @@ -12654,7 +14238,7 @@ paths: has_more: false offset: 0 limit: 100 - example: *a54 + example: *a58 x-speakeasy-name-override: list parameters: - *a5 @@ -12746,7 +14330,7 @@ paths: - feature_id title: EventsAggregateParams examples: - - &a55 + - &a59 customer_id: cus_123 feature_id: api_calls range: 30d @@ -12757,7 +14341,7 @@ paths: - messages range: 7d group_by: properties.model - example: *a55 + example: *a59 responses: "200": description: OK @@ -12819,7 +14403,7 @@ paths: - list - total examples: - - &a56 + - &a60 list: - period: 1762905600000 values: @@ -12866,7 +14450,7 @@ paths: sessions: count: 2 sum: 15 - example: *a56 + example: *a60 x-speakeasy-name-override: aggregate parameters: - *a5 @@ -12986,1000 +14570,11 @@ paths: - entity_id title: CreateEntityParams examples: - - &a57 + - &a61 customer_id: cus_123 entity_id: seat_42 feature_id: seats name: Seat 42 - example: *a57 - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - id: - anyOf: - - type: string - - type: "null" - description: The unique identifier of the entity - name: - anyOf: - - type: string - - type: "null" - description: The name of the entity - customer_id: - anyOf: - - type: string - - type: "null" - description: The customer ID this entity belongs to - feature_id: - anyOf: - - type: string - - type: "null" - description: The feature ID this entity belongs to - created_at: - type: number - description: Unix timestamp when the entity was created - env: - enum: - - sandbox - - live - type: string - description: The environment (sandbox/live) - subscriptions: - type: array - items: - type: object - properties: - id: - type: string - description: The unique identifier of this subscription. If a subscription_id - was provided at attach time, it is used; otherwise, - falls back to the internal ID. - plan: - $ref: "#/components/schemas/Plan" - description: The full plan object if expanded. - plan_id: - type: string - description: The unique identifier of the subscribed plan. - auto_enable: - type: boolean - description: Whether the plan was automatically enabled for the customer. - add_on: - type: boolean - description: Whether this is an add-on plan rather than a base subscription. - status: - enum: - - active - - scheduled - type: string - description: Current status of the subscription. - past_due: - type: boolean - description: Whether the subscription has overdue payments. - canceled_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the subscription was canceled, or null if not - canceled. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the subscription will expire, or null if no expiry - set. - trial_ends_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the trial period ends, or null if not on trial. - started_at: - type: number - description: Timestamp when the subscription started. - current_period_start: - anyOf: - - type: number - - type: "null" - description: Start timestamp of the current billing period. - current_period_end: - anyOf: - - type: number - - type: "null" - description: End timestamp of the current billing period. - quantity: - type: number - description: Number of units of this subscription (for per-seat plans). - required: - - id - - plan_id - - auto_enable - - add_on - - status - - past_due - - canceled_at - - expires_at - - trial_ends_at - - started_at - - current_period_start - - current_period_end - - quantity - purchases: - type: array - items: - type: object - properties: - plan: - $ref: "#/components/schemas/Plan" - description: The full plan object if expanded. - plan_id: - type: string - description: The unique identifier of the purchased plan. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the purchase expires, or null for lifetime access. - started_at: - type: number - description: Timestamp when the purchase was made. - quantity: - type: number - description: Number of units purchased. - required: - - plan_id - - expires_at - - started_at - - quantity - balances: - type: object - propertyNames: - type: string - additionalProperties: - $ref: "#/components/schemas/Balance" - flags: - type: object - propertyNames: - type: string - additionalProperties: - type: object - properties: - id: - type: string - description: The unique identifier for this flag. - plan_id: - anyOf: - - type: string - - type: "null" - description: The plan ID this flag originates from, or null for standalone - flags. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when this flag expires, or null for no expiration. - feature_id: - type: string - description: The feature ID this flag is for. - feature: - type: object - properties: - id: - type: string - description: The unique identifier for this feature, used in /check and /track - calls. - name: - type: string - description: Human-readable name displayed in the dashboard and billing UI. - type: - enum: - - boolean - - metered - - credit_system - type: string - description: "Feature type: 'boolean' for on/off access, 'metered' for - usage-tracked features, 'credit_system' for - unified credit pools." - consumable: - type: boolean - description: "For metered features: true if usage resets periodically (API - calls, credits), false if allocated persistently - (seats, storage)." - event_names: - type: array - items: - type: string - description: Event names that trigger this feature's balance. Allows multiple - features to respond to a single event. - credit_schema: - type: array - items: - type: object - properties: - metered_feature_id: - type: string - description: ID of the metered feature that draws from this credit system. - credit_cost: - type: number - description: Credits consumed per unit of the metered feature. - required: - - metered_feature_id - - credit_cost - description: "For credit_system features: maps metered features to their credit - costs." - display: - type: object - properties: - singular: - anyOf: - - type: string - - type: "null" - description: Singular form for UI display (e.g., 'API call', 'seat'). - plural: - anyOf: - - type: string - - type: "null" - description: Plural form for UI display (e.g., 'API calls', 'seats'). - description: Display names for the feature in billing UI and customer-facing - components. - archived: - type: boolean - description: Whether the feature is archived and hidden from the dashboard. - required: - - id - - name - - type - - consumable - - archived - description: The full feature object if expanded. - required: - - id - - plan_id - - expires_at - - feature_id - examples: - - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV - plan_id: pro_plan - expires_at: null - feature_id: dashboard - billing_controls: - type: object - properties: - spend_limits: - type: array - items: - type: object - properties: - feature_id: - type: string - description: Optional feature ID this spend limit applies to. - enabled: - type: boolean - default: false - description: Whether this spend limit is enabled. - overage_limit: - type: number - minimum: 0 - description: Maximum allowed overage spend for the target feature. - description: List of overage spend limits per feature. - usage_alerts: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this alert applies to. - enabled: - type: boolean - default: true - description: Whether this usage alert is enabled. - threshold: - type: number - minimum: 0 - description: The threshold value that triggers the alert. For usage or - remaining, this is an absolute count. For - usage_percentage or remaining_percentage, this - is a percentage (0-100). - threshold_type: - enum: - - usage - - usage_percentage - - remaining - - remaining_percentage - type: string - description: Whether the threshold is an absolute count or a percentage of the - usage allowance or remaining balance. - name: - type: string - description: Optional user-defined label to distinguish multiple alerts on the - same feature. - required: - - threshold - - threshold_type - description: List of usage alert configurations per feature. - overage_allowed: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this overage allowed control applies to. - enabled: - type: boolean - default: false - description: Whether overage is allowed for this feature. - required: - - feature_id - description: List of overage allowed controls per feature. When enabled, usage - can exceed balance. - description: Billing controls for the entity. - invoices: - type: array - items: - type: object - properties: - plan_ids: - type: array - items: - type: string - description: Array of plan IDs included in this invoice - stripe_id: - type: string - description: The Stripe invoice ID - status: - type: string - description: The status of the invoice - total: - type: number - description: The total amount of the invoice - currency: - type: string - description: The currency code for the invoice - created_at: - type: number - description: Timestamp when the invoice was created - hosted_invoice_url: - anyOf: - - type: string - - type: "null" - description: URL to the Stripe-hosted invoice page - required: - - plan_ids - - stripe_id - - status - - total - - currency - - created_at - description: Invoices for this entity (only included when expand=invoices) - required: - - id - - name - - created_at - - env - - subscriptions - - purchases - - balances - - flags - examples: - - &a58 - id: seat_42 - name: Seat 42 - customer_id: cus_123 - feature_id: seats - created_at: 1771409161016 - env: sandbox - subscriptions: - - plan_id: pro_plan - auto_enable: true - add_on: false - status: active - past_due: false - canceled_at: null - expires_at: null - trial_ends_at: null - started_at: 1771431921437 - current_period_start: 1771431921437 - current_period_end: 1771999921437 - quantity: 1 - purchases: [] - balances: - messages: - feature_id: messages - granted: 100 - remaining: 72 - usage: 28 - unlimited: false - overage_allowed: false - max_purchase: null - next_reset_at: 1773851121437 - breakdown: - - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV - plan_id: pro_plan - included_grant: 100 - prepaid_grant: 0 - remaining: 72 - usage: 28 - unlimited: false - reset: - interval: month - resets_at: 1773851121437 - price: null - expires_at: null - invoices: [] - example: *a58 - x-speakeasy-name-override: create - parameters: - - *a5 - /v1/entities.get: - post: - operationId: getEntity - description: >- - Fetches an entity by its ID. - - - Use this to read one entity's current state. Pass customerId when you - want to scope the lookup to a specific customer. - tags: - - entities - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - customer_id: - type: string - description: The ID of the customer to create the entity for. - entity_id: - type: string - description: The ID of the entity. - required: - - entity_id - title: GetEntityParams - examples: - - &a59 - entity_id: seat_42 - - customer_id: cus_123 - entity_id: seat_42 - example: *a59 - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - id: - anyOf: - - type: string - - type: "null" - description: The unique identifier of the entity - name: - anyOf: - - type: string - - type: "null" - description: The name of the entity - customer_id: - anyOf: - - type: string - - type: "null" - description: The customer ID this entity belongs to - feature_id: - anyOf: - - type: string - - type: "null" - description: The feature ID this entity belongs to - created_at: - type: number - description: Unix timestamp when the entity was created - env: - enum: - - sandbox - - live - type: string - description: The environment (sandbox/live) - subscriptions: - type: array - items: - type: object - properties: - id: - type: string - description: The unique identifier of this subscription. If a subscription_id - was provided at attach time, it is used; otherwise, - falls back to the internal ID. - plan: - $ref: "#/components/schemas/Plan" - description: The full plan object if expanded. - plan_id: - type: string - description: The unique identifier of the subscribed plan. - auto_enable: - type: boolean - description: Whether the plan was automatically enabled for the customer. - add_on: - type: boolean - description: Whether this is an add-on plan rather than a base subscription. - status: - enum: - - active - - scheduled - type: string - description: Current status of the subscription. - past_due: - type: boolean - description: Whether the subscription has overdue payments. - canceled_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the subscription was canceled, or null if not - canceled. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the subscription will expire, or null if no expiry - set. - trial_ends_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the trial period ends, or null if not on trial. - started_at: - type: number - description: Timestamp when the subscription started. - current_period_start: - anyOf: - - type: number - - type: "null" - description: Start timestamp of the current billing period. - current_period_end: - anyOf: - - type: number - - type: "null" - description: End timestamp of the current billing period. - quantity: - type: number - description: Number of units of this subscription (for per-seat plans). - required: - - id - - plan_id - - auto_enable - - add_on - - status - - past_due - - canceled_at - - expires_at - - trial_ends_at - - started_at - - current_period_start - - current_period_end - - quantity - purchases: - type: array - items: - type: object - properties: - plan: - $ref: "#/components/schemas/Plan" - description: The full plan object if expanded. - plan_id: - type: string - description: The unique identifier of the purchased plan. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when the purchase expires, or null for lifetime access. - started_at: - type: number - description: Timestamp when the purchase was made. - quantity: - type: number - description: Number of units purchased. - required: - - plan_id - - expires_at - - started_at - - quantity - balances: - type: object - propertyNames: - type: string - additionalProperties: - $ref: "#/components/schemas/Balance" - flags: - type: object - propertyNames: - type: string - additionalProperties: - type: object - properties: - id: - type: string - description: The unique identifier for this flag. - plan_id: - anyOf: - - type: string - - type: "null" - description: The plan ID this flag originates from, or null for standalone - flags. - expires_at: - anyOf: - - type: number - - type: "null" - description: Timestamp when this flag expires, or null for no expiration. - feature_id: - type: string - description: The feature ID this flag is for. - feature: - type: object - properties: - id: - type: string - description: The unique identifier for this feature, used in /check and /track - calls. - name: - type: string - description: Human-readable name displayed in the dashboard and billing UI. - type: - enum: - - boolean - - metered - - credit_system - type: string - description: "Feature type: 'boolean' for on/off access, 'metered' for - usage-tracked features, 'credit_system' for - unified credit pools." - consumable: - type: boolean - description: "For metered features: true if usage resets periodically (API - calls, credits), false if allocated persistently - (seats, storage)." - event_names: - type: array - items: - type: string - description: Event names that trigger this feature's balance. Allows multiple - features to respond to a single event. - credit_schema: - type: array - items: - type: object - properties: - metered_feature_id: - type: string - description: ID of the metered feature that draws from this credit system. - credit_cost: - type: number - description: Credits consumed per unit of the metered feature. - required: - - metered_feature_id - - credit_cost - description: "For credit_system features: maps metered features to their credit - costs." - display: - type: object - properties: - singular: - anyOf: - - type: string - - type: "null" - description: Singular form for UI display (e.g., 'API call', 'seat'). - plural: - anyOf: - - type: string - - type: "null" - description: Plural form for UI display (e.g., 'API calls', 'seats'). - description: Display names for the feature in billing UI and customer-facing - components. - archived: - type: boolean - description: Whether the feature is archived and hidden from the dashboard. - required: - - id - - name - - type - - consumable - - archived - description: The full feature object if expanded. - required: - - id - - plan_id - - expires_at - - feature_id - examples: - - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV - plan_id: pro_plan - expires_at: null - feature_id: dashboard - billing_controls: - type: object - properties: - spend_limits: - type: array - items: - type: object - properties: - feature_id: - type: string - description: Optional feature ID this spend limit applies to. - enabled: - type: boolean - default: false - description: Whether this spend limit is enabled. - overage_limit: - type: number - minimum: 0 - description: Maximum allowed overage spend for the target feature. - description: List of overage spend limits per feature. - usage_alerts: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this alert applies to. - enabled: - type: boolean - default: true - description: Whether this usage alert is enabled. - threshold: - type: number - minimum: 0 - description: The threshold value that triggers the alert. For usage or - remaining, this is an absolute count. For - usage_percentage or remaining_percentage, this - is a percentage (0-100). - threshold_type: - enum: - - usage - - usage_percentage - - remaining - - remaining_percentage - type: string - description: Whether the threshold is an absolute count or a percentage of the - usage allowance or remaining balance. - name: - type: string - description: Optional user-defined label to distinguish multiple alerts on the - same feature. - required: - - threshold - - threshold_type - description: List of usage alert configurations per feature. - overage_allowed: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this overage allowed control applies to. - enabled: - type: boolean - default: false - description: Whether overage is allowed for this feature. - required: - - feature_id - description: List of overage allowed controls per feature. When enabled, usage - can exceed balance. - description: Billing controls for the entity. - invoices: - type: array - items: - type: object - properties: - plan_ids: - type: array - items: - type: string - description: Array of plan IDs included in this invoice - stripe_id: - type: string - description: The Stripe invoice ID - status: - type: string - description: The status of the invoice - total: - type: number - description: The total amount of the invoice - currency: - type: string - description: The currency code for the invoice - created_at: - type: number - description: Timestamp when the invoice was created - hosted_invoice_url: - anyOf: - - type: string - - type: "null" - description: URL to the Stripe-hosted invoice page - required: - - plan_ids - - stripe_id - - status - - total - - currency - - created_at - description: Invoices for this entity (only included when expand=invoices) - required: - - id - - name - - created_at - - env - - subscriptions - - purchases - - balances - - flags - examples: - - &a60 - id: seat_42 - name: Seat 42 - customer_id: cus_123 - feature_id: seats - created_at: 1771409161016 - env: sandbox - subscriptions: - - plan_id: pro_plan - auto_enable: true - add_on: false - status: active - past_due: false - canceled_at: null - expires_at: null - trial_ends_at: null - started_at: 1771431921437 - current_period_start: 1771431921437 - current_period_end: 1771999921437 - quantity: 1 - purchases: [] - balances: - messages: - feature_id: messages - granted: 100 - remaining: 72 - usage: 28 - unlimited: false - overage_allowed: false - max_purchase: null - next_reset_at: 1773851121437 - breakdown: - - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV - plan_id: pro_plan - included_grant: 100 - prepaid_grant: 0 - remaining: 72 - usage: 28 - unlimited: false - reset: - interval: month - resets_at: 1773851121437 - price: null - expires_at: null - invoices: [] - example: *a60 - x-speakeasy-name-override: get - parameters: - - *a5 - /v1/entities.update: - post: - operationId: updateEntity - description: >- - Updates an existing entity and returns the refreshed entity object. - - - Use this to change entity billing controls or other mutable entity - fields after the entity has already been created. - tags: - - entities - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - customer_id: - type: string - description: The ID of the customer that owns the entity. - entity_id: - type: string - description: The ID of the entity. - billing_controls: - type: object - properties: - spend_limits: - type: array - items: - type: object - properties: - feature_id: - type: string - description: Optional feature ID this spend limit applies to. - enabled: - type: boolean - default: false - description: Whether this spend limit is enabled. - overage_limit: - type: number - minimum: 0 - description: Maximum allowed overage spend for the target feature. - description: List of overage spend limits per feature. - usage_alerts: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this alert applies to. - enabled: - type: boolean - default: true - description: Whether this usage alert is enabled. - threshold: - type: number - minimum: 0 - description: The threshold value that triggers the alert. For usage or - remaining, this is an absolute count. For - usage_percentage or remaining_percentage, this is - a percentage (0-100). - threshold_type: - enum: - - usage - - usage_percentage - - remaining - - remaining_percentage - type: string - description: Whether the threshold is an absolute count or a percentage of the - usage allowance or remaining balance. - name: - type: string - description: Optional user-defined label to distinguish multiple alerts on the - same feature. - required: - - threshold - - threshold_type - description: List of usage alert configurations per feature. - overage_allowed: - type: array - items: - type: object - properties: - feature_id: - type: string - description: The feature ID this overage allowed control applies to. - enabled: - type: boolean - default: false - description: Whether overage is allowed for this feature. - required: - - feature_id - description: List of overage allowed controls per feature. When enabled, usage - can exceed balance. - description: Billing controls to replace on the entity. - required: - - entity_id - title: UpdateEntityParams - examples: - - &a61 - customer_id: cus_123 - entity_id: seat_42 - billing_controls: - spend_limits: - - feature_id: messages - enabled: true - overage_limit: 25 example: *a61 responses: "200": @@ -14401,6 +14996,995 @@ paths: expires_at: null invoices: [] example: *a62 + x-speakeasy-name-override: create + parameters: + - *a5 + /v1/entities.get: + post: + operationId: getEntity + description: >- + Fetches an entity by its ID. + + + Use this to read one entity's current state. Pass customerId when you + want to scope the lookup to a specific customer. + tags: + - entities + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer to create the entity for. + entity_id: + type: string + description: The ID of the entity. + required: + - entity_id + title: GetEntityParams + examples: + - &a63 + entity_id: seat_42 + - customer_id: cus_123 + entity_id: seat_42 + example: *a63 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: The unique identifier of the entity + name: + anyOf: + - type: string + - type: "null" + description: The name of the entity + customer_id: + anyOf: + - type: string + - type: "null" + description: The customer ID this entity belongs to + feature_id: + anyOf: + - type: string + - type: "null" + description: The feature ID this entity belongs to + created_at: + type: number + description: Unix timestamp when the entity was created + env: + enum: + - sandbox + - live + type: string + description: The environment (sandbox/live) + subscriptions: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier of this subscription. If a subscription_id + was provided at attach time, it is used; otherwise, + falls back to the internal ID. + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the subscribed plan. + auto_enable: + type: boolean + description: Whether the plan was automatically enabled for the customer. + add_on: + type: boolean + description: Whether this is an add-on plan rather than a base subscription. + status: + enum: + - active + - scheduled + type: string + description: Current status of the subscription. + past_due: + type: boolean + description: Whether the subscription has overdue payments. + canceled_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription was canceled, or null if not + canceled. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription will expire, or null if no expiry + set. + trial_ends_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the trial period ends, or null if not on trial. + started_at: + type: number + description: Timestamp when the subscription started. + current_period_start: + anyOf: + - type: number + - type: "null" + description: Start timestamp of the current billing period. + current_period_end: + anyOf: + - type: number + - type: "null" + description: End timestamp of the current billing period. + quantity: + type: number + description: Number of units of this subscription (for per-seat plans). + required: + - id + - plan_id + - auto_enable + - add_on + - status + - past_due + - canceled_at + - expires_at + - trial_ends_at + - started_at + - current_period_start + - current_period_end + - quantity + purchases: + type: array + items: + type: object + properties: + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the purchased plan. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the purchase expires, or null for lifetime access. + started_at: + type: number + description: Timestamp when the purchase was made. + quantity: + type: number + description: Number of units purchased. + required: + - plan_id + - expires_at + - started_at + - quantity + balances: + type: object + propertyNames: + type: string + additionalProperties: + $ref: "#/components/schemas/Balance" + flags: + type: object + propertyNames: + type: string + additionalProperties: + type: object + properties: + id: + type: string + description: The unique identifier for this flag. + plan_id: + anyOf: + - type: string + - type: "null" + description: The plan ID this flag originates from, or null for standalone + flags. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when this flag expires, or null for no expiration. + feature_id: + type: string + description: The feature ID this flag is for. + feature: + type: object + properties: + id: + type: string + description: The unique identifier for this feature, used in /check and /track + calls. + name: + type: string + description: Human-readable name displayed in the dashboard and billing UI. + type: + enum: + - boolean + - metered + - credit_system + type: string + description: "Feature type: 'boolean' for on/off access, 'metered' for + usage-tracked features, 'credit_system' for + unified credit pools." + consumable: + type: boolean + description: "For metered features: true if usage resets periodically (API + calls, credits), false if allocated persistently + (seats, storage)." + event_names: + type: array + items: + type: string + description: Event names that trigger this feature's balance. Allows multiple + features to respond to a single event. + credit_schema: + type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: ID of the metered feature that draws from this credit system. + credit_cost: + type: number + description: Credits consumed per unit of the metered feature. + required: + - metered_feature_id + - credit_cost + description: "For credit_system features: maps metered features to their credit + costs." + display: + type: object + properties: + singular: + anyOf: + - type: string + - type: "null" + description: Singular form for UI display (e.g., 'API call', 'seat'). + plural: + anyOf: + - type: string + - type: "null" + description: Plural form for UI display (e.g., 'API calls', 'seats'). + description: Display names for the feature in billing UI and customer-facing + components. + archived: + type: boolean + description: Whether the feature is archived and hidden from the dashboard. + required: + - id + - name + - type + - consumable + - archived + description: The full feature object if expanded. + required: + - id + - plan_id + - expires_at + - feature_id + examples: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + expires_at: null + feature_id: dashboard + billing_controls: + type: object + properties: + spend_limits: + type: array + items: + type: object + properties: + feature_id: + type: string + description: Optional feature ID this spend limit applies to. + enabled: + type: boolean + default: false + description: Whether this spend limit is enabled. + overage_limit: + type: number + minimum: 0 + description: Maximum allowed overage spend for the target feature. + description: List of overage spend limits per feature. + usage_alerts: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this alert applies to. + enabled: + type: boolean + default: true + description: Whether this usage alert is enabled. + threshold: + type: number + minimum: 0 + description: The threshold value that triggers the alert. For usage or + remaining, this is an absolute count. For + usage_percentage or remaining_percentage, this + is a percentage (0-100). + threshold_type: + enum: + - usage + - usage_percentage + - remaining + - remaining_percentage + type: string + description: Whether the threshold is an absolute count or a percentage of the + usage allowance or remaining balance. + name: + type: string + description: Optional user-defined label to distinguish multiple alerts on the + same feature. + required: + - threshold + - threshold_type + description: List of usage alert configurations per feature. + overage_allowed: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this overage allowed control applies to. + enabled: + type: boolean + default: false + description: Whether overage is allowed for this feature. + required: + - feature_id + description: List of overage allowed controls per feature. When enabled, usage + can exceed balance. + description: Billing controls for the entity. + invoices: + type: array + items: + type: object + properties: + plan_ids: + type: array + items: + type: string + description: Array of plan IDs included in this invoice + stripe_id: + type: string + description: The Stripe invoice ID + status: + type: string + description: The status of the invoice + total: + type: number + description: The total amount of the invoice + currency: + type: string + description: The currency code for the invoice + created_at: + type: number + description: Timestamp when the invoice was created + hosted_invoice_url: + anyOf: + - type: string + - type: "null" + description: URL to the Stripe-hosted invoice page + required: + - plan_ids + - stripe_id + - status + - total + - currency + - created_at + description: Invoices for this entity (only included when expand=invoices) + required: + - id + - name + - created_at + - env + - subscriptions + - purchases + - balances + - flags + examples: + - &a64 + id: seat_42 + name: Seat 42 + customer_id: cus_123 + feature_id: seats + created_at: 1771409161016 + env: sandbox + subscriptions: + - plan_id: pro_plan + auto_enable: true + add_on: false + status: active + past_due: false + canceled_at: null + expires_at: null + trial_ends_at: null + started_at: 1771431921437 + current_period_start: 1771431921437 + current_period_end: 1771999921437 + quantity: 1 + purchases: [] + balances: + messages: + feature_id: messages + granted: 100 + remaining: 72 + usage: 28 + unlimited: false + overage_allowed: false + max_purchase: null + next_reset_at: 1773851121437 + breakdown: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + included_grant: 100 + prepaid_grant: 0 + remaining: 72 + usage: 28 + unlimited: false + reset: + interval: month + resets_at: 1773851121437 + price: null + expires_at: null + invoices: [] + example: *a64 + x-speakeasy-name-override: get + parameters: + - *a5 + /v1/entities.update: + post: + operationId: updateEntity + description: >- + Updates an existing entity and returns the refreshed entity object. + + + Use this to change entity billing controls or other mutable entity + fields after the entity has already been created. + tags: + - entities + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer that owns the entity. + entity_id: + type: string + description: The ID of the entity. + billing_controls: + type: object + properties: + spend_limits: + type: array + items: + type: object + properties: + feature_id: + type: string + description: Optional feature ID this spend limit applies to. + enabled: + type: boolean + default: false + description: Whether this spend limit is enabled. + overage_limit: + type: number + minimum: 0 + description: Maximum allowed overage spend for the target feature. + description: List of overage spend limits per feature. + usage_alerts: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this alert applies to. + enabled: + type: boolean + default: true + description: Whether this usage alert is enabled. + threshold: + type: number + minimum: 0 + description: The threshold value that triggers the alert. For usage or + remaining, this is an absolute count. For + usage_percentage or remaining_percentage, this is + a percentage (0-100). + threshold_type: + enum: + - usage + - usage_percentage + - remaining + - remaining_percentage + type: string + description: Whether the threshold is an absolute count or a percentage of the + usage allowance or remaining balance. + name: + type: string + description: Optional user-defined label to distinguish multiple alerts on the + same feature. + required: + - threshold + - threshold_type + description: List of usage alert configurations per feature. + overage_allowed: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this overage allowed control applies to. + enabled: + type: boolean + default: false + description: Whether overage is allowed for this feature. + required: + - feature_id + description: List of overage allowed controls per feature. When enabled, usage + can exceed balance. + description: Billing controls to replace on the entity. + required: + - entity_id + title: UpdateEntityParams + examples: + - &a65 + customer_id: cus_123 + entity_id: seat_42 + billing_controls: + spend_limits: + - feature_id: messages + enabled: true + overage_limit: 25 + example: *a65 + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: The unique identifier of the entity + name: + anyOf: + - type: string + - type: "null" + description: The name of the entity + customer_id: + anyOf: + - type: string + - type: "null" + description: The customer ID this entity belongs to + feature_id: + anyOf: + - type: string + - type: "null" + description: The feature ID this entity belongs to + created_at: + type: number + description: Unix timestamp when the entity was created + env: + enum: + - sandbox + - live + type: string + description: The environment (sandbox/live) + subscriptions: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier of this subscription. If a subscription_id + was provided at attach time, it is used; otherwise, + falls back to the internal ID. + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the subscribed plan. + auto_enable: + type: boolean + description: Whether the plan was automatically enabled for the customer. + add_on: + type: boolean + description: Whether this is an add-on plan rather than a base subscription. + status: + enum: + - active + - scheduled + type: string + description: Current status of the subscription. + past_due: + type: boolean + description: Whether the subscription has overdue payments. + canceled_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription was canceled, or null if not + canceled. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription will expire, or null if no expiry + set. + trial_ends_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the trial period ends, or null if not on trial. + started_at: + type: number + description: Timestamp when the subscription started. + current_period_start: + anyOf: + - type: number + - type: "null" + description: Start timestamp of the current billing period. + current_period_end: + anyOf: + - type: number + - type: "null" + description: End timestamp of the current billing period. + quantity: + type: number + description: Number of units of this subscription (for per-seat plans). + required: + - id + - plan_id + - auto_enable + - add_on + - status + - past_due + - canceled_at + - expires_at + - trial_ends_at + - started_at + - current_period_start + - current_period_end + - quantity + purchases: + type: array + items: + type: object + properties: + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the purchased plan. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the purchase expires, or null for lifetime access. + started_at: + type: number + description: Timestamp when the purchase was made. + quantity: + type: number + description: Number of units purchased. + required: + - plan_id + - expires_at + - started_at + - quantity + balances: + type: object + propertyNames: + type: string + additionalProperties: + $ref: "#/components/schemas/Balance" + flags: + type: object + propertyNames: + type: string + additionalProperties: + type: object + properties: + id: + type: string + description: The unique identifier for this flag. + plan_id: + anyOf: + - type: string + - type: "null" + description: The plan ID this flag originates from, or null for standalone + flags. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when this flag expires, or null for no expiration. + feature_id: + type: string + description: The feature ID this flag is for. + feature: + type: object + properties: + id: + type: string + description: The unique identifier for this feature, used in /check and /track + calls. + name: + type: string + description: Human-readable name displayed in the dashboard and billing UI. + type: + enum: + - boolean + - metered + - credit_system + type: string + description: "Feature type: 'boolean' for on/off access, 'metered' for + usage-tracked features, 'credit_system' for + unified credit pools." + consumable: + type: boolean + description: "For metered features: true if usage resets periodically (API + calls, credits), false if allocated persistently + (seats, storage)." + event_names: + type: array + items: + type: string + description: Event names that trigger this feature's balance. Allows multiple + features to respond to a single event. + credit_schema: + type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: ID of the metered feature that draws from this credit system. + credit_cost: + type: number + description: Credits consumed per unit of the metered feature. + required: + - metered_feature_id + - credit_cost + description: "For credit_system features: maps metered features to their credit + costs." + display: + type: object + properties: + singular: + anyOf: + - type: string + - type: "null" + description: Singular form for UI display (e.g., 'API call', 'seat'). + plural: + anyOf: + - type: string + - type: "null" + description: Plural form for UI display (e.g., 'API calls', 'seats'). + description: Display names for the feature in billing UI and customer-facing + components. + archived: + type: boolean + description: Whether the feature is archived and hidden from the dashboard. + required: + - id + - name + - type + - consumable + - archived + description: The full feature object if expanded. + required: + - id + - plan_id + - expires_at + - feature_id + examples: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + expires_at: null + feature_id: dashboard + billing_controls: + type: object + properties: + spend_limits: + type: array + items: + type: object + properties: + feature_id: + type: string + description: Optional feature ID this spend limit applies to. + enabled: + type: boolean + default: false + description: Whether this spend limit is enabled. + overage_limit: + type: number + minimum: 0 + description: Maximum allowed overage spend for the target feature. + description: List of overage spend limits per feature. + usage_alerts: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this alert applies to. + enabled: + type: boolean + default: true + description: Whether this usage alert is enabled. + threshold: + type: number + minimum: 0 + description: The threshold value that triggers the alert. For usage or + remaining, this is an absolute count. For + usage_percentage or remaining_percentage, this + is a percentage (0-100). + threshold_type: + enum: + - usage + - usage_percentage + - remaining + - remaining_percentage + type: string + description: Whether the threshold is an absolute count or a percentage of the + usage allowance or remaining balance. + name: + type: string + description: Optional user-defined label to distinguish multiple alerts on the + same feature. + required: + - threshold + - threshold_type + description: List of usage alert configurations per feature. + overage_allowed: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this overage allowed control applies to. + enabled: + type: boolean + default: false + description: Whether overage is allowed for this feature. + required: + - feature_id + description: List of overage allowed controls per feature. When enabled, usage + can exceed balance. + description: Billing controls for the entity. + invoices: + type: array + items: + type: object + properties: + plan_ids: + type: array + items: + type: string + description: Array of plan IDs included in this invoice + stripe_id: + type: string + description: The Stripe invoice ID + status: + type: string + description: The status of the invoice + total: + type: number + description: The total amount of the invoice + currency: + type: string + description: The currency code for the invoice + created_at: + type: number + description: Timestamp when the invoice was created + hosted_invoice_url: + anyOf: + - type: string + - type: "null" + description: URL to the Stripe-hosted invoice page + required: + - plan_ids + - stripe_id + - status + - total + - currency + - created_at + description: Invoices for this entity (only included when expand=invoices) + required: + - id + - name + - created_at + - env + - subscriptions + - purchases + - balances + - flags + examples: + - &a66 + id: seat_42 + name: Seat 42 + customer_id: cus_123 + feature_id: seats + created_at: 1771409161016 + env: sandbox + subscriptions: + - plan_id: pro_plan + auto_enable: true + add_on: false + status: active + past_due: false + canceled_at: null + expires_at: null + trial_ends_at: null + started_at: 1771431921437 + current_period_start: 1771431921437 + current_period_end: 1771999921437 + quantity: 1 + purchases: [] + balances: + messages: + feature_id: messages + granted: 100 + remaining: 72 + usage: 28 + unlimited: false + overage_allowed: false + max_purchase: null + next_reset_at: 1773851121437 + breakdown: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + included_grant: 100 + prepaid_grant: 0 + remaining: 72 + usage: 28 + unlimited: false + reset: + interval: month + resets_at: 1773851121437 + price: null + expires_at: null + invoices: [] + example: *a66 x-speakeasy-name-override: update parameters: - *a5 @@ -14432,10 +16016,10 @@ paths: - entity_id title: DeleteEntityParams examples: - - &a63 + - &a67 customer_id: cus_123 entity_id: seat_42 - example: *a63 + example: *a67 responses: "200": description: OK @@ -14449,9 +16033,9 @@ paths: required: - success examples: - - &a64 + - &a68 success: true - example: *a64 + example: *a68 x-speakeasy-name-override: delete parameters: - *a5 @@ -14479,10 +16063,10 @@ paths: - program_id title: CreateReferralCodeParams examples: - - &a65 + - &a69 customer_id: cus_123 program_id: prog_123 - example: *a65 + example: *a69 responses: "200": description: OK @@ -14505,11 +16089,11 @@ paths: - customer_id - created_at examples: - - &a66 + - &a70 code: customer_id: created_at: 123 - example: *a66 + example: *a70 x-speakeasy-name-override: createCode parameters: - *a5 @@ -14537,10 +16121,10 @@ paths: - customer_id title: RedeemReferralCodeParams examples: - - &a67 + - &a71 code: REF123 customer_id: cus_456 - example: *a67 + example: *a71 responses: "200": description: OK @@ -14563,11 +16147,11 @@ paths: - customer_id - reward_id examples: - - &a68 + - &a72 id: customer_id: reward_id: - example: *a68 + example: *a72 x-speakeasy-name-override: redeemCode parameters: - *a5 @@ -14729,6 +16313,118 @@ webhooks: responses: "200": description: Webhook received successfully. + billing.auto_topup_succeeded: + post: + operationId: billingAutoTopupSucceeded + summary: Auto Top-Up Succeeded + description: Fired when an automatic top-up grants additional prepaid balance. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - type + - data + properties: + type: + type: string + const: billing.auto_topup_succeeded + description: The webhook event type. + data: + examples: + - customer_id: cus_123 + feature_id: messages + quantity_granted: 100 + threshold: 20 + balance_after: 115 + invoice_mode: false + invoice: + stripe_id: in_1A2B3C4D5E6F7G8H + status: paid + total: 1000 + currency: usd + hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 + type: object + properties: + customer_id: + description: The ID of the customer whose balance was topped up. + type: string + feature_id: + description: The feature ID that was automatically topped up. + type: string + quantity_granted: + description: The normalized amount of balance granted by the top-up. + type: number + threshold: + description: The configured balance threshold that triggered the top-up. + type: number + balance_after: + description: The customer's remaining balance for the feature after the top-up. + type: number + invoice_mode: + description: Whether the auto top-up created a send_invoice invoice instead of + auto-charging. + type: boolean + invoice: + description: The invoice created for the auto top-up. + type: object + properties: + stripe_id: + description: The Stripe invoice ID. Use this as a stable dedupe key. + type: string + status: + description: The status of the invoice. "paid" for auto-charged top-ups; "open" + for invoice-mode top-ups where credits were granted + but the invoice has not yet been paid. + anyOf: + - type: string + - type: "null" + total: + description: The total amount of the invoice in the smallest currency unit (e.g. + cents for USD), matching Stripe's invoice.total. + type: number + currency: + description: The ISO currency code for the invoice. + type: string + hosted_invoice_url: + description: URL to the hosted invoice page, if available. + anyOf: + - type: string + - type: "null" + required: + - stripe_id + - total + - currency + additionalProperties: false + required: + - customer_id + - feature_id + - quantity_granted + - threshold + - balance_after + - invoice_mode + - invoice + additionalProperties: false + example: + type: billing.auto_topup_succeeded + data: + customer_id: cus_123 + feature_id: messages + quantity_granted: 100 + threshold: 20 + balance_after: 115 + invoice_mode: false + invoice: + stripe_id: in_1A2B3C4D5E6F7G8H + status: paid + total: 1000 + currency: usd + hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 + responses: + "200": + description: Webhook received successfully. vercel.resources.deleted: post: operationId: vercelResourcesDeleted diff --git a/packages/openapi/openapi.yml b/packages/openapi/openapi.yml index 30ea8cb44..c489f042e 100644 --- a/packages/openapi/openapi.yml +++ b/packages/openapi/openapi.yml @@ -1835,7 +1835,7 @@ paths: expand: type: array items: - type: string + $ref: "#/components/schemas/CustomerExpand" description: Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature. @@ -1863,6 +1863,808 @@ paths: type: string default: 2.2.0 x-speakeasy-globals-hidden: true + /v1/customers.get: + post: + operationId: getCustomer + description: >- + Fetches a customer by ID, optionally expanding related data such as + invoices or entities. + + + Use this when you know the customer exists or assert they exist without + creating them. + + + @example + + ```typescript + + // Fetch a customer by external ID + + const response = await client.get({ customerId: "cus_123" }); + + ``` + + + @example + + ```typescript + + // Fetch a customer with expanded invoices and entities + + const response = await client.get({ customerId: "cus_123", expand: + ["invoices","entities"] }); + + ``` + + + @param customerId - ID of the customer to fetch + + @param expand - Expand related customer data like invoices or entities, + or expand nested objects like balances.feature, flags.feature, + subscriptions.plan, and purchases.plan. (optional) + tags: + - customers + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + title: CustomerId + description: ID of the customer to fetch + expand: + type: array + items: + $ref: "#/components/schemas/CustomerExpand" + description: Expand related customer data like invoices or entities, or expand + nested objects like balances.feature, flags.feature, + subscriptions.plan, and purchases.plan. + required: + - customer_id + title: GetCustomerParams + examples: + - customer_id: cus_123 + - customer_id: cus_123 + expand: + - invoices + - entities + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: Your unique identifier for the customer. + name: + anyOf: + - type: string + - type: "null" + description: The name of the customer. + email: + anyOf: + - type: string + - type: "null" + description: The email address of the customer. + created_at: + type: number + description: Timestamp of customer creation in milliseconds since epoch. + fingerprint: + anyOf: + - type: string + - type: "null" + description: "A unique identifier (eg. serial number) to de-duplicate customers + across devices or browsers. For example: apple device ID." + stripe_id: + anyOf: + - type: string + - type: "null" + description: Stripe customer ID. + env: + enum: + - sandbox + - live + type: string + description: The environment this customer was created in. + metadata: + type: object + propertyNames: {} + additionalProperties: {} + description: The metadata for the customer. + send_email_receipts: + type: boolean + description: Whether to send email receipts to the customer. + billing_controls: + type: object + properties: + auto_topups: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature (credit balance) to auto top-up. + enabled: + type: boolean + default: false + description: Whether auto top-up is enabled. + threshold: + type: number + minimum: 0 + description: When the balance drops below this threshold, an auto top-up will be + purchased. + quantity: + type: number + minimum: 1 + description: Amount of credits to add per auto top-up. + purchase_limit: + anyOf: + - type: object + properties: + interval: + enum: + - hour + - day + - week + - month + type: string + description: The time interval for the purchase limit window. + interval_count: + type: number + minimum: 1 + default: 1 + description: Number of intervals in the purchase limit window. + limit: + type: number + minimum: 1 + description: Maximum number of auto top-ups allowed within the interval. + required: + - interval + - limit + - type: object + properties: + interval: + anyOf: + - enum: + - hour + - day + - week + - month + type: string + - type: "null" + description: The time interval for the purchase limit window. Null when no + purchase limit is configured. + interval_count: + anyOf: + - type: number + minimum: 1 + - type: "null" + description: Number of intervals in the purchase limit window. Null when no + purchase limit is configured. + limit: + anyOf: + - type: number + minimum: 1 + - type: "null" + description: Maximum number of auto top-ups allowed within the interval. Null + when no purchase limit is configured. + count: + type: number + description: Number of auto top-ups already consumed in the current window. + next_reset_at: + type: number + description: Unix ms timestamp when the current purchase window ends and the + count resets. + required: + - interval + - interval_count + - limit + - count + - next_reset_at + description: Optional rate limit to cap how often auto top-ups occur. Expand + billing_controls.auto_topups.purchase_limit for + a count of top ups and the next_reset_at. + invoice_mode: + type: boolean + description: When true, auto top-up creates a send_invoice invoice instead of + auto-charging. + required: + - feature_id + - threshold + - quantity + description: List of auto top-up configurations per feature. + spend_limits: + type: array + items: + type: object + properties: + feature_id: + type: string + description: Optional feature ID this spend limit applies to. + enabled: + type: boolean + default: false + description: Whether this spend limit is enabled. + overage_limit: + type: number + minimum: 0 + description: Maximum allowed overage spend for the target feature. + description: List of overage spend limits per feature. + usage_alerts: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this alert applies to. + enabled: + type: boolean + default: true + description: Whether this usage alert is enabled. + threshold: + type: number + minimum: 0 + description: The threshold value that triggers the alert. For usage or + remaining, this is an absolute count. For + usage_percentage or remaining_percentage, this + is a percentage (0-100). + threshold_type: + enum: + - usage + - usage_percentage + - remaining + - remaining_percentage + type: string + description: Whether the threshold is an absolute count or a percentage of the + usage allowance or remaining balance. + name: + type: string + description: Optional user-defined label to distinguish multiple alerts on the + same feature. + required: + - threshold + - threshold_type + description: List of usage alert configurations per feature. + overage_allowed: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The feature ID this overage allowed control applies to. + enabled: + type: boolean + default: false + description: Whether overage is allowed for this feature. + required: + - feature_id + description: List of overage allowed controls per feature. When enabled, usage + can exceed balance. + description: Billing controls for the customer (auto top-ups, etc.) + subscriptions: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier of this subscription. If a subscription_id + was provided at attach time, it is used; otherwise, + falls back to the internal ID. + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the subscribed plan. + auto_enable: + type: boolean + description: Whether the plan was automatically enabled for the customer. + add_on: + type: boolean + description: Whether this is an add-on plan rather than a base subscription. + status: + enum: + - active + - scheduled + type: string + description: Current status of the subscription. + past_due: + type: boolean + description: Whether the subscription has overdue payments. + canceled_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription was canceled, or null if not + canceled. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the subscription will expire, or null if no expiry + set. + trial_ends_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the trial period ends, or null if not on trial. + started_at: + type: number + description: Timestamp when the subscription started. + current_period_start: + anyOf: + - type: number + - type: "null" + description: Start timestamp of the current billing period. + current_period_end: + anyOf: + - type: number + - type: "null" + description: End timestamp of the current billing period. + quantity: + type: number + description: Number of units of this subscription (for per-seat plans). + required: + - id + - plan_id + - auto_enable + - add_on + - status + - past_due + - canceled_at + - expires_at + - trial_ends_at + - started_at + - current_period_start + - current_period_end + - quantity + description: Active and scheduled recurring plans that this customer has + attached. + purchases: + type: array + items: + type: object + properties: + plan: + $ref: "#/components/schemas/Plan" + description: The full plan object if expanded. + plan_id: + type: string + description: The unique identifier of the purchased plan. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when the purchase expires, or null for lifetime access. + started_at: + type: number + description: Timestamp when the purchase was made. + quantity: + type: number + description: Number of units purchased. + required: + - plan_id + - expires_at + - started_at + - quantity + description: One-time purchases made by the customer. + balances: + type: object + propertyNames: + type: string + additionalProperties: + $ref: "#/components/schemas/Balance" + description: Feature balances keyed by feature ID, showing usage limits and + remaining amounts. + flags: + type: object + propertyNames: + type: string + additionalProperties: + type: object + properties: + id: + type: string + description: The unique identifier for this flag. + plan_id: + anyOf: + - type: string + - type: "null" + description: The plan ID this flag originates from, or null for standalone + flags. + expires_at: + anyOf: + - type: number + - type: "null" + description: Timestamp when this flag expires, or null for no expiration. + feature_id: + type: string + description: The feature ID this flag is for. + feature: + type: object + properties: + id: + type: string + description: The unique identifier for this feature, used in /check and /track + calls. + name: + type: string + description: Human-readable name displayed in the dashboard and billing UI. + type: + enum: + - boolean + - metered + - credit_system + type: string + description: "Feature type: 'boolean' for on/off access, 'metered' for + usage-tracked features, 'credit_system' for + unified credit pools." + consumable: + type: boolean + description: "For metered features: true if usage resets periodically (API + calls, credits), false if allocated persistently + (seats, storage)." + event_names: + type: array + items: + type: string + description: Event names that trigger this feature's balance. Allows multiple + features to respond to a single event. + credit_schema: + type: array + items: + type: object + properties: + metered_feature_id: + type: string + description: ID of the metered feature that draws from this credit system. + credit_cost: + type: number + description: Credits consumed per unit of the metered feature. + required: + - metered_feature_id + - credit_cost + description: "For credit_system features: maps metered features to their credit + costs." + display: + type: object + properties: + singular: + anyOf: + - type: string + - type: "null" + description: Singular form for UI display (e.g., 'API call', 'seat'). + plural: + anyOf: + - type: string + - type: "null" + description: Plural form for UI display (e.g., 'API calls', 'seats'). + description: Display names for the feature in billing UI and customer-facing + components. + archived: + type: boolean + description: Whether the feature is archived and hidden from the dashboard. + required: + - id + - name + - type + - consumable + - archived + description: The full feature object if expanded. + required: + - id + - plan_id + - expires_at + - feature_id + examples: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + plan_id: pro_plan + expires_at: null + feature_id: dashboard + description: Boolean feature flags keyed by feature ID, showing enabled access + for on/off features. + config: + type: object + properties: + disable_pooled_balance: + type: boolean + description: Whether to disable the shared customer-level pool for entities. + description: Configuration for the customer. + 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 customer. + entities: + type: array + items: + type: object + properties: + id: + anyOf: + - type: string + - type: "null" + description: The unique identifier of the entity + name: + anyOf: + - type: string + - type: "null" + description: The name of the entity + customer_id: + anyOf: + - type: string + - type: "null" + description: The customer ID this entity belongs to + feature_id: + anyOf: + - type: string + - type: "null" + description: The feature ID this entity belongs to + created_at: + type: number + description: Unix timestamp when the entity was created + env: + enum: + - sandbox + - live + type: string + description: The environment (sandbox/live) + required: + - id + - name + - created_at + - env + description: Entities associated with this customer. + trials_used: + type: array + items: + type: object + properties: + plan_id: + type: string + customer_id: + type: string + fingerprint: + anyOf: + - type: string + - type: "null" + required: + - plan_id + - customer_id + description: Trial usage history for this customer. + rewards: + anyOf: + - type: object + properties: + discounts: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier for this discount + name: + type: string + description: The name of the discount or coupon + type: + enum: + - percentage_discount + - fixed_discount + - free_product + - invoice_credits + type: string + description: The type of reward + discount_value: + type: number + description: The discount value (percentage or fixed amount) + duration_type: + enum: + - one_off + - months + - forever + type: string + description: How long the discount lasts + duration_value: + anyOf: + - type: number + - type: "null" + description: Number of billing periods the discount applies for repeating + durations + currency: + anyOf: + - type: string + - type: "null" + description: The currency code for fixed amount discounts + start: + anyOf: + - type: number + - type: "null" + description: Timestamp when the discount becomes active + end: + anyOf: + - type: number + - type: "null" + description: Timestamp when the discount expires + subscription_id: + anyOf: + - type: string + - type: "null" + description: The Stripe subscription ID this discount is applied to + total_discount_amount: + anyOf: + - type: number + - type: "null" + description: Total amount saved from this discount + required: + - id + - name + - type + - discount_value + - duration_type + description: Array of active discounts applied to the customer + required: + - discounts + - type: "null" + description: Rewards earned or applied for this customer. + referrals: + type: array + items: + type: object + properties: + program_id: + type: string + customer: + type: object + properties: + id: + type: string + name: + anyOf: + - type: string + - type: "null" + email: + anyOf: + - type: string + - type: "null" + required: + - id + reward_applied: + type: boolean + created_at: + type: number + required: + - program_id + - customer + - reward_applied + - created_at + description: Referral records for this customer. + payment_method: + anyOf: + - {} + - type: "null" + description: The customer's default payment method. + required: + - id + - name + - email + - created_at + - fingerprint + - stripe_id + - env + - metadata + - send_email_receipts + - billing_controls + - subscriptions + - purchases + - balances + - flags + examples: + - id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58 + name: Patrick + email: patrick@useautumn.com + createdAt: 1771409161016 + fingerprint: null + stripeId: cus_U0BKxpq1mFhuJO + env: sandbox + metadata: {} + sendEmailReceipts: false + billingControls: + autoTopups: [] + subscriptions: + - planId: pro_plan + autoEnable: true + addOn: false + status: active + pastDue: false + canceledAt: null + expiresAt: null + trialEndsAt: null + startedAt: 1771431921437 + currentPeriodStart: 1771431921437 + currentPeriodEnd: 1771999921437 + quantity: 1 + purchases: [] + balances: + messages: + featureId: messages + granted: 100 + remaining: 0 + usage: 100 + unlimited: false + overageAllowed: false + maxPurchase: null + nextResetAt: 1773851121437 + breakdown: + - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV + planId: pro_plan + includedGrant: 100 + prepaidGrant: 0 + remaining: 0 + usage: 100 + unlimited: false + reset: + interval: month + resetsAt: 1773851121437 + price: null + expiresAt: null + flags: + advanced_workflows: + id: cus_ent_abc123 + plan_id: pro_plan + expires_at: null + feature_id: advanced_workflows + config: + disable_pooled_balance: false + x-speakeasy-name-override: get + parameters: + - *a1 /v1/customers.list: post: operationId: listCustomers @@ -6865,6 +7667,10 @@ paths: current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) + @param startsAt - Unix timestamp in milliseconds for when the attached + plan should start. Future dates create a scheduled subscription. + (optional) + @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @@ -7239,6 +8045,12 @@ paths: 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -7401,6 +8213,721 @@ paths: x-speakeasy-name-override: attach parameters: - *a1 + /v1/billing.create_schedule: + post: + operationId: createSchedule + description: |- + Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times. + + Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time. + + @example + ```typescript + // Schedule a transition from a trial plan to a paid plan + const response = await client.billing.createSchedule({ customerId: "cus_123", phases: [{"startsAt":1778065018741,"plans":[{"planId":"trial_plan"}]},{"startsAt":1779274618741,"plans":[{"planId":"pro_plan"}]}] }); + ``` + + @param customerId - The ID of the customer to create the schedule for. + @param entityId - Optional entity ID for an entity-scoped schedule. (optional) + @param invoiceMode - Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. (optional) + @param successUrl - URL to redirect to after successful checkout. (optional) + @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) + @param redirectMode - Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if_required' only redirects when needed, and 'never' disables redirects. (optional) + @param billingBehavior - Whether to prorate the immediate phase. 'none' skips proration charges and credits. (optional) + @param billingCycleAnchor - Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time. (optional) + @param enablePlanImmediately - If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed. (optional) + @param phases - Ordered phase definitions for the schedule. + + @returns A create-schedule response with the schedule ID, persisted phases, and any required payment or checkout URL. + tags: + - billing + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer to create the schedule for. + entity_id: + type: string + description: Optional entity ID for an entity-scoped schedule. + invoice_mode: + type: object + properties: + enabled: + type: boolean + description: When true, creates an invoice and sends it to the customer instead + of charging their card immediately. Uses Stripe's + send_invoice collection method. + enable_plan_immediately: + type: boolean + default: false + description: If true, enables the plan immediately even though the invoice is + not paid yet. + finalize: + type: boolean + default: true + description: If true, finalizes the invoice so it can be sent to the customer. + If false, keeps it as a draft for manual review. + required: + - enabled + description: Invoice mode creates and sends an invoice instead of charging the + customer's payment method immediately for the first phase. + success_url: + type: string + description: URL to redirect to after successful checkout. + checkout_session_params: + type: object + propertyNames: + type: string + additionalProperties: {} + description: Additional parameters to pass into the creation of the Stripe + checkout session. + redirect_mode: + enum: + - always + - if_required + - never + type: string + description: Controls when to return a checkout URL for the immediate phase. + 'always' forces a confirmation or checkout flow, + 'if_required' only redirects when needed, and 'never' + disables redirects. + default: if_required + billing_behavior: + enum: + - prorate_immediately + - none + type: string + description: Whether to prorate the immediate phase. 'none' skips proration + charges and credits. + billing_cycle_anchor: + const: now + description: Pass 'now' to reset the billing cycle anchor of the immediate phase + to the current time. + enable_plan_immediately: + type: boolean + description: If true, the immediate-phase cusProducts are activated immediately + (and scheduled-phase cusProducts pre-inserted) even when + payment is pending via Stripe checkout. The Autumn schedule + rows are persisted on checkout.session.completed. + phases: + type: array + prefixItems: + - type: object + properties: + starts_at: + type: number + description: When this phase should start, in epoch milliseconds. + plans: + type: array + minItems: 1 + items: + type: object + properties: + plan_id: + type: string + description: The ID of the plan to schedule in this phase. + feature_quantities: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to set quantity for. + quantity: + type: number + minimum: 0 + description: The quantity of the feature. + adjustable: + type: boolean + description: Whether the customer can adjust the quantity. + required: + - feature_id + title: FeatureQuantity + description: Quantity configuration for a prepaid feature. + description: Optional prepaid feature quantities for this phase's plan. + version: + type: number + description: Optional explicit plan version to schedule. + customize: + type: object + properties: + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Base price amount for the plan. + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval (e.g. 'month', 'year'). + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + required: + - amount + - interval + title: BasePrice + description: Base price configuration for a plan. + - type: "null" + description: Override the base price of the plan. Pass null to remove the base + price. + items: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to configure. + included: + type: number + description: Number of free units included. Balance resets to this each interval + for consumable features. + unlimited: + type: boolean + description: If true, customer has unlimited access to this feature. + reset: + type: object + properties: + interval: + enum: + - one_off + - minute + - hour + - day + - week + - month + - quarter + - semi_annual + - year + type: string + description: Interval at which balance resets (e.g. 'month', 'year'). For + consumable features only. + interval_count: + type: number + description: Number of intervals between resets. Defaults to 1. + required: + - interval + description: Reset configuration for consumable features. Omit for + non-consumable features like seats. + price: + type: object + properties: + amount: + type: number + description: Price per billing_units after included usage. Either 'amount' or + 'tiers' is required. + tiers: + type: array + items: + type: object + properties: + to: {} + amount: {} + flat_amount: {} + description: Tiered pricing. Either 'amount' or 'tiers' is required. + tier_behavior: + enum: + - graduated + - volume + type: string + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval. For consumable features, should match + reset.interval. + interval_count: + type: number + default: 1 + description: Number of intervals per billing cycle. Defaults to 1. + billing_units: + type: number + default: 1 + description: Units per price increment. Usage is rounded UP when billed (e.g. + billing_units=100 means 101 + rounds to 200). + billing_method: + enum: + - prepaid + - usage_based + type: string + description: "'prepaid' for upfront payment (seats), 'usage_based' for + pay-as-you-go." + max_purchase: + type: number + description: Max units purchasable beyond included. E.g. included=100, + max_purchase=300 allows 400 + total. + required: + - interval + - billing_method + description: Pricing for usage beyond included units. Omit for free features. + proration: + type: object + properties: + on_increase: + enum: + - bill_immediately + - prorate_immediately + - prorate_next_cycle + - bill_next_cycle + type: string + description: Billing behavior when quantity increases mid-cycle. + on_decrease: + enum: + - prorate + - prorate_immediately + - prorate_next_cycle + - none + - no_prorations + type: string + description: Credit behavior when quantity decreases mid-cycle. + required: + - on_increase + - on_decrease + description: Proration settings for prepaid features. Controls mid-cycle + quantity change billing. + rollover: + type: object + properties: + max: + type: number + description: Max rollover units. Omit for unlimited rollover. + max_percentage: + type: number + description: Maximum rollover as a percentage (0-100) of included + prepaid + grant. Mutually exclusive with + max. + expiry_duration_type: + enum: + - month + - forever + type: string + description: When rolled over units expire. + expiry_duration_length: + type: number + description: Number of periods before expiry. + required: + - expiry_duration_type + description: Rollover config for unused units. If set, unused included units + carry over. + required: + - feature_id + title: PlanItem + description: Configuration for a feature item in a plan, including usage limits, + pricing, and rollover settings. + description: Override the items in the plan. + additionalProperties: false + description: Customize the plan to schedule. Can override the price, items, or + both. + subscription_id: + type: string + description: Unsupported for create_schedule today. Requests that include this + field will be rejected. + required: + - plan_id + description: Plans to materialize for this phase. + required: + - starts_at + - plans + items: + type: object + properties: + starts_at: + type: number + description: When this phase should start, in epoch milliseconds. + plans: + type: array + minItems: 1 + items: + type: object + properties: + plan_id: + type: string + description: The ID of the plan to schedule in this phase. + feature_quantities: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to set quantity for. + quantity: + type: number + minimum: 0 + description: The quantity of the feature. + adjustable: + type: boolean + description: Whether the customer can adjust the quantity. + required: + - feature_id + title: FeatureQuantity + description: Quantity configuration for a prepaid feature. + description: Optional prepaid feature quantities for this phase's plan. + version: + type: number + description: Optional explicit plan version to schedule. + customize: + type: object + properties: + price: + anyOf: + - type: object + properties: + amount: + type: number + description: Base price amount for the plan. + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval (e.g. 'month', 'year'). + interval_count: + type: number + description: Number of intervals per billing cycle. Defaults to 1. + required: + - amount + - interval + title: BasePrice + description: Base price configuration for a plan. + - type: "null" + description: Override the base price of the plan. Pass null to remove the base + price. + items: + type: array + items: + type: object + properties: + feature_id: + type: string + description: The ID of the feature to configure. + included: + type: number + description: Number of free units included. Balance resets to this each interval + for consumable features. + unlimited: + type: boolean + description: If true, customer has unlimited access to this feature. + reset: + type: object + properties: + interval: + enum: + - one_off + - minute + - hour + - day + - week + - month + - quarter + - semi_annual + - year + type: string + description: Interval at which balance resets (e.g. 'month', 'year'). For + consumable features only. + interval_count: + type: number + description: Number of intervals between resets. Defaults to 1. + required: + - interval + description: Reset configuration for consumable features. Omit for + non-consumable features like seats. + price: + type: object + properties: + amount: + type: number + description: Price per billing_units after included usage. Either 'amount' or + 'tiers' is required. + tiers: + type: array + items: + type: object + properties: + to: {} + amount: {} + flat_amount: {} + description: Tiered pricing. Either 'amount' or 'tiers' is required. + tier_behavior: + enum: + - graduated + - volume + type: string + interval: + enum: + - one_off + - week + - month + - quarter + - semi_annual + - year + type: string + description: Billing interval. For consumable features, should match + reset.interval. + interval_count: + type: number + default: 1 + description: Number of intervals per billing cycle. Defaults to 1. + billing_units: + type: number + default: 1 + description: Units per price increment. Usage is rounded UP when billed (e.g. + billing_units=100 means 101 rounds + to 200). + billing_method: + enum: + - prepaid + - usage_based + type: string + description: "'prepaid' for upfront payment (seats), 'usage_based' for + pay-as-you-go." + max_purchase: + type: number + description: Max units purchasable beyond included. E.g. included=100, + max_purchase=300 allows 400 total. + required: + - interval + - billing_method + description: Pricing for usage beyond included units. Omit for free features. + proration: + type: object + properties: + on_increase: + enum: + - bill_immediately + - prorate_immediately + - prorate_next_cycle + - bill_next_cycle + type: string + description: Billing behavior when quantity increases mid-cycle. + on_decrease: + enum: + - prorate + - prorate_immediately + - prorate_next_cycle + - none + - no_prorations + type: string + description: Credit behavior when quantity decreases mid-cycle. + required: + - on_increase + - on_decrease + description: Proration settings for prepaid features. Controls mid-cycle + quantity change billing. + rollover: + type: object + properties: + max: + type: number + description: Max rollover units. Omit for unlimited rollover. + max_percentage: + type: number + description: Maximum rollover as a percentage (0-100) of included + prepaid + grant. Mutually exclusive with + max. + expiry_duration_type: + enum: + - month + - forever + type: string + description: When rolled over units expire. + expiry_duration_length: + type: number + description: Number of periods before expiry. + required: + - expiry_duration_type + description: Rollover config for unused units. If set, unused included units + carry over. + required: + - feature_id + title: PlanItem + description: Configuration for a feature item in a plan, including usage limits, + pricing, and rollover settings. + description: Override the items in the plan. + additionalProperties: false + description: Customize the plan to schedule. Can override the price, items, or + both. + subscription_id: + type: string + description: Unsupported for create_schedule today. Requests that include this + field will be rejected. + required: + - plan_id + description: Plans to materialize for this phase. + required: + - starts_at + - plans + description: Ordered phase definitions for the schedule. + required: + - customer_id + - phases + title: CreateScheduleParams + examples: + - customer_id: cus_123 + phases: + - starts_at: 1735689600000 + plans: + - plan_id: trial_plan + - starts_at: 1736899200000 + plans: + - plan_id: pro_plan + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + customer_id: + type: string + description: The ID of the customer. + entity_id: + anyOf: + - type: string + - type: "null" + description: The entity ID for the schedule, or null when customer-level. + status: + enum: + - created + - pending_payment + type: string + description: Whether the schedule is fully created or waiting for payment or + confirmation to complete. + schedule_id: + anyOf: + - type: string + - type: "null" + description: The ID of the created schedule. Null when the schedule is waiting + on Autumn checkout confirmation. + phases: + type: array + items: + type: object + properties: + phase_id: + type: string + description: The ID of the persisted phase row. + starts_at: + type: number + description: When this phase starts, in epoch milliseconds. + customer_product_ids: + type: array + items: + type: string + description: Customer products materialized for this phase. + required: + - phase_id + - starts_at + - customer_product_ids + description: Persisted phases in ascending starts_at order. Empty when waiting + on Autumn checkout confirmation. + invoice: + type: object + properties: + status: + anyOf: + - type: string + - type: "null" + description: The status of the invoice (e.g., 'paid', 'open', 'draft'). + stripe_id: + type: string + description: The Stripe invoice ID. + total: + type: number + description: The total amount of the invoice in cents. + currency: + type: string + description: The three-letter ISO currency code (e.g., 'usd'). + hosted_invoice_url: + anyOf: + - type: string + - type: "null" + description: URL to the hosted invoice page where the customer can view and pay + the invoice. + required: + - status + - stripe_id + - total + - currency + - hosted_invoice_url + description: Invoice details if an invoice was created. Only present when a + charge was made. + payment_url: + anyOf: + - type: string + - type: "null" + description: URL to redirect the customer to complete payment. Null if no + payment action is required. + required_action: + type: object + properties: + code: + enum: + - 3ds_required + - payment_method_required + - payment_failed + type: string + description: The type of action required to complete the payment. + reason: + type: string + description: A human-readable explanation of why this action is required. + required: + - code + - reason + required: + - customer_id + - entity_id + - status + - schedule_id + - phases + - payment_url + title: CreateScheduleResponse + examples: + - customer_id: cus_123 + entity_id: null + status: created + schedule_id: sch_1234 + phases: + - phase_id: sphs_1111 + starts_at: 1735689600000 + customer_product_ids: + - cus_prod_1111 + - phase_id: sphs_2222 + starts_at: 1736899200000 + customer_product_ids: + - cus_prod_2222 + invoice: null + payment_url: null + x-speakeasy-name-override: createSchedule + parameters: + - *a1 /v1/billing.multi_attach: post: operationId: multiAttach @@ -8033,6 +9560,10 @@ paths: current billing cycle. By default, upgrades are immediate and downgrades are scheduled. (optional) + @param startsAt - Unix timestamp in milliseconds for when the attached + plan should start. Future dates create a scheduled subscription. + (optional) + @param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional) @@ -8407,6 +9938,12 @@ paths: 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -8517,10 +10054,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -8572,12 +10110,12 @@ paths: - quantity subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -8589,10 +10127,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -8608,10 +10148,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -8857,6 +10398,20 @@ paths: description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -9369,10 +10924,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -9424,12 +10980,12 @@ paths: - quantity subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -9441,10 +10997,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -9460,10 +11018,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -9709,6 +11268,20 @@ paths: description: Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -10741,10 +12314,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -10797,12 +12371,12 @@ paths: description: List of line items for the current billing period. subtotal: type: number - description: The total amount in cents before discounts for the current billing - period. + description: The total amount in cents before discounts and tax for the current + billing period. total: type: number - description: The final amount in cents after discounts for the current billing - period. + description: The final amount in cents after discounts and tax for the current + billing period. currency: type: string description: The three-letter ISO currency code (e.g., 'usd'). @@ -10814,10 +12388,12 @@ paths: description: Unix timestamp (milliseconds) when the next billing cycle starts. subtotal: type: number - description: The total amount in cents before discounts for the next cycle. + description: The total amount in cents before discounts and tax for the next + cycle. total: type: number - description: The final amount in cents after discounts for the next cycle. + description: The final amount in cents after discounts and tax for the next + cycle. line_items: type: array items: @@ -10833,10 +12409,11 @@ paths: description: A detailed description of the line item. subtotal: type: number - description: The amount in cents before discounts for this line item. + description: The amount in cents before discounts and tax for this line item. total: type: number - description: The final amount in cents after discounts for this line item. + description: The final amount in cents after discounts and tax for this line + item. discounts: type: array items: @@ -11047,6 +12624,51 @@ paths: - uncancel - none type: string + tax: + type: object + properties: + total: + type: number + description: Total tax amount in major currency units. + amount_inclusive: + type: number + description: Tax included in line item subtotals. + amount_exclusive: + type: number + description: Tax added on top of subtotals. + currency: + type: string + description: Three-letter currency code. + status: + enum: + - complete + - incomplete + type: string + description: Calculation status ('complete' when Stripe Tax succeeds or + 'incomplete' when Stripe Tax returned 0 or errored). + required: + - total + - amount_inclusive + - amount_exclusive + - currency + - status + description: Tax preview for the immediate charge. Contact us to enable the tax + flag on your organisation. Shows only with flag enabled, a + Stripe customer exists and has a location. + invoice_credits: + type: object + properties: + balance: + type: number + description: Stripe customer credit balance available, expressed as a positive + number in major currency units. + currency: + type: string + description: Three-letter currency code. + required: + - balance + - currency + description: Stripe customer invoice credits preview. required: - customer_id - line_items @@ -11424,6 +13046,12 @@ paths: billing_cycle_anchor: const: now description: Reset the billing cycle anchor immediately with 'now'. + starts_at: + type: integer + minimum: 0 + maximum: 9007199254740991 + description: Unix timestamp in milliseconds for when the attached plan should + start. Future dates create a scheduled subscription. checkout_session_params: type: object propertyNames: @@ -15593,6 +17221,118 @@ webhooks: responses: "200": description: Webhook received successfully. + billing.auto_topup_succeeded: + post: + operationId: billingAutoTopupSucceeded + summary: Auto Top-Up Succeeded + description: Fired when an automatic top-up grants additional prepaid balance. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - type + - data + properties: + type: + type: string + const: billing.auto_topup_succeeded + description: The webhook event type. + data: + examples: + - customer_id: cus_123 + feature_id: messages + quantity_granted: 100 + threshold: 20 + balance_after: 115 + invoice_mode: false + invoice: + stripe_id: in_1A2B3C4D5E6F7G8H + status: paid + total: 1000 + currency: usd + hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 + type: object + properties: + customer_id: + description: The ID of the customer whose balance was topped up. + type: string + feature_id: + description: The feature ID that was automatically topped up. + type: string + quantity_granted: + description: The normalized amount of balance granted by the top-up. + type: number + threshold: + description: The configured balance threshold that triggered the top-up. + type: number + balance_after: + description: The customer's remaining balance for the feature after the top-up. + type: number + invoice_mode: + description: Whether the auto top-up created a send_invoice invoice instead of + auto-charging. + type: boolean + invoice: + description: The invoice created for the auto top-up. + type: object + properties: + stripe_id: + description: The Stripe invoice ID. Use this as a stable dedupe key. + type: string + status: + description: The status of the invoice. "paid" for auto-charged top-ups; "open" + for invoice-mode top-ups where credits were granted + but the invoice has not yet been paid. + anyOf: + - type: string + - type: "null" + total: + description: The total amount of the invoice in the smallest currency unit (e.g. + cents for USD), matching Stripe's invoice.total. + type: number + currency: + description: The ISO currency code for the invoice. + type: string + hosted_invoice_url: + description: URL to the hosted invoice page, if available. + anyOf: + - type: string + - type: "null" + required: + - stripe_id + - total + - currency + additionalProperties: false + required: + - customer_id + - feature_id + - quantity_granted + - threshold + - balance_after + - invoice_mode + - invoice + additionalProperties: false + example: + type: billing.auto_topup_succeeded + data: + customer_id: cus_123 + feature_id: messages + quantity_granted: 100 + threshold: 20 + balance_after: 115 + invoice_mode: false + invoice: + stripe_id: in_1A2B3C4D5E6F7G8H + status: paid + total: 1000 + currency: usd + hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456 + responses: + "200": + description: Webhook received successfully. vercel.resources.deleted: post: operationId: vercelResourcesDeleted diff --git a/packages/openapi/v2.1/contracts/billingContract.ts b/packages/openapi/v2.1/contracts/billingContract.ts index e235f199f..a2eff2433 100644 --- a/packages/openapi/v2.1/contracts/billingContract.ts +++ b/packages/openapi/v2.1/contracts/billingContract.ts @@ -2,6 +2,8 @@ import { AttachParamsV1Schema, BILLING_PREVIEW_RESPONSE_EXAMPLE, BillingResponseSchema, + CreateScheduleParamsV0Schema, + CreateScheduleResponseSchema, ExtAttachPreviewResponseSchema, ExtPreviewUpdateSubscriptionResponseSchema, ExtUpdateSubscriptionV1ParamsSchema, @@ -14,6 +16,7 @@ import { import { oc } from "@orpc/contract"; import { billingAttachJsDoc, + billingCreateScheduleJsDoc, billingMultiAttachJsDoc, billingPreviewAttachJsDoc, billingPreviewMultiAttachJsDoc, @@ -227,6 +230,66 @@ export const billingSetupPaymentContract = oc }), ); +export const billingCreateScheduleContract = oc + .route({ + method: "POST", + path: "/v1/billing.create_schedule", + operationId: "createSchedule", + tags: ["billing"], + description: billingCreateScheduleJsDoc, + spec: (spec) => ({ + ...spec, + "x-speakeasy-name-override": "createSchedule", + }), + }) + .input( + CreateScheduleParamsV0Schema.meta({ + title: "CreateScheduleParams", + examples: [ + { + customer_id: "cus_123", + phases: [ + { + starts_at: 1735689600000, + plans: [{ plan_id: "trial_plan" }], + }, + { + starts_at: 1736899200000, + plans: [{ plan_id: "pro_plan" }], + }, + ], + }, + ], + }), + ) + .output( + CreateScheduleResponseSchema.meta({ + title: "CreateScheduleResponse", + examples: [ + { + customer_id: "cus_123", + entity_id: null, + status: "created", + schedule_id: "sch_1234", + phases: [ + { + phase_id: "sphs_1111", + starts_at: 1735689600000, + customer_product_ids: ["cus_prod_1111"], + }, + { + phase_id: "sphs_2222", + starts_at: 1736899200000, + customer_product_ids: ["cus_prod_2222"], + }, + ], + invoice: null, + payment_url: null, + }, + ], + }), + ); + export const billingMultiAttachContract = oc .route({ method: "POST", diff --git a/packages/openapi/v2.1/contracts/customersContract.ts b/packages/openapi/v2.1/contracts/customersContract.ts index 60e97e3c3..bea4f3dc4 100644 --- a/packages/openapi/v2.1/contracts/customersContract.ts +++ b/packages/openapi/v2.1/contracts/customersContract.ts @@ -9,10 +9,14 @@ import { DeleteCustomerParamsSchema, DeleteCustomerResponseSchema, } from "@api/customers/crud/deleteCustomerParams.js"; +import { GetCustomerParamsV1Schema } from "@api/customers/crud/getCustomerParams.js"; import { ListCustomersV2ParamsSchema } from "@api/customers/crud/listCustomersParamsV2.js"; import { UpdateCustomerParamsV1Schema } from "@api/customers/crud/updateCustomerParams.js"; import { oc } from "@orpc/contract"; -import { getOrCreateCustomerJsDoc } from "../jsDocs/customerJsDocs"; +import { + getCustomerJsDoc, + getOrCreateCustomerJsDoc, +} from "../jsDocs/customerJsDocs"; export const getOrCreateCustomerContract = oc .route({ @@ -40,6 +44,38 @@ export const getOrCreateCustomerContract = oc ) .output(ApiCustomerV5Schema); +export const getCustomerContract = oc + .route({ + method: "POST", + path: "/v1/customers.get", + operationId: "getCustomer", + tags: ["customers"], + description: getCustomerJsDoc, + spec: (spec) => ({ + ...spec, + "x-speakeasy-name-override": "get", + }), + }) + .input( + GetCustomerParamsV1Schema.meta({ + title: "GetCustomerParams", + examples: [ + { + customer_id: "cus_123", + }, + { + customer_id: "cus_123", + expand: ["invoices", "entities"], + }, + ], + }), + ) + .output( + ApiCustomerV5Schema.meta({ + examples: [API_CUSTOMER_V5_EXAMPLE], + }), + ); + export const listCustomersContract = oc .route({ method: "POST", diff --git a/packages/openapi/v2.1/contracts/index.ts b/packages/openapi/v2.1/contracts/index.ts index 48745bece..02c03004c 100644 --- a/packages/openapi/v2.1/contracts/index.ts +++ b/packages/openapi/v2.1/contracts/index.ts @@ -9,6 +9,7 @@ import { } from "./balancesContract.js"; import { billingAttachContract, + billingCreateScheduleContract, billingMultiAttachContract, billingOpenCustomerPortalContract, billingPreviewAttachContract, @@ -19,6 +20,7 @@ import { } from "./billingContract.js"; import { deleteCustomerContract, + getCustomerContract, getOrCreateCustomerContract, listCustomersContract, updateCustomerContract, @@ -55,6 +57,7 @@ import { export const v2_1ContractRouter = oc.router({ // Customers getOrCreateCustomer: getOrCreateCustomerContract, + getCustomer: getCustomerContract, listCustomers: listCustomersContract, updateCustomer: updateCustomerContract, deleteCustomer: deleteCustomerContract, @@ -75,6 +78,7 @@ export const v2_1ContractRouter = oc.router({ // Billing billingAttach: billingAttachContract, + billingCreateSchedule: billingCreateScheduleContract, billingMultiAttach: billingMultiAttachContract, billingPreviewAttach: billingPreviewAttachContract, billingPreviewMultiAttach: billingPreviewMultiAttachContract, diff --git a/packages/openapi/v2.1/jsDocs/billingJsDocs.ts b/packages/openapi/v2.1/jsDocs/billingJsDocs.ts index 4b7ca991c..f4d19d08f 100644 --- a/packages/openapi/v2.1/jsDocs/billingJsDocs.ts +++ b/packages/openapi/v2.1/jsDocs/billingJsDocs.ts @@ -1,5 +1,6 @@ import { AttachParamsV1Schema, + CreateScheduleParamsV0Schema, MultiAttachParamsV0Schema, UpdateSubscriptionV1ParamsSchema, } from "@autumn/shared"; @@ -179,6 +180,35 @@ export const billingMultiAttachJsDoc = createJSDocDescription({ "A billing response with customer ID, invoice details, and payment URL (if checkout required).", }); +export const billingCreateScheduleJsDoc = createJSDocDescription({ + description: + "Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times.", + whenToUse: + "Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time.", + body: CreateScheduleParamsV0Schema, + examples: [ + example({ + description: "Schedule a transition from a trial plan to a paid plan", + values: { + customerId: "cus_123", + phases: [ + { + startsAt: Date.now(), + plans: [{ planId: "trial_plan" }], + }, + { + startsAt: Date.now() + 14 * 24 * 60 * 60 * 1000, + plans: [{ planId: "pro_plan" }], + }, + ], + }, + }), + ], + methodName: "billing.createSchedule", + returns: + "A create-schedule response with the schedule ID, persisted phases, and any required payment or checkout URL.", +}); + export const billingPreviewMultiAttachJsDoc = createJSDocDescription({ description: "Previews the billing changes that would occur when attaching multiple plans, without actually making any changes.", diff --git a/packages/openapi/v2.1/jsDocs/customerJsDocs.ts b/packages/openapi/v2.1/jsDocs/customerJsDocs.ts index b530024a4..26047b9a1 100644 --- a/packages/openapi/v2.1/jsDocs/customerJsDocs.ts +++ b/packages/openapi/v2.1/jsDocs/customerJsDocs.ts @@ -1,4 +1,7 @@ -import { CreateCustomerParamsV0Schema } from "@autumn/shared"; +import { + CreateCustomerParamsV0Schema, + GetCustomerParamsV1Schema, +} from "@autumn/shared"; import { createJSDocDescription, example } from "../../utils/jsDocs/index.js"; export const getOrCreateCustomerJsDoc = createJSDocDescription({ @@ -19,3 +22,27 @@ export const getOrCreateCustomerJsDoc = createJSDocDescription({ ], methodName: "getOrCreate", }); + +export const getCustomerJsDoc = createJSDocDescription({ + description: + "Fetches a customer by ID, optionally expanding related data such as invoices or entities.", + whenToUse: + "Use this when you know the customer exists or assert they exist without creating them.", + body: GetCustomerParamsV1Schema, + examples: [ + example({ + description: "Fetch a customer by external ID", + values: { + customerId: "cus_123", + }, + }), + example({ + description: "Fetch a customer with expanded invoices and entities", + values: { + customerId: "cus_123", + expand: ["invoices", "entities"], + }, + }), + ], + methodName: "get", +}); diff --git a/packages/openapi/v2.1/openapi2.1.ts b/packages/openapi/v2.1/openapi2.1.ts index 3cae5d2d4..b7f04bb2a 100644 --- a/packages/openapi/v2.1/openapi2.1.ts +++ b/packages/openapi/v2.1/openapi2.1.ts @@ -16,6 +16,7 @@ import { CustomerDataSchema, CustomerExpandEnum, CustomerIdSchema, + GetCustomerParamsV1Schema, LATEST_VERSION, PreviewUpdateSubscriptionResponseSchema, SetupPaymentParamsV1Schema, @@ -54,6 +55,7 @@ async function generateOpenApiDocument(): Promise> { // in the OpenAPI output, which removeInternalFields() will then strip registerInternalSchemas(BaseApiCustomerSchema); registerInternalSchemas(CreateCustomerParamsV1Schema); + registerInternalSchemas(GetCustomerParamsV1Schema); registerInternalSchemas(AttachParamsV1Schema); registerInternalSchemas(UpdateSubscriptionV1ParamsSchema); registerInternalSchemas(SetupPaymentParamsV1Schema);