23090 lines
1.0 MiB
23090 lines
1.0 MiB
info:
|
|
title: Autumn API
|
|
version: 2.3.0
|
|
servers:
|
|
- url: https://api.useautumn.com
|
|
description: Production server
|
|
openapi: 3.1.0
|
|
components:
|
|
schemas:
|
|
CustomerId:
|
|
type: string
|
|
title: CustomerId
|
|
description: Your unique identifier for the customer
|
|
CustomerData:
|
|
type: object
|
|
properties:
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
create_in_stripe:
|
|
type: boolean
|
|
description: Whether to create the customer in Stripe
|
|
auto_enable_plan_id:
|
|
type: string
|
|
description: The ID of the free plan to auto-enable for the customer
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
description: Optional rate limit to cap how often auto top-ups occur.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature (max units per interval).
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For usage_percentage
|
|
or remaining_percentage, this is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Miscellaneous configurations for the customer.
|
|
title: CustomerData
|
|
description: Customer details to set when creating a customer
|
|
CustomerExpand:
|
|
enum:
|
|
- invoices
|
|
- trials_used
|
|
- rewards
|
|
- entities
|
|
- referrals
|
|
- payment_method
|
|
- subscriptions.plan
|
|
- purchases.plan
|
|
- balances.feature
|
|
- flags.feature
|
|
- billing_controls.auto_topups.purchase_limit
|
|
type: string
|
|
title: CustomerExpand
|
|
Customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
- type: "null"
|
|
description: The time interval for the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Number of intervals in the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
limit:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Maximum number of auto top-ups allowed within the interval. Null
|
|
when no purchase limit is configured.
|
|
count:
|
|
type: number
|
|
description: Number of auto top-ups already consumed in the current window.
|
|
next_reset_at:
|
|
type: number
|
|
description: Unix ms timestamp when the current purchase window ends and the
|
|
count resets.
|
|
required:
|
|
- interval
|
|
- interval_count
|
|
- limit
|
|
- count
|
|
- next_reset_at
|
|
description: Optional rate limit to cap how often auto top-ups occur. Expand
|
|
billing_controls.auto_topups.purchase_limit for a count of
|
|
top ups and the next_reset_at.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature, with current interval usage.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For usage_percentage
|
|
or remaining_percentage, this is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise, falls back
|
|
to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools, 'ai_credit_system' for model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
description: Boolean feature flags keyed by feature ID, showing enabled access
|
|
for on/off features.
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Configuration for the customer.
|
|
processors:
|
|
type: object
|
|
properties:
|
|
stripe:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Stripe customer ID.
|
|
required:
|
|
- id
|
|
description: Stripe processor connection for the customer.
|
|
vercel:
|
|
type: object
|
|
properties:
|
|
installation_id:
|
|
type: string
|
|
description: Vercel marketplace installation ID for this customer.
|
|
account_id:
|
|
type: string
|
|
description: Vercel account ID associated with the installation.
|
|
required:
|
|
- installation_id
|
|
- account_id
|
|
description: Vercel processor connection for the customer (public-safe subset).
|
|
revenuecat:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's external ID, used as the RevenueCat app user ID. Null if
|
|
the customer has no external ID set.
|
|
required:
|
|
- id
|
|
description: RevenueCat processor connection for the customer.
|
|
description: Payment processors this customer is connected to (Stripe, Vercel,
|
|
RevenueCat). Omitted entirely when the customer has not been created
|
|
in any processor.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this customer.
|
|
entities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
description: Entities associated with this customer.
|
|
trials_used:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
customer_id:
|
|
type: string
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- customer_id
|
|
description: Trial usage history for this customer.
|
|
rewards:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this discount
|
|
name:
|
|
type: string
|
|
description: The name of the discount or coupon
|
|
type:
|
|
enum:
|
|
- percentage_discount
|
|
- fixed_discount
|
|
- free_product
|
|
- invoice_credits
|
|
- feature_grant
|
|
type: string
|
|
description: The type of reward
|
|
discount_value:
|
|
type: number
|
|
description: The discount value (percentage or fixed amount)
|
|
duration_type:
|
|
enum:
|
|
- one_off
|
|
- months
|
|
- forever
|
|
type: string
|
|
description: How long the discount lasts
|
|
duration_value:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Number of billing periods the discount applies for repeating
|
|
durations
|
|
currency:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The currency code for fixed amount discounts
|
|
start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount becomes active
|
|
end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount expires
|
|
subscription_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The Stripe subscription ID this discount is applied to
|
|
total_discount_amount:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Total amount saved from this discount
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- discount_value
|
|
- duration_type
|
|
description: Array of active discounts applied to the customer
|
|
required:
|
|
- discounts
|
|
- type: "null"
|
|
description: Rewards earned or applied for this customer.
|
|
referrals:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
program_id:
|
|
type: string
|
|
customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
reward_applied:
|
|
type: boolean
|
|
created_at:
|
|
type: number
|
|
required:
|
|
- program_id
|
|
- customer
|
|
- reward_applied
|
|
- created_at
|
|
description: Referral records for this customer.
|
|
payment_method:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
description: The customer's default payment method.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- billing_controls
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
processors:
|
|
stripe:
|
|
id: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
billingControls:
|
|
autoTopups: []
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
flags:
|
|
advanced_workflows:
|
|
id: cus_ent_abc123
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: advanced_workflows
|
|
config:
|
|
disable_pooled_balance: false
|
|
Plan:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_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:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers' or 'amount' is
|
|
required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer can use up
|
|
to 400 total before usage is capped. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores the
|
|
customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a past_due
|
|
state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
description: Whether the trial on this plan is available to this customer. For
|
|
example, if the customer used the trial in the past, this will
|
|
be false.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: The customer's current status with this plan. 'active' if attached,
|
|
'scheduled' if pending activation.
|
|
canceling:
|
|
type: boolean
|
|
description: Whether the customer's active instance of this plan is set to
|
|
cancel.
|
|
trialing:
|
|
type: boolean
|
|
description: Whether the customer is currently on a free trial of this plan.
|
|
attach_action:
|
|
enum:
|
|
- activate
|
|
- upgrade
|
|
- downgrade
|
|
- none
|
|
- purchase
|
|
type: string
|
|
description: The action that would occur if this plan were attached to the
|
|
customer.
|
|
required:
|
|
- attach_action
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
- config
|
|
Balance:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools, 'ai_credit_system' for model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
granted:
|
|
type: number
|
|
description: Total balance granted (included + prepaid).
|
|
remaining:
|
|
type: number
|
|
minimum: 0
|
|
description: Remaining balance available for use.
|
|
usage:
|
|
type: number
|
|
description: Total usage consumed in the current period.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether this feature has unlimited usage.
|
|
overage_allowed:
|
|
type: boolean
|
|
description: Whether usage beyond the granted balance is allowed (with overage
|
|
charges).
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum quantity that can be purchased as a top-up, or null for
|
|
unlimited.
|
|
next_reset_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will reset, or null for no reset.
|
|
breakdown:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
default: ""
|
|
description: The unique identifier for this balance breakdown.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this balance originates from, or null for standalone
|
|
balances.
|
|
included_grant:
|
|
type: number
|
|
description: Amount granted from the plan's included usage.
|
|
prepaid_grant:
|
|
type: number
|
|
description: Amount granted from prepaid purchases or top-ups.
|
|
remaining:
|
|
type: number
|
|
description: Remaining balance available for use.
|
|
usage:
|
|
type: number
|
|
description: Amount consumed in the current period.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether this balance has unlimited usage.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for this balance, or null if no reset.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: The per-unit price amount.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration if applicable.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
description: "How tiers are applied: graduated (split across bands) or volume
|
|
(flat rate for the matched tier)."
|
|
billing_units:
|
|
type: number
|
|
description: The number of units per billing increment (eg. $9 / 250 units).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Whether usage is prepaid or billed pay-per-use.
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum quantity that can be purchased, or null for unlimited.
|
|
required:
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration if this balance has usage-based pricing.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this balance expires, or null for no expiration.
|
|
required:
|
|
- plan_id
|
|
- included_grant
|
|
- prepaid_grant
|
|
- remaining
|
|
- usage
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
- expires_at
|
|
description: Detailed breakdown of balance sources when stacking multiple plans
|
|
or grants.
|
|
rollovers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance:
|
|
type: number
|
|
description: Amount of balance rolled over from a previous period.
|
|
expires_at:
|
|
type: number
|
|
description: Timestamp when the rollover balance expires.
|
|
required:
|
|
- balance
|
|
- expires_at
|
|
description: Rollover balances carried over from previous periods.
|
|
required:
|
|
- feature_id
|
|
- granted
|
|
- remaining
|
|
- usage
|
|
- unlimited
|
|
- overage_allowed
|
|
- max_purchase
|
|
- next_reset_at
|
|
examples:
|
|
- feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
securitySchemes:
|
|
secretKey:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
paths:
|
|
/v1/customers.get_or_create:
|
|
post:
|
|
operationId: getOrCreateCustomer
|
|
description: >-
|
|
Creates a customer if they do not exist, or returns the existing
|
|
customer by your external customer ID.
|
|
|
|
|
|
Use this as the primary entrypoint before billing operations so the
|
|
customer record is always present and up to date.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create or fetch a customer by external ID
|
|
|
|
const response = await client.getOrCreate({ customerId: "cus_123", name:
|
|
"John Doe", email: "john@example.com" });
|
|
|
|
```
|
|
|
|
|
|
@param id - Your unique identifier for the customer (optional)
|
|
|
|
@param name - Customer's name (optional)
|
|
|
|
@param email - Customer's email address (optional)
|
|
|
|
@param fingerprint - Unique identifier (eg, serial number) to detect
|
|
duplicate customers and prevent free trial abuse (optional)
|
|
|
|
@param metadata - Additional metadata for the customer (optional)
|
|
|
|
@param stripeId - Stripe customer ID if you already have one (optional)
|
|
|
|
@param createInStripe - Whether to create the customer in Stripe
|
|
(optional)
|
|
|
|
@param autoEnablePlanId - The ID of the free plan to auto-enable for the
|
|
customer (optional)
|
|
|
|
@param sendEmailReceipts - Whether to send email receipts to this
|
|
customer (optional)
|
|
|
|
@param billingControls - Billing controls for the customer (auto
|
|
top-ups, etc.) (optional)
|
|
|
|
@param config - Miscellaneous configurations for the customer.
|
|
(optional)
|
|
|
|
@param expand - Fields to expand in the returned customer response, such
|
|
as subscriptions.plan, purchases.plan, balances.feature, or
|
|
flags.feature. (optional)
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/CustomerId"
|
|
- type: "null"
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
create_in_stripe:
|
|
type: boolean
|
|
description: Whether to create the customer in Stripe
|
|
auto_enable_plan_id:
|
|
type: string
|
|
description: The ID of the free plan to auto-enable for the customer
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
description: Optional rate limit to cap how often auto top-ups occur.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature (max units per interval).
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this is
|
|
a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Miscellaneous configurations for the customer.
|
|
expand:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerExpand"
|
|
description: Fields to expand in the returned customer response, such as
|
|
subscriptions.plan, purchases.plan, balances.feature, or
|
|
flags.feature.
|
|
required:
|
|
- customer_id
|
|
title: GetOrCreateCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
name: John Doe
|
|
email: john@example.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
x-speakeasy-name-override: getOrCreate
|
|
parameters:
|
|
- &a1
|
|
name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: 2.3.0
|
|
x-speakeasy-globals-hidden: true
|
|
/v1/customers.get:
|
|
post:
|
|
operationId: getCustomer
|
|
description: >-
|
|
Fetches a customer by ID, optionally expanding related data such as
|
|
invoices or entities.
|
|
|
|
|
|
Use this when you know the customer exists or assert they exist without
|
|
creating them.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a customer by external ID
|
|
|
|
const response = await client.get({ customerId: "cus_123" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a customer with expanded invoices and entities
|
|
|
|
const response = await client.get({ customerId: "cus_123", expand:
|
|
["invoices","entities"] });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - ID of the customer to fetch
|
|
|
|
@param expand - Expand related customer data like invoices or entities,
|
|
or expand nested objects like balances.feature, flags.feature,
|
|
subscriptions.plan, and purchases.plan. (optional)
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to fetch
|
|
expand:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerExpand"
|
|
description: Expand related customer data like invoices or entities, or expand
|
|
nested objects like balances.feature, flags.feature,
|
|
subscriptions.plan, and purchases.plan.
|
|
required:
|
|
- customer_id
|
|
title: GetCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
- customer_id: cus_123
|
|
expand:
|
|
- invoices
|
|
- entities
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
- type: "null"
|
|
description: The time interval for the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Number of intervals in the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
limit:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Maximum number of auto top-ups allowed within the interval. Null
|
|
when no purchase limit is configured.
|
|
count:
|
|
type: number
|
|
description: Number of auto top-ups already consumed in the current window.
|
|
next_reset_at:
|
|
type: number
|
|
description: Unix ms timestamp when the current purchase window ends and the
|
|
count resets.
|
|
required:
|
|
- interval
|
|
- interval_count
|
|
- limit
|
|
- count
|
|
- next_reset_at
|
|
description: Optional rate limit to cap how often auto top-ups occur. Expand
|
|
billing_controls.auto_topups.purchase_limit for
|
|
a count of top ups and the next_reset_at.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature, with current interval usage.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise,
|
|
falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
description: Boolean feature flags keyed by feature ID, showing enabled access
|
|
for on/off features.
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Configuration for the customer.
|
|
processors:
|
|
type: object
|
|
properties:
|
|
stripe:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Stripe customer ID.
|
|
required:
|
|
- id
|
|
description: Stripe processor connection for the customer.
|
|
vercel:
|
|
type: object
|
|
properties:
|
|
installation_id:
|
|
type: string
|
|
description: Vercel marketplace installation ID for this customer.
|
|
account_id:
|
|
type: string
|
|
description: Vercel account ID associated with the installation.
|
|
required:
|
|
- installation_id
|
|
- account_id
|
|
description: Vercel processor connection for the customer (public-safe subset).
|
|
revenuecat:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's external ID, used as the RevenueCat app user ID. Null if
|
|
the customer has no external ID set.
|
|
required:
|
|
- id
|
|
description: RevenueCat processor connection for the customer.
|
|
description: Payment processors this customer is connected to (Stripe, Vercel,
|
|
RevenueCat). Omitted entirely when the customer has not
|
|
been created in any processor.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this customer.
|
|
entities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
description: Entities associated with this customer.
|
|
trials_used:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
customer_id:
|
|
type: string
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- customer_id
|
|
description: Trial usage history for this customer.
|
|
rewards:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this discount
|
|
name:
|
|
type: string
|
|
description: The name of the discount or coupon
|
|
type:
|
|
enum:
|
|
- percentage_discount
|
|
- fixed_discount
|
|
- free_product
|
|
- invoice_credits
|
|
- feature_grant
|
|
type: string
|
|
description: The type of reward
|
|
discount_value:
|
|
type: number
|
|
description: The discount value (percentage or fixed amount)
|
|
duration_type:
|
|
enum:
|
|
- one_off
|
|
- months
|
|
- forever
|
|
type: string
|
|
description: How long the discount lasts
|
|
duration_value:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Number of billing periods the discount applies for repeating
|
|
durations
|
|
currency:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The currency code for fixed amount discounts
|
|
start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount becomes active
|
|
end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount expires
|
|
subscription_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The Stripe subscription ID this discount is applied to
|
|
total_discount_amount:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Total amount saved from this discount
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- discount_value
|
|
- duration_type
|
|
description: Array of active discounts applied to the customer
|
|
required:
|
|
- discounts
|
|
- type: "null"
|
|
description: Rewards earned or applied for this customer.
|
|
referrals:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
program_id:
|
|
type: string
|
|
customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
reward_applied:
|
|
type: boolean
|
|
created_at:
|
|
type: number
|
|
required:
|
|
- program_id
|
|
- customer
|
|
- reward_applied
|
|
- created_at
|
|
description: Referral records for this customer.
|
|
payment_method:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
description: The customer's default payment method.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- billing_controls
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
processors:
|
|
stripe:
|
|
id: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
billingControls:
|
|
autoTopups: []
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
flags:
|
|
advanced_workflows:
|
|
id: cus_ent_abc123
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: advanced_workflows
|
|
config:
|
|
disable_pooled_balance: false
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/customers.list:
|
|
post:
|
|
operationId: listCustomers
|
|
description: 'Lists customers with cursor pagination and optional filters. Pass
|
|
`start_cursor: ""` (or omit) for the first page; use `next_cursor` from
|
|
a prior response for subsequent pages.'
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
start_cursor:
|
|
type: string
|
|
default: ""
|
|
description: Opaque pagination cursor. Empty string (default) requests the first
|
|
page; use next_cursor from a prior response for subsequent
|
|
pages.
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 5000
|
|
default: 50
|
|
description: Number of items to return. Default 50, hard ceiling 5000.
|
|
plans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
versions:
|
|
type: array
|
|
items:
|
|
type: number
|
|
required:
|
|
- id
|
|
description: Filter by plan ID and version. Returns customers with active
|
|
subscriptions to this plan.
|
|
subscription_status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Filter by customer product status. Defaults to active and
|
|
scheduled.
|
|
search:
|
|
type: string
|
|
description: Search customers by id, name, or email.
|
|
processors:
|
|
type: array
|
|
items:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
- vercel
|
|
type: string
|
|
description: Filter by customer processor type (stripe, revenuecat, vercel).
|
|
title: ListCustomersParams
|
|
examples:
|
|
- start_cursor: ""
|
|
limit: 10
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple
|
|
device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
- type: "null"
|
|
description: The time interval for the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Number of intervals in the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
limit:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Maximum number of auto top-ups allowed within the interval. Null
|
|
when no purchase limit is
|
|
configured.
|
|
count:
|
|
type: number
|
|
description: Number of auto top-ups already consumed in the current window.
|
|
next_reset_at:
|
|
type: number
|
|
description: Unix ms timestamp when the current purchase window ends and the
|
|
count resets.
|
|
required:
|
|
- interval
|
|
- interval_count
|
|
- limit
|
|
- count
|
|
- next_reset_at
|
|
description: Optional rate limit to cap how often auto top-ups occur. Expand
|
|
billing_controls.auto_topups.purchase_limit
|
|
for a count of top ups and the
|
|
next_reset_at.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing
|
|
controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature, with current interval usage.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage,
|
|
this is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used;
|
|
otherwise, falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system'
|
|
for unified credit pools,
|
|
'ai_credit_system' for model-based token
|
|
pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
description: Boolean feature flags keyed by feature ID, showing enabled access
|
|
for on/off features.
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Configuration for the customer.
|
|
processors:
|
|
type: object
|
|
properties:
|
|
stripe:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Stripe customer ID.
|
|
required:
|
|
- id
|
|
description: Stripe processor connection for the customer.
|
|
vercel:
|
|
type: object
|
|
properties:
|
|
installation_id:
|
|
type: string
|
|
description: Vercel marketplace installation ID for this customer.
|
|
account_id:
|
|
type: string
|
|
description: Vercel account ID associated with the installation.
|
|
required:
|
|
- installation_id
|
|
- account_id
|
|
description: Vercel processor connection for the customer (public-safe subset).
|
|
revenuecat:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's external ID, used as the RevenueCat app user ID. Null if
|
|
the customer has no external ID set.
|
|
required:
|
|
- id
|
|
description: RevenueCat processor connection for the customer.
|
|
description: Payment processors this customer is connected to (Stripe, Vercel,
|
|
RevenueCat). Omitted entirely when the customer has
|
|
not been created in any processor.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- billing_controls
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
processors:
|
|
stripe:
|
|
id: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
billingControls:
|
|
autoTopups: []
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
flags:
|
|
advanced_workflows:
|
|
id: cus_ent_abc123
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: advanced_workflows
|
|
config:
|
|
disable_pooled_balance: false
|
|
description: Items for current page.
|
|
next_cursor:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Opaque cursor for the next page. Null when there are no more
|
|
results.
|
|
required:
|
|
- list
|
|
- next_cursor
|
|
examples:
|
|
- list:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
processors:
|
|
stripe:
|
|
id: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
billingControls:
|
|
autoTopups: []
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
flags:
|
|
advanced_workflows:
|
|
id: cus_ent_abc123
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: advanced_workflows
|
|
config:
|
|
disable_pooled_balance: false
|
|
next_cursor: null
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/customers.update:
|
|
post:
|
|
operationId: updateCustomer
|
|
description: Updates an existing customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to update
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
description: Optional rate limit to cap how often auto top-ups occur.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature (max units per interval).
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this is
|
|
a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Miscellaneous configurations for the customer.
|
|
new_customer_id:
|
|
$ref: "#/components/schemas/CustomerId"
|
|
description: New ID for the customer
|
|
required:
|
|
- customer_id
|
|
title: UpdateCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
name: Jane Doe
|
|
email: jane@example.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
auto_topups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature (credit balance) to auto top-up.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether auto top-up is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: When the balance drops below this threshold, an auto top-up will be
|
|
purchased.
|
|
quantity:
|
|
type: number
|
|
minimum: 1
|
|
description: Amount of credits to add per auto top-up.
|
|
purchase_limit:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
description: The time interval for the purchase limit window.
|
|
interval_count:
|
|
type: number
|
|
minimum: 1
|
|
default: 1
|
|
description: Number of intervals in the purchase limit window.
|
|
limit:
|
|
type: number
|
|
minimum: 1
|
|
description: Maximum number of auto top-ups allowed within the interval.
|
|
required:
|
|
- interval
|
|
- limit
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
type: string
|
|
- type: "null"
|
|
description: The time interval for the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Number of intervals in the purchase limit window. Null when no
|
|
purchase limit is configured.
|
|
limit:
|
|
anyOf:
|
|
- type: number
|
|
minimum: 1
|
|
- type: "null"
|
|
description: Maximum number of auto top-ups allowed within the interval. Null
|
|
when no purchase limit is configured.
|
|
count:
|
|
type: number
|
|
description: Number of auto top-ups already consumed in the current window.
|
|
next_reset_at:
|
|
type: number
|
|
description: Unix ms timestamp when the current purchase window ends and the
|
|
count resets.
|
|
required:
|
|
- interval
|
|
- interval_count
|
|
- limit
|
|
- count
|
|
- next_reset_at
|
|
description: Optional rate limit to cap how often auto top-ups occur. Expand
|
|
billing_controls.auto_topups.purchase_limit for
|
|
a count of top ups and the next_reset_at.
|
|
invoice_mode:
|
|
type: boolean
|
|
description: When true, auto top-up creates a send_invoice invoice instead of
|
|
auto-charging.
|
|
required:
|
|
- feature_id
|
|
- threshold
|
|
- quantity
|
|
description: List of auto top-up configurations per feature.
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage 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 (caps overage spend).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature, with current interval usage.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the customer (auto top-ups, etc.)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise,
|
|
falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
description: Boolean feature flags keyed by feature ID, showing enabled access
|
|
for on/off features.
|
|
config:
|
|
type: object
|
|
properties:
|
|
disable_pooled_balance:
|
|
type: boolean
|
|
description: Whether to disable the shared customer-level pool for entities.
|
|
description: Configuration for the customer.
|
|
processors:
|
|
type: object
|
|
properties:
|
|
stripe:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Stripe customer ID.
|
|
required:
|
|
- id
|
|
description: Stripe processor connection for the customer.
|
|
vercel:
|
|
type: object
|
|
properties:
|
|
installation_id:
|
|
type: string
|
|
description: Vercel marketplace installation ID for this customer.
|
|
account_id:
|
|
type: string
|
|
description: Vercel account ID associated with the installation.
|
|
required:
|
|
- installation_id
|
|
- account_id
|
|
description: Vercel processor connection for the customer (public-safe subset).
|
|
revenuecat:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's external ID, used as the RevenueCat app user ID. Null if
|
|
the customer has no external ID set.
|
|
required:
|
|
- id
|
|
description: RevenueCat processor connection for the customer.
|
|
description: Payment processors this customer is connected to (Stripe, Vercel,
|
|
RevenueCat). Omitted entirely when the customer has not
|
|
been created in any processor.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- billing_controls
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
processors:
|
|
stripe:
|
|
id: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
billingControls:
|
|
autoTopups: []
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
flags:
|
|
advanced_workflows:
|
|
id: cus_ent_abc123
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: advanced_workflows
|
|
config:
|
|
disable_pooled_balance: false
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/customers.delete:
|
|
post:
|
|
operationId: deleteCustomer
|
|
description: Deletes a customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to delete
|
|
delete_in_stripe:
|
|
type: boolean
|
|
default: false
|
|
description: Whether to also delete the customer in Stripe
|
|
required:
|
|
- customer_id
|
|
title: DeleteCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
delete_in_stripe: false
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.create:
|
|
post:
|
|
operationId: createPlan
|
|
summary: Create a plan
|
|
description: |-
|
|
Creates a new plan with optional base price and feature configurations.
|
|
|
|
Use this to programmatically create pricing plans. See [How plans work](/documentation/pricing/plans) for concepts.
|
|
|
|
@example
|
|
```typescript
|
|
// Create a free plan with limited features
|
|
const response = await client.plans.create({
|
|
planId: "free_plan",
|
|
name: "Free",
|
|
autoEnable: true,
|
|
items: [{"featureId":"messages","included":100,"reset":{"interval":"month"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a paid plan with base price and usage-based feature
|
|
const response = await client.plans.create({
|
|
planId: "pro_plan",
|
|
name: "Pro Plan",
|
|
price: {"amount":10,"interval":"month"},
|
|
items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"},"price":{"amount":0.01,"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with prepaid seats
|
|
const response = await client.plans.create({
|
|
planId: "team_plan",
|
|
name: "Team Plan",
|
|
price: {"amount":49,"interval":"month"},
|
|
items: [{"featureId":"seats","included":5,"price":{"amount":10,"interval":"month","billingUnits":1,"billingMethod":"prepaid"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create an add-on plan
|
|
const response = await client.plans.create({
|
|
planId: "analytics_addon",
|
|
name: "Advanced Analytics",
|
|
addOn: true,
|
|
price: {"amount":20,"interval":"month"},
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with tiered pricing
|
|
const response = await client.plans.create({ planId: "api_plan", name: "API Plan", items: [{"featureId":"api_calls","included":1000,"reset":{"interval":"month"},"price":{"tiers":[{"to":10000,"amount":0.001},{"to":100000,"amount":0.0005},{"to":"inf","amount":0.0001}],"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}] });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with free trial
|
|
const response = await client.plans.create({
|
|
planId: "premium_plan",
|
|
name: "Premium",
|
|
price: {"amount":99,"interval":"month"},
|
|
freeTrial: {"durationLength":14,"durationType":"day","cardRequired":true},
|
|
});
|
|
```
|
|
|
|
@param planId - The ID of the plan to create.
|
|
@param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional)
|
|
@param name - Display name of the plan.
|
|
@param description - Optional description of the plan. (optional)
|
|
@param addOn - If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. (optional)
|
|
@param autoEnable - If true, plan is automatically attached when a customer is created. Use for free tiers. (optional)
|
|
@param price - Base recurring price for the plan. Omit for free or usage-only plans. (optional)
|
|
@param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional)
|
|
@param freeTrial - Free trial configuration. Customers can try this plan before being charged. (optional)
|
|
@param config - Miscellaneous plan-level configuration flags. (optional)
|
|
|
|
@returns The created plan object.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The ID of the plan to create.
|
|
group:
|
|
type: string
|
|
default: ""
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
default: null
|
|
description: Optional description of the plan.
|
|
add_on:
|
|
type: boolean
|
|
default: false
|
|
description: If true, this plan can be attached alongside other plans.
|
|
Otherwise, attaching replaces existing plans in the same
|
|
group.
|
|
auto_enable:
|
|
type: boolean
|
|
default: false
|
|
description: If true, plan is automatically attached when a customer is created.
|
|
Use for free tiers.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
description: Base recurring price for the plan. Omit for free or usage-only
|
|
plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Feature configurations for this plan. Each item defines included
|
|
units, pricing, and reset behavior.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores the
|
|
customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
description: Free trial configuration. Customers can try this plan before being
|
|
charged.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a
|
|
past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
create_in_stripe:
|
|
type: boolean
|
|
default: true
|
|
required:
|
|
- plan_id
|
|
- name
|
|
title: CreatePlanParams
|
|
examples:
|
|
- plan_id: free_plan
|
|
name: Free
|
|
auto_enable: true
|
|
items:
|
|
- feature_id: messages
|
|
included: 100
|
|
reset:
|
|
interval: month
|
|
- plan_id: pro_plan
|
|
name: Pro Plan
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
items:
|
|
- feature_id: messages
|
|
included: 1000
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.01
|
|
interval: month
|
|
billing_units: 1
|
|
billing_method: usage_based
|
|
- plan_id: team_plan
|
|
name: Team Plan
|
|
price:
|
|
amount: 49
|
|
interval: month
|
|
items:
|
|
- feature_id: seats
|
|
included: 5
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billing_units: 1
|
|
billing_method: prepaid
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_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:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers' or 'amount'
|
|
is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores the
|
|
customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a
|
|
past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
description: Whether the trial on this plan is available to this customer. For
|
|
example, if the customer used the trial in the past,
|
|
this will be false.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: The customer's current status with this plan. 'active' if attached,
|
|
'scheduled' if pending activation.
|
|
canceling:
|
|
type: boolean
|
|
description: Whether the customer's active instance of this plan is set to
|
|
cancel.
|
|
trialing:
|
|
type: boolean
|
|
description: Whether the customer is currently on a free trial of this plan.
|
|
attach_action:
|
|
enum:
|
|
- activate
|
|
- upgrade
|
|
- downgrade
|
|
- none
|
|
- purchase
|
|
type: string
|
|
description: The action that would occur if this plan were attached to the
|
|
customer.
|
|
required:
|
|
- attach_action
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
- config
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
config:
|
|
ignore_past_due: false
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.get:
|
|
post:
|
|
operationId: getPlan
|
|
summary: Get a plan
|
|
description: >-
|
|
Retrieves a single plan by its ID.
|
|
|
|
|
|
Use this to fetch the full configuration of a specific plan, including
|
|
its features and pricing.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Get a plan by ID
|
|
|
|
const response = await client.plans.get({ planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Get a specific version of a plan
|
|
|
|
const response = await client.plans.get({ planId: "pro_plan", version: 2
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param planId - The ID of the plan to retrieve.
|
|
|
|
@param version - The version of the plan to get. Defaults to the latest
|
|
version. (optional)
|
|
|
|
|
|
@returns The plan object with its full configuration.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
description: The ID of the plan to retrieve.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to get. Defaults to the latest version.
|
|
required:
|
|
- plan_id
|
|
title: GetPlanParams
|
|
examples:
|
|
- plan_id: pro_plan
|
|
- plan_id: pro_plan
|
|
version: 2
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_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:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers' or 'amount'
|
|
is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores the
|
|
customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a
|
|
past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
description: Whether the trial on this plan is available to this customer. For
|
|
example, if the customer used the trial in the past,
|
|
this will be false.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: The customer's current status with this plan. 'active' if attached,
|
|
'scheduled' if pending activation.
|
|
canceling:
|
|
type: boolean
|
|
description: Whether the customer's active instance of this plan is set to
|
|
cancel.
|
|
trialing:
|
|
type: boolean
|
|
description: Whether the customer is currently on a free trial of this plan.
|
|
attach_action:
|
|
enum:
|
|
- activate
|
|
- upgrade
|
|
- downgrade
|
|
- none
|
|
- purchase
|
|
type: string
|
|
description: The action that would occur if this plan were attached to the
|
|
customer.
|
|
required:
|
|
- attach_action
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
- config
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
config:
|
|
ignore_past_due: false
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.list:
|
|
post:
|
|
operationId: listPlans
|
|
summary: List all plans
|
|
description: >-
|
|
Lists all plans in the current environment.
|
|
|
|
|
|
Use this to retrieve all plans for displaying pricing pages or managing
|
|
plan configurations.
|
|
|
|
|
|
@returns A list of all plans with their pricing and feature
|
|
configurations.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Customer ID to include eligibility info (trial availability, attach
|
|
scenario).
|
|
entity_id:
|
|
type: string
|
|
description: Entity ID for entity-scoped plans.
|
|
include_archived:
|
|
type: boolean
|
|
description: If true, includes archived plans in the response.
|
|
title: ListPlansParams
|
|
examples:
|
|
- {}
|
|
- customer_id: cus_123
|
|
- include_archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_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:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers' or
|
|
'amount' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed
|
|
(e.g. billing_units=100 means 101
|
|
usage rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300,
|
|
customer can use up to 400 total
|
|
before usage is capped. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a
|
|
feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in
|
|
a past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
description: Whether the trial on this plan is available to this customer. For
|
|
example, if the customer used the trial in the
|
|
past, this will be false.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: The customer's current status with this plan. 'active' if attached,
|
|
'scheduled' if pending activation.
|
|
canceling:
|
|
type: boolean
|
|
description: Whether the customer's active instance of this plan is set to
|
|
cancel.
|
|
trialing:
|
|
type: boolean
|
|
description: Whether the customer is currently on a free trial of this plan.
|
|
attach_action:
|
|
enum:
|
|
- activate
|
|
- upgrade
|
|
- downgrade
|
|
- none
|
|
- purchase
|
|
type: string
|
|
description: The action that would occur if this plan were attached to the
|
|
customer.
|
|
required:
|
|
- attach_action
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
- config
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
required:
|
|
- list
|
|
examples:
|
|
- list:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
config:
|
|
ignore_past_due: false
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.update:
|
|
post:
|
|
operationId: updatePlan
|
|
summary: Update a plan
|
|
description: |-
|
|
Updates an existing plan. Creates a new version unless `disableVersion` is set.
|
|
|
|
Use this to modify plan properties, pricing, or feature configurations. See [Adding features to plans](/documentation/pricing/plan-features) for item configuration.
|
|
|
|
@example
|
|
```typescript
|
|
// Update plan name and price
|
|
const response = await client.plans.update({ planId: "pro_plan", name: "Pro Plan (Updated)", price: {"amount":15,"interval":"month"} });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Add a feature to an existing plan
|
|
const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"}},{"featureId":"storage","included":10,"reset":{"interval":"month"}}] });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Remove the base price (make usage-only)
|
|
const response = await client.plans.update({ planId: "pro_plan", price: null });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Archive a plan
|
|
const response = await client.plans.update({ planId: "old_plan", archived: true });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Update feature's included amount
|
|
const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":2000,"reset":{"interval":"month"}}] });
|
|
```
|
|
|
|
@param planId - The ID of the plan to update.
|
|
@param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional)
|
|
@param name - Display name of the plan. (optional)
|
|
@param addOn - Whether the plan is an add-on. (optional)
|
|
@param autoEnable - Whether the plan is automatically enabled. (optional)
|
|
@param price - The price of the plan. Set to null to remove the base price. (optional)
|
|
@param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional)
|
|
@param freeTrial - The free trial of the plan. Set to null to remove the free trial. (optional)
|
|
@param config - Miscellaneous plan-level configuration flags. (optional)
|
|
@param newPlanId - The new ID to use for the plan. Can only be updated if the plan has not been used by any customers. (optional)
|
|
|
|
@returns The updated plan object.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The ID of the plan to update.
|
|
group:
|
|
type: string
|
|
default: ""
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: Display name of the plan.
|
|
description:
|
|
type: string
|
|
add_on:
|
|
type: boolean
|
|
description: Whether the plan is an add-on.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan is automatically enabled.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: The price of the plan. Set to null to remove the base price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Feature configurations for this plan. Each item defines included
|
|
units, pricing, and reset behavior.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores
|
|
the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: The free trial of the plan. Set to null to remove the free trial.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a
|
|
past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
create_in_stripe:
|
|
type: boolean
|
|
default: true
|
|
version:
|
|
type: number
|
|
archived:
|
|
type: boolean
|
|
default: false
|
|
new_plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The new ID to use for the plan. Can only be updated if the plan has
|
|
not been used by any customers.
|
|
disable_version:
|
|
type: boolean
|
|
required:
|
|
- plan_id
|
|
title: UpdatePlanParams
|
|
examples:
|
|
- plan_id: pro_plan
|
|
name: Pro Plan (Updated)
|
|
price:
|
|
amount: 15
|
|
interval: month
|
|
- plan_id: pro_plan
|
|
price: null
|
|
- plan_id: old_plan
|
|
archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_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:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers' or 'amount'
|
|
is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores the
|
|
customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
config:
|
|
type: object
|
|
properties:
|
|
ignore_past_due:
|
|
type: boolean
|
|
default: false
|
|
description: If true, entitlements attached to this plan will still reset on
|
|
schedule even when the customer's product is in a
|
|
past_due state.
|
|
description: Miscellaneous plan-level configuration flags.
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
description: Whether the trial on this plan is available to this customer. For
|
|
example, if the customer used the trial in the past,
|
|
this will be false.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: The customer's current status with this plan. 'active' if attached,
|
|
'scheduled' if pending activation.
|
|
canceling:
|
|
type: boolean
|
|
description: Whether the customer's active instance of this plan is set to
|
|
cancel.
|
|
trialing:
|
|
type: boolean
|
|
description: Whether the customer is currently on a free trial of this plan.
|
|
attach_action:
|
|
enum:
|
|
- activate
|
|
- upgrade
|
|
- downgrade
|
|
- none
|
|
- purchase
|
|
type: string
|
|
description: The action that would occur if this plan were attached to the
|
|
customer.
|
|
required:
|
|
- attach_action
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
- config
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
config:
|
|
ignore_past_due: false
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.delete:
|
|
post:
|
|
operationId: deletePlan
|
|
summary: Delete a plan
|
|
description: >-
|
|
Deletes a plan by its ID.
|
|
|
|
|
|
Use this to permanently remove a plan. Plans with active customers
|
|
cannot be deleted - archive them instead.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete a plan
|
|
|
|
const response = await client.plans.delete({ planId: "unused_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete all versions of a plan
|
|
|
|
const response = await client.plans.delete({ planId: "legacy_plan",
|
|
allVersions: true });
|
|
|
|
```
|
|
|
|
|
|
@param planId - The ID of the plan to delete.
|
|
|
|
@param allVersions - If true, deletes all versions of the plan.
|
|
Otherwise, only deletes the latest version. (optional)
|
|
|
|
|
|
@returns A success flag indicating the plan was deleted.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
description: The ID of the plan to delete.
|
|
all_versions:
|
|
type: boolean
|
|
default: false
|
|
description: If true, deletes all versions of the plan. Otherwise, only deletes
|
|
the latest version.
|
|
required:
|
|
- plan_id
|
|
title: DeletePlanParams
|
|
examples:
|
|
- plan_id: unused_plan
|
|
- plan_id: legacy_plan
|
|
all_versions: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/features.create:
|
|
post:
|
|
operationId: createFeature
|
|
description: >-
|
|
Creates a new feature.
|
|
|
|
|
|
Use this to programmatically create features for metering usage,
|
|
managing access, or building credit systems.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a metered feature for API calls
|
|
|
|
const response = await client.features.create({
|
|
featureId: "api-calls",
|
|
name: "API Calls",
|
|
type: "metered",
|
|
consumable: true,
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a boolean feature for a premium feature flag
|
|
|
|
const response = await client.features.create({ featureId:
|
|
"advanced-analytics", name: "Advanced Analytics", type: "boolean" });
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the feature.
|
|
|
|
@param type - The type of the feature. 'single_use' features are
|
|
consumed, like API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects. 'credit_system'
|
|
features are schemas that unify multiple 'single_use' features into a
|
|
single credit system.
|
|
|
|
@param consumable - Whether this feature is consumable. A consumable
|
|
feature is one that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable only for
|
|
'metered' features. (optional)
|
|
|
|
@param display - Singular and plural display names for the feature in
|
|
your user interface. (optional)
|
|
|
|
@param creditSchema - A schema that maps 'single_use' feature IDs to
|
|
credit costs. For classic credit systems only — AI credit systems use
|
|
model_markups instead. (optional)
|
|
|
|
@param modelMarkups - Per-model markup overrides for AI credit systems.
|
|
Maps model IDs to their markup configuration. (optional)
|
|
|
|
@param defaultMarkup - Default percentage markup for this AI credit
|
|
system. Used when no model or provider markup applies. Use -100 to make
|
|
usage free. (optional)
|
|
|
|
@param providerMarkups - Per-provider default markup percentages for AI
|
|
credit systems. Provider keys match the first segment of model_id.
|
|
(optional)
|
|
|
|
@param featureId - The ID of the feature to create.
|
|
|
|
|
|
@returns The created feature object.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: The type of the feature. 'single_use' features are consumed, like
|
|
API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects.
|
|
'credit_system' features are schemas that unify multiple
|
|
'single_use' features into a single credit system.
|
|
consumable:
|
|
type: boolean
|
|
description: Whether this feature is consumable. A consumable feature is one
|
|
that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable
|
|
only for 'metered' features.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
plural:
|
|
type: string
|
|
required:
|
|
- singular
|
|
- plural
|
|
description: Singular and plural display names for the feature in your user
|
|
interface.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: A schema that maps 'single_use' feature IDs to credit costs. For
|
|
classic credit systems only — AI credit systems use
|
|
model_markups instead.
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems. Maps model IDs to
|
|
their markup configuration.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for this AI credit system. Used when no
|
|
model or provider markup applies. Use -100 to make usage
|
|
free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
Provider keys match the first segment of model_id.
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to create.
|
|
required:
|
|
- name
|
|
- type
|
|
- feature_id
|
|
title: CreateFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
- feature_id: credits
|
|
name: Credits
|
|
type: credit_system
|
|
consumable: true
|
|
credit_schema:
|
|
- metered_feature_id: api-calls
|
|
credit_cost: 1
|
|
- metered_feature_id: image-generations
|
|
credit_cost: 10
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools, 'ai_credit_system' for model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/features.get:
|
|
post:
|
|
operationId: getFeature
|
|
description: |-
|
|
Retrieves a single feature by its ID.
|
|
|
|
Use this when you need to fetch the details of a specific feature.
|
|
|
|
@example
|
|
```typescript
|
|
// Get a feature by ID
|
|
const response = await client.features.get({ featureId: "api-calls" });
|
|
```
|
|
|
|
@param featureId - The ID of the feature.
|
|
|
|
@returns The feature object with its full configuration.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
required:
|
|
- feature_id
|
|
title: GetFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools, 'ai_credit_system' for model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/features.list:
|
|
post:
|
|
operationId: listFeatures
|
|
description: >-
|
|
Lists all features in the current environment.
|
|
|
|
|
|
Use this to retrieve all features configured for your organization to
|
|
display in dashboards or for feature management.
|
|
|
|
|
|
@returns A list of all features with their configuration and metadata.
|
|
tags:
|
|
- features
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified
|
|
credit pools, 'ai_credit_system' for model-based
|
|
token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
required:
|
|
- list
|
|
examples:
|
|
- list:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
- id: credits
|
|
name: Credits
|
|
type: credit_system
|
|
consumable: true
|
|
archived: false
|
|
credit_schema:
|
|
- metered_feature_id: api-calls
|
|
credit_cost: 1
|
|
- metered_feature_id: image-generations
|
|
credit_cost: 10
|
|
display:
|
|
singular: credit
|
|
plural: credits
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/features.update:
|
|
post:
|
|
operationId: updateFeature
|
|
description: >-
|
|
Updates an existing feature.
|
|
|
|
|
|
Use this to modify feature properties like name, display settings, or to
|
|
archive a feature.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Update a feature's display name
|
|
|
|
const response = await client.features.update({ featureId: "api-calls",
|
|
name: "API Requests", display: {"singular":"API request","plural":"API
|
|
requests"} });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Archive a feature
|
|
|
|
const response = await client.features.update({ featureId:
|
|
"deprecated-feature", archived: true });
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the feature. (optional)
|
|
|
|
@param type - The type of the feature. 'single_use' features are
|
|
consumed, like API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects. 'credit_system'
|
|
features are schemas that unify multiple 'single_use' features into a
|
|
single credit system. (optional)
|
|
|
|
@param consumable - Whether this feature is consumable. A consumable
|
|
feature is one that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable only for
|
|
'metered' features. (optional)
|
|
|
|
@param display - Singular and plural display names for the feature in
|
|
your user interface. (optional)
|
|
|
|
@param creditSchema - A schema that maps 'single_use' feature IDs to
|
|
credit costs. For classic credit systems only — AI credit systems use
|
|
model_markups instead. (optional)
|
|
|
|
@param modelMarkups - Per-model markup overrides for AI credit systems.
|
|
Maps model IDs to their markup configuration. (optional)
|
|
|
|
@param defaultMarkup - Default percentage markup for this AI credit
|
|
system. Used when no model or provider markup applies. Use -100 to make
|
|
usage free. (optional)
|
|
|
|
@param providerMarkups - Per-provider default markup percentages for AI
|
|
credit systems. Provider keys match the first segment of model_id.
|
|
(optional)
|
|
|
|
@param archived - Whether the feature is archived. Archived features are
|
|
hidden from the dashboard. (optional)
|
|
|
|
@param featureId - The ID of the feature to update.
|
|
|
|
@param newFeatureId - The new ID of the feature. Feature ID can only be
|
|
updated if it's not being used by any customers. (optional)
|
|
|
|
|
|
@returns The updated feature object.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: The type of the feature. 'single_use' features are consumed, like
|
|
API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects.
|
|
'credit_system' features are schemas that unify multiple
|
|
'single_use' features into a single credit system.
|
|
consumable:
|
|
type: boolean
|
|
description: Whether this feature is consumable. A consumable feature is one
|
|
that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable
|
|
only for 'metered' features.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
plural:
|
|
type: string
|
|
required:
|
|
- singular
|
|
- plural
|
|
description: Singular and plural display names for the feature in your user
|
|
interface.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: A schema that maps 'single_use' feature IDs to credit costs. For
|
|
classic credit systems only — AI credit systems use
|
|
model_markups instead.
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems. Maps model IDs to
|
|
their markup configuration.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for this AI credit system. Used when no
|
|
model or provider markup applies. Use -100 to make usage
|
|
free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
Provider keys match the first segment of model_id.
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived. Archived features are hidden from
|
|
the dashboard.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to update.
|
|
new_feature_id:
|
|
type: string
|
|
description: The new ID of the feature. Feature ID can only be updated if it's
|
|
not being used by any customers.
|
|
required:
|
|
- feature_id
|
|
title: UpdateFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
name: API Requests
|
|
display:
|
|
singular: API request
|
|
plural: API requests
|
|
- feature_id: old-feature
|
|
archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools, 'ai_credit_system' for model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/features.delete:
|
|
post:
|
|
operationId: deleteFeature
|
|
description: >-
|
|
Deletes a feature by its ID.
|
|
|
|
|
|
Use this to permanently remove a feature. Note: features that are used
|
|
in products cannot be deleted - archive them instead.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete an unused feature
|
|
|
|
const response = await client.features.delete({ featureId: "old-feature"
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param featureId - The ID of the feature to delete.
|
|
|
|
|
|
@returns A success flag indicating the feature was deleted.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to delete.
|
|
required:
|
|
- feature_id
|
|
title: DeleteFeatureParams
|
|
examples:
|
|
- feature_id: old-feature
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
examples:
|
|
- success: true
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.attach:
|
|
post:
|
|
operationId: attach
|
|
description: >-
|
|
Attaches a plan to a customer. Handles new subscriptions, upgrades and
|
|
downgrades.
|
|
|
|
|
|
Use this endpoint to subscribe a customer to a plan, upgrade/downgrade
|
|
between plans, or add an add-on product.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach a plan to a customer
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach with a free trial
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan", freeTrial:
|
|
{"durationLength":14,"durationType":"day"} });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach with custom pricing
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan", customize:
|
|
{"price":{"amount":4900,"interval":"month"}} });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan.
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param customize - Customize the plan to attach. Can override the price,
|
|
items, free trial, or a combination. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param prorationBehavior - How to handle proration when updating an
|
|
existing subscription. 'prorate_immediately' charges/credits prorated
|
|
amounts now, 'none' skips creating any charges. (optional)
|
|
|
|
@param redirectMode - Controls when to return a checkout URL. 'always'
|
|
returns a URL even if payment succeeds, 'if_required' only when payment
|
|
action is needed, 'never' disables redirects. (optional)
|
|
|
|
@param subscriptionId - A unique ID to identify this subscription. Can
|
|
be used to target specific subscriptions in update operations when a
|
|
customer has multiple products with the same plan. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param successUrl - URL to redirect to after successful checkout.
|
|
(optional)
|
|
|
|
@param newBillingSubscription - Only applicable when the customer has an
|
|
existing Stripe subscription. If true, creates a new separate
|
|
subscription instead of merging into the existing one. (optional)
|
|
|
|
@param billingCycleAnchor - Reset the billing cycle anchor immediately
|
|
with 'now'. (optional)
|
|
|
|
@param planSchedule - When the plan change should take effect.
|
|
'immediate' applies now, 'end_of_cycle' schedules for the end of the
|
|
current billing cycle. By default, upgrades are immediate and downgrades
|
|
are scheduled. (optional)
|
|
|
|
@param startsAt - Unix timestamp in milliseconds for when the attached
|
|
plan should start. Future dates create a scheduled subscription.
|
|
(optional)
|
|
|
|
@param endsAt - Unix timestamp in milliseconds for when the attached
|
|
plan should end. (optional)
|
|
|
|
@param checkoutSessionParams - Additional parameters to pass into the
|
|
creation of the Stripe checkout session. (optional)
|
|
|
|
@param customLineItems - Custom line items that override the
|
|
auto-generated proration invoice. Only valid for immediate plan changes
|
|
(eg. upgrades or one off plans). (optional)
|
|
|
|
@param processorSubscriptionId - The processor subscription ID to link.
|
|
Use this to attach an existing Stripe subscription instead of creating a
|
|
new one. (optional)
|
|
|
|
@param carryOverBalances - Whether to carry over balances from the
|
|
previous plan. (optional)
|
|
|
|
@param carryOverUsages - Whether to carry over usages from the previous
|
|
plan. (optional)
|
|
|
|
@param metadata - Key-value metadata to attach to the Stripe
|
|
subscription, invoice, and checkout session created during this attach
|
|
flow. Keys prefixed with 'autumn_' are reserved and will be stripped.
|
|
(optional)
|
|
|
|
@param noBillingChanges - If true, skips any billing changes for the
|
|
attach operation. (optional)
|
|
|
|
@param enablePlanImmediately - If true, the customer's plan is activated
|
|
immediately even when payment is deferred (invoice mode) or pending
|
|
(Stripe checkout). For Stripe checkout, the customer_product is inserted
|
|
before the customer completes the hosted form. (optional)
|
|
|
|
@param taxRateId - Stripe tax rate ID (txr_...) to apply as the default
|
|
tax rate on the created subscription, invoice, or checkout session line
|
|
items. (optional)
|
|
|
|
|
|
@returns A billing response with customer ID, invoice details, and
|
|
payment URL (if checkout required).
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items / remove_items
|
|
/ deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval (reset-side,
|
|
includes day/hour/minute) so price-less items
|
|
keyed by reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
description: Customize the plan to attach. Can override the price, items, free
|
|
trial, or a combination.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
proration_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: How to handle proration when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'none' skips creating any charges.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Can be used to target
|
|
specific subscriptions in update operations when a customer
|
|
has multiple products with the same plan.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Reset the billing cycle anchor immediately with 'now'.
|
|
plan_schedule:
|
|
enum:
|
|
- immediate
|
|
- end_of_cycle
|
|
type: string
|
|
description: When the plan change should take effect. 'immediate' applies now,
|
|
'end_of_cycle' schedules for the end of the current billing
|
|
cycle. By default, upgrades are immediate and downgrades are
|
|
scheduled.
|
|
starts_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
start. Future dates create a scheduled subscription.
|
|
ends_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
end.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
custom_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Amount in dollars for this line item (e.g. 10.50). Can be negative
|
|
for credits.
|
|
description:
|
|
type: string
|
|
description: Description for the line item.
|
|
required:
|
|
- amount
|
|
- description
|
|
description: Custom line items that override the auto-generated proration
|
|
invoice. Only valid for immediate plan changes (eg. upgrades
|
|
or one off plans).
|
|
processor_subscription_id:
|
|
type: string
|
|
description: The processor subscription ID to link. Use this to attach an
|
|
existing Stripe subscription instead of creating a new one.
|
|
carry_over_balances:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over balances from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over balances from. If left
|
|
undefined, all features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over balances from the previous plan.
|
|
carry_over_usages:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over usages from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over usages for. If left
|
|
undefined, all consumable features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over usages from the previous plan.
|
|
metadata:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: string
|
|
description: Key-value metadata to attach to the Stripe subscription, invoice,
|
|
and checkout session created during this attach flow. Keys
|
|
prefixed with 'autumn_' are reserved and will be stripped.
|
|
no_billing_changes:
|
|
type: boolean
|
|
description: If true, skips any billing changes for the attach operation.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the customer's plan is activated immediately even when
|
|
payment is deferred (invoice mode) or pending (Stripe
|
|
checkout). For Stripe checkout, the customer_product is
|
|
inserted before the customer completes the hosted form.
|
|
tax_rate_id:
|
|
type: string
|
|
description: Stripe tax rate ID (txr_...) to apply as the default tax rate on
|
|
the created subscription, invoice, or checkout session line
|
|
items.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: AttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if the plan was attached to an entity.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
type: string
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
description: Details about any action required to complete the payment. Present
|
|
when the payment could not be processed automatically.
|
|
required:
|
|
- customer_id
|
|
- payment_url
|
|
examples:
|
|
- customer_id: cus_123
|
|
payment_url: https://checkout.stripe.com/...
|
|
x-speakeasy-name-override: attach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.create_schedule:
|
|
post:
|
|
operationId: createSchedule
|
|
description: |-
|
|
Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times.
|
|
|
|
Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time.
|
|
|
|
@example
|
|
```typescript
|
|
// Schedule a transition from a trial plan to a paid plan
|
|
const response = await client.billing.createSchedule({ customerId: "cus_123", phases: [{"startsAt":1781265695558,"plans":[{"planId":"trial_plan"}]},{"startsAt":1782475295558,"plans":[{"planId":"pro_plan"}]}] });
|
|
```
|
|
|
|
@param customerId - The ID of the customer to create the schedule for.
|
|
@param entityId - Optional entity ID for an entity-scoped schedule. (optional)
|
|
@param invoiceMode - Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. (optional)
|
|
@param discounts - List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
@param successUrl - URL to redirect to after successful checkout. (optional)
|
|
@param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional)
|
|
@param redirectMode - Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if_required' only redirects when needed, and 'never' disables redirects. (optional)
|
|
@param billingBehavior - Whether to prorate the immediate phase. 'none' skips proration charges and credits. (optional)
|
|
@param billingCycleAnchor - Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time. (optional)
|
|
@param enablePlanImmediately - If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed. (optional)
|
|
@param phases - Ordered phase definitions for the schedule.
|
|
|
|
@returns A create-schedule response with the schedule ID, persisted phases, and any required payment or checkout URL.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the schedule for.
|
|
entity_id:
|
|
type: string
|
|
description: Optional entity ID for an entity-scoped schedule.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates and sends an invoice instead of charging the
|
|
customer's payment method immediately for the first phase.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply to the immediate phase. Each discount
|
|
can be an Autumn reward ID, Stripe coupon ID, or Stripe
|
|
promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL for the immediate phase.
|
|
'always' forces a confirmation or checkout flow,
|
|
'if_required' only redirects when needed, and 'never'
|
|
disables redirects.
|
|
default: if_required
|
|
billing_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: Whether to prorate the immediate phase. 'none' skips proration
|
|
charges and credits.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Pass 'now' to reset the billing cycle anchor of the immediate phase
|
|
to the current time.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the immediate-phase cusProducts are activated immediately
|
|
(and scheduled-phase cusProducts pre-inserted) even when
|
|
payment is pending via Stripe checkout. The Autumn schedule
|
|
rows are persisted on checkout.session.completed.
|
|
phases:
|
|
type: array
|
|
prefixItems:
|
|
- type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: When this phase should start, in epoch milliseconds.
|
|
plans:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to schedule in this phase.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: Optional prepaid feature quantities for this phase's plan.
|
|
version:
|
|
type: number
|
|
description: Optional explicit plan version to schedule.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to: {}
|
|
amount: {}
|
|
flat_amount: {}
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101
|
|
rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400
|
|
total. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with
|
|
max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items
|
|
/ remove_items / deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to: {}
|
|
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:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400
|
|
total. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with
|
|
max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval
|
|
(reset-side, includes
|
|
day/hour/minute) so price-less items
|
|
keyed by reset.interval can be
|
|
disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in
|
|
count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
description: Customize the plan to schedule. Can override price, replace items,
|
|
or patch items with add_items and
|
|
remove_items.
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Useful when scheduling
|
|
the same plan multiple times.
|
|
required:
|
|
- plan_id
|
|
description: Plans to materialize for this phase.
|
|
required:
|
|
- starts_at
|
|
- plans
|
|
items:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: When this phase should start, in epoch milliseconds.
|
|
plans:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to schedule in this phase.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: Optional prepaid feature quantities for this phase's plan.
|
|
version:
|
|
type: number
|
|
description: Optional explicit plan version to schedule.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to: {}
|
|
amount: {}
|
|
flat_amount: {}
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds
|
|
to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with
|
|
max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items /
|
|
remove_items / deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to: {}
|
|
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:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with
|
|
max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval
|
|
(reset-side, includes day/hour/minute)
|
|
so price-less items keyed by
|
|
reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in
|
|
count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
description: Customize the plan to schedule. Can override price, replace items,
|
|
or patch items with add_items and remove_items.
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Useful when scheduling
|
|
the same plan multiple times.
|
|
required:
|
|
- plan_id
|
|
description: Plans to materialize for this phase.
|
|
required:
|
|
- starts_at
|
|
- plans
|
|
description: Ordered phase definitions for the schedule.
|
|
required:
|
|
- customer_id
|
|
- phases
|
|
title: CreateScheduleParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
phases:
|
|
- starts_at: 1735689600000
|
|
plans:
|
|
- plan_id: trial_plan
|
|
- starts_at: 1736899200000
|
|
plans:
|
|
- plan_id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The entity ID for the schedule, or null when customer-level.
|
|
status:
|
|
enum:
|
|
- created
|
|
- pending_payment
|
|
type: string
|
|
description: Whether the schedule is fully created or waiting for payment or
|
|
confirmation to complete.
|
|
schedule_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the created schedule. Null when the schedule is waiting
|
|
on Autumn checkout confirmation.
|
|
phases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
phase_id:
|
|
type: string
|
|
description: The ID of the persisted phase row.
|
|
starts_at:
|
|
type: number
|
|
description: When this phase starts, in epoch milliseconds.
|
|
customer_product_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Customer products materialized for this phase.
|
|
required:
|
|
- phase_id
|
|
- starts_at
|
|
- customer_product_ids
|
|
description: Persisted phases in ascending starts_at order. Empty when waiting
|
|
on Autumn checkout confirmation.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
type: string
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
required:
|
|
- customer_id
|
|
- entity_id
|
|
- status
|
|
- schedule_id
|
|
- phases
|
|
- payment_url
|
|
title: CreateScheduleResponse
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: null
|
|
status: created
|
|
schedule_id: sch_1234
|
|
phases:
|
|
- phase_id: sphs_1111
|
|
starts_at: 1735689600000
|
|
customer_product_ids:
|
|
- cus_prod_1111
|
|
- phase_id: sphs_2222
|
|
starts_at: 1736899200000
|
|
customer_product_ids:
|
|
- cus_prod_2222
|
|
invoice: null
|
|
payment_url: null
|
|
x-speakeasy-name-override: createSchedule
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.multi_attach:
|
|
post:
|
|
operationId: multiAttach
|
|
description: |-
|
|
Attaches multiple plans to a customer in a single request. Creates a single Stripe subscription with all plans consolidated.
|
|
|
|
Use this endpoint when you need to subscribe a customer to multiple plans at once, such as a base plan plus add-ons, or to create a bundle of products.
|
|
|
|
@example
|
|
```typescript
|
|
// Attach multiple plans to a customer
|
|
const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_seats","featureQuantities":[{"featureId":"seats","quantity":5}]}] });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Attach with free trial applied to all plans
|
|
const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_storage"}], freeTrial: {"durationLength":14,"durationType":"day"} });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Attach with custom pricing on one plan
|
|
const response = await client.billing.multiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan","customize":{"price":{"amount":4900,"interval":"month"}}},{"planId":"addon_support"}] });
|
|
```
|
|
|
|
@param customerId - The ID of the customer to attach the plans to.
|
|
@param entityId - The ID of the entity to attach the plans to. (optional)
|
|
@param plans - The list of plans to attach to the customer.
|
|
@param freeTrial - Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. (optional)
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. (optional)
|
|
@param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
@param successUrl - URL to redirect to after successful checkout. (optional)
|
|
@param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional)
|
|
@param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional)
|
|
@param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional)
|
|
@param enablePlanImmediately - If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. (optional)
|
|
|
|
@returns A billing response with customer ID, invoice details, and payment URL (if checkout required).
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plans to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plans to.
|
|
plans:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null
|
|
for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan.
|
|
description: Customize the plan to attach. Can override the price or items.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Useful when attaching
|
|
the same plan multiple times.
|
|
required:
|
|
- plan_id
|
|
description: The list of plans to attach to the customer.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores
|
|
the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Free trial configuration applied to all plans. Pass an object to
|
|
set a custom trial, or null to remove any trial.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the cusProducts are activated immediately even when
|
|
payment is pending via Stripe checkout.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
entity_data:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID that this entity is associated with
|
|
name:
|
|
type: string
|
|
description: Name of the entity
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
required:
|
|
- feature_id
|
|
required:
|
|
- customer_id
|
|
- plans
|
|
title: MultiAttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plans:
|
|
- plan_id: pro_plan
|
|
- plan_id: addon_seats
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 5
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if the plan was attached to an entity.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
type: string
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
description: Details about any action required to complete the payment. Present
|
|
when the payment could not be processed automatically.
|
|
required:
|
|
- customer_id
|
|
- payment_url
|
|
examples:
|
|
- customer_id: cus_123
|
|
invoice:
|
|
status: paid
|
|
stripe_id: in_1234
|
|
total: 4900
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/...
|
|
payment_url: null
|
|
x-speakeasy-name-override: multiAttach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.preview_attach:
|
|
post:
|
|
operationId: previewAttach
|
|
description: >-
|
|
Previews the billing changes that would occur when attaching a plan,
|
|
without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers what they will be charged before
|
|
confirming a subscription change.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Preview attaching a plan
|
|
|
|
const response = await client.billing.previewAttach({ customerId:
|
|
"cus_123", planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan.
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param customize - Customize the plan to attach. Can override the price,
|
|
items, free trial, or a combination. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param prorationBehavior - How to handle proration when updating an
|
|
existing subscription. 'prorate_immediately' charges/credits prorated
|
|
amounts now, 'none' skips creating any charges. (optional)
|
|
|
|
@param redirectMode - Controls when to return a checkout URL. 'always'
|
|
returns a URL even if payment succeeds, 'if_required' only when payment
|
|
action is needed, 'never' disables redirects. (optional)
|
|
|
|
@param subscriptionId - A unique ID to identify this subscription. Can
|
|
be used to target specific subscriptions in update operations when a
|
|
customer has multiple products with the same plan. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param successUrl - URL to redirect to after successful checkout.
|
|
(optional)
|
|
|
|
@param newBillingSubscription - Only applicable when the customer has an
|
|
existing Stripe subscription. If true, creates a new separate
|
|
subscription instead of merging into the existing one. (optional)
|
|
|
|
@param billingCycleAnchor - Reset the billing cycle anchor immediately
|
|
with 'now'. (optional)
|
|
|
|
@param planSchedule - When the plan change should take effect.
|
|
'immediate' applies now, 'end_of_cycle' schedules for the end of the
|
|
current billing cycle. By default, upgrades are immediate and downgrades
|
|
are scheduled. (optional)
|
|
|
|
@param startsAt - Unix timestamp in milliseconds for when the attached
|
|
plan should start. Future dates create a scheduled subscription.
|
|
(optional)
|
|
|
|
@param endsAt - Unix timestamp in milliseconds for when the attached
|
|
plan should end. (optional)
|
|
|
|
@param checkoutSessionParams - Additional parameters to pass into the
|
|
creation of the Stripe checkout session. (optional)
|
|
|
|
@param customLineItems - Custom line items that override the
|
|
auto-generated proration invoice. Only valid for immediate plan changes
|
|
(eg. upgrades or one off plans). (optional)
|
|
|
|
@param processorSubscriptionId - The processor subscription ID to link.
|
|
Use this to attach an existing Stripe subscription instead of creating a
|
|
new one. (optional)
|
|
|
|
@param carryOverBalances - Whether to carry over balances from the
|
|
previous plan. (optional)
|
|
|
|
@param carryOverUsages - Whether to carry over usages from the previous
|
|
plan. (optional)
|
|
|
|
@param metadata - Key-value metadata to attach to the Stripe
|
|
subscription, invoice, and checkout session created during this attach
|
|
flow. Keys prefixed with 'autumn_' are reserved and will be stripped.
|
|
(optional)
|
|
|
|
@param noBillingChanges - If true, skips any billing changes for the
|
|
attach operation. (optional)
|
|
|
|
@param enablePlanImmediately - If true, the customer's plan is activated
|
|
immediately even when payment is deferred (invoice mode) or pending
|
|
(Stripe checkout). For Stripe checkout, the customer_product is inserted
|
|
before the customer completes the hosted form. (optional)
|
|
|
|
@param taxRateId - Stripe tax rate ID (txr_...) to apply as the default
|
|
tax rate on the created subscription, invoice, or checkout session line
|
|
items. (optional)
|
|
|
|
|
|
@returns A preview response with line items, totals, and effective dates
|
|
for the proposed changes.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items / remove_items
|
|
/ deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval (reset-side,
|
|
includes day/hour/minute) so price-less items
|
|
keyed by reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
description: Customize the plan to attach. Can override the price, items, free
|
|
trial, or a combination.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
proration_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: How to handle proration when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'none' skips creating any charges.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Can be used to target
|
|
specific subscriptions in update operations when a customer
|
|
has multiple products with the same plan.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Reset the billing cycle anchor immediately with 'now'.
|
|
plan_schedule:
|
|
enum:
|
|
- immediate
|
|
- end_of_cycle
|
|
type: string
|
|
description: When the plan change should take effect. 'immediate' applies now,
|
|
'end_of_cycle' schedules for the end of the current billing
|
|
cycle. By default, upgrades are immediate and downgrades are
|
|
scheduled.
|
|
starts_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
start. Future dates create a scheduled subscription.
|
|
ends_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
end.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
custom_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Amount in dollars for this line item (e.g. 10.50). Can be negative
|
|
for credits.
|
|
description:
|
|
type: string
|
|
description: Description for the line item.
|
|
required:
|
|
- amount
|
|
- description
|
|
description: Custom line items that override the auto-generated proration
|
|
invoice. Only valid for immediate plan changes (eg. upgrades
|
|
or one off plans).
|
|
processor_subscription_id:
|
|
type: string
|
|
description: The processor subscription ID to link. Use this to attach an
|
|
existing Stripe subscription instead of creating a new one.
|
|
carry_over_balances:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over balances from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over balances from. If left
|
|
undefined, all features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over balances from the previous plan.
|
|
carry_over_usages:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over usages from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over usages for. If left
|
|
undefined, all consumable features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over usages from the previous plan.
|
|
metadata:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: string
|
|
description: Key-value metadata to attach to the Stripe subscription, invoice,
|
|
and checkout session created during this attach flow. Keys
|
|
prefixed with 'autumn_' are reserved and will be stripped.
|
|
no_billing_changes:
|
|
type: boolean
|
|
description: If true, skips any billing changes for the attach operation.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the customer's plan is activated immediately even when
|
|
payment is deferred (invoice mode) or pending (Stripe
|
|
checkout). For Stripe checkout, the customer_product is
|
|
inserted before the customer completes the hosted form.
|
|
tax_rate_id:
|
|
type: string
|
|
description: Stripe tax rate ID (txr_...) to apply as the default tax rate on
|
|
the created subscription, invoice, or checkout session line
|
|
items.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: PreviewAttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name or
|
|
the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the current
|
|
billing period.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the current
|
|
billing period.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
next_cycle:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the next
|
|
cycle.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the next
|
|
cycle.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
description: List of line items for the next billing cycle.
|
|
usage_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
required:
|
|
- display_name
|
|
- plan_id
|
|
- feature_id
|
|
description: List of line items for usage-based features in the next cycle.
|
|
required:
|
|
- starts_at
|
|
- subtotal
|
|
- total
|
|
- line_items
|
|
- usage_line_items
|
|
description: Preview of the next billing cycle, if applicable. This shows what
|
|
the customer will be charged in subsequent cycles.
|
|
expand:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Expand the response with additional data.
|
|
incoming:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being added or updated.
|
|
outgoing:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being removed or ended.
|
|
redirect_to_checkout:
|
|
type: boolean
|
|
description: Whether the customer will be redirected to a checkout page if
|
|
attach is called.
|
|
checkout_type:
|
|
anyOf:
|
|
- enum:
|
|
- stripe_checkout
|
|
- autumn_checkout
|
|
type: string
|
|
- type: "null"
|
|
description: The type of checkout that will be used if the customer is
|
|
redirected to a checkout page.
|
|
tax:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: number
|
|
description: Total tax amount in major currency units.
|
|
amount_inclusive:
|
|
type: number
|
|
description: Tax included in line item subtotals.
|
|
amount_exclusive:
|
|
type: number
|
|
description: Tax added on top of subtotals.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
status:
|
|
enum:
|
|
- complete
|
|
- incomplete
|
|
type: string
|
|
description: Calculation status ('complete' when Stripe Tax succeeds or
|
|
'incomplete' when Stripe Tax returned 0 or errored).
|
|
required:
|
|
- total
|
|
- amount_inclusive
|
|
- amount_exclusive
|
|
- currency
|
|
- status
|
|
description: Tax preview for the immediate charge. Contact us to enable the tax
|
|
flag on your organisation. Shows only with flag enabled, a
|
|
Stripe customer exists and has a location.
|
|
invoice_credits:
|
|
type: object
|
|
properties:
|
|
balance:
|
|
type: number
|
|
description: Stripe customer credit balance available, expressed as a positive
|
|
number in major currency units.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
required:
|
|
- balance
|
|
- currency
|
|
description: Stripe customer invoice credits preview.
|
|
required:
|
|
- customer_id
|
|
- line_items
|
|
- subtotal
|
|
- total
|
|
- currency
|
|
- incoming
|
|
- outgoing
|
|
- redirect_to_checkout
|
|
- checkout_type
|
|
examples:
|
|
- customerId: charles
|
|
lineItems:
|
|
- display_name: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
subtotal: 20
|
|
total: 20
|
|
discounts: []
|
|
subtotal: 20
|
|
total: 20
|
|
currency: usd
|
|
x-speakeasy-name-override: previewAttach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.preview_multi_attach:
|
|
post:
|
|
operationId: previewMultiAttach
|
|
description: |-
|
|
Previews the billing changes that would occur when attaching multiple plans, without actually making any changes.
|
|
|
|
Use this endpoint to show customers what they will be charged before confirming a multi-plan subscription.
|
|
|
|
@example
|
|
```typescript
|
|
// Preview attaching multiple plans
|
|
const response = await client.billing.previewMultiAttach({ customerId: "cus_123", plans: [{"planId":"pro_plan"},{"planId":"addon_seats","featureQuantities":[{"featureId":"seats","quantity":5}]}] });
|
|
```
|
|
|
|
@param customerId - The ID of the customer to attach the plans to.
|
|
@param entityId - The ID of the entity to attach the plans to. (optional)
|
|
@param plans - The list of plans to attach to the customer.
|
|
@param freeTrial - Free trial configuration applied to all plans. Pass an object to set a custom trial, or null to remove any trial. (optional)
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. (optional)
|
|
@param discounts - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
@param successUrl - URL to redirect to after successful checkout. (optional)
|
|
@param checkoutSessionParams - Additional parameters to pass into the creation of the Stripe checkout session. (optional)
|
|
@param redirectMode - Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects. (optional)
|
|
@param newBillingSubscription - Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. (optional)
|
|
@param enablePlanImmediately - If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. (optional)
|
|
|
|
@returns A preview response with line items, totals, and effective dates for the proposed multi-plan attachment.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plans to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plans to.
|
|
plans:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null
|
|
for no limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan.
|
|
description: Customize the plan to attach. Can override the price or items.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Useful when attaching
|
|
the same plan multiple times.
|
|
required:
|
|
- plan_id
|
|
description: The list of plans to attach to the customer.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and restores
|
|
the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Free trial configuration applied to all plans. Pass an object to
|
|
set a custom trial, or null to remove any trial.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the cusProducts are activated immediately even when
|
|
payment is pending via Stripe checkout.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
entity_data:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID that this entity is associated with
|
|
name:
|
|
type: string
|
|
description: Name of the entity
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
required:
|
|
- feature_id
|
|
required:
|
|
- customer_id
|
|
- plans
|
|
title: PreviewMultiAttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plans:
|
|
- plan_id: pro_plan
|
|
- plan_id: addon_seats
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 5
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name or
|
|
the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the current
|
|
billing period.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the current
|
|
billing period.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
next_cycle:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the next
|
|
cycle.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the next
|
|
cycle.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
description: List of line items for the next billing cycle.
|
|
usage_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
required:
|
|
- display_name
|
|
- plan_id
|
|
- feature_id
|
|
description: List of line items for usage-based features in the next cycle.
|
|
required:
|
|
- starts_at
|
|
- subtotal
|
|
- total
|
|
- line_items
|
|
- usage_line_items
|
|
description: Preview of the next billing cycle, if applicable. This shows what
|
|
the customer will be charged in subsequent cycles.
|
|
expand:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Expand the response with additional data.
|
|
incoming:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being added or updated.
|
|
outgoing:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being removed or ended.
|
|
redirect_to_checkout:
|
|
type: boolean
|
|
description: Whether the customer will be redirected to a checkout page if
|
|
attach is called.
|
|
checkout_type:
|
|
anyOf:
|
|
- enum:
|
|
- stripe_checkout
|
|
- autumn_checkout
|
|
type: string
|
|
- type: "null"
|
|
description: The type of checkout that will be used if the customer is
|
|
redirected to a checkout page.
|
|
tax:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: number
|
|
description: Total tax amount in major currency units.
|
|
amount_inclusive:
|
|
type: number
|
|
description: Tax included in line item subtotals.
|
|
amount_exclusive:
|
|
type: number
|
|
description: Tax added on top of subtotals.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
status:
|
|
enum:
|
|
- complete
|
|
- incomplete
|
|
type: string
|
|
description: Calculation status ('complete' when Stripe Tax succeeds or
|
|
'incomplete' when Stripe Tax returned 0 or errored).
|
|
required:
|
|
- total
|
|
- amount_inclusive
|
|
- amount_exclusive
|
|
- currency
|
|
- status
|
|
description: Tax preview for the immediate charge. Contact us to enable the tax
|
|
flag on your organisation. Shows only with flag enabled, a
|
|
Stripe customer exists and has a location.
|
|
invoice_credits:
|
|
type: object
|
|
properties:
|
|
balance:
|
|
type: number
|
|
description: Stripe customer credit balance available, expressed as a positive
|
|
number in major currency units.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
required:
|
|
- balance
|
|
- currency
|
|
description: Stripe customer invoice credits preview.
|
|
required:
|
|
- customer_id
|
|
- line_items
|
|
- subtotal
|
|
- total
|
|
- currency
|
|
- incoming
|
|
- outgoing
|
|
- redirect_to_checkout
|
|
- checkout_type
|
|
examples:
|
|
- customerId: charles
|
|
lineItems:
|
|
- display_name: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
subtotal: 20
|
|
total: 20
|
|
discounts: []
|
|
subtotal: 20
|
|
total: 20
|
|
currency: usd
|
|
x-speakeasy-name-override: previewMultiAttach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.update:
|
|
post:
|
|
operationId: billingUpdate
|
|
description: >-
|
|
Updates an existing subscription. Use to modify feature quantities,
|
|
cancel, or change plan configuration.
|
|
|
|
|
|
Use this endpoint to update prepaid quantities, cancel a subscription
|
|
(immediately or at end of cycle), or modify subscription settings.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Update prepaid feature quantity
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", featureQuantities:
|
|
[{"featureId":"seats","quantity":10}] });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Cancel a subscription at end of billing cycle
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", cancelAction: "cancel_end_of_cycle" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Uncancel a subscription at the end of the billing cycle
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", cancelAction: "uncancel" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan to update. Optional if
|
|
subscription_id is provided, or if the customer has only one product.
|
|
(optional)
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param customize - Customize the plan to attach. Can override the price,
|
|
items, free trial, or a combination. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param prorationBehavior - How to handle proration when updating an
|
|
existing subscription. 'prorate_immediately' charges/credits prorated
|
|
amounts now, 'none' skips creating any charges. (optional)
|
|
|
|
@param redirectMode - Controls when to return a checkout URL. 'always'
|
|
returns a URL even if payment succeeds, 'if_required' only when payment
|
|
action is needed, 'never' disables redirects. (optional)
|
|
|
|
@param subscriptionId - A unique ID to identify this subscription. Can
|
|
be used to target specific subscriptions in update operations when a
|
|
customer has multiple products with the same plan. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param cancelAction - Action to perform for cancellation.
|
|
'cancel_immediately' cancels now with prorated refund,
|
|
'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a
|
|
pending cancellation. (optional)
|
|
|
|
@param billingCycleAnchor - Reset the billing cycle anchor immediately
|
|
with 'now' (optional)
|
|
|
|
@param noBillingChanges - If true, the subscription is updated
|
|
internally without applying billing changes in Stripe. (optional)
|
|
|
|
@param recalculateBalances - Controls whether balances should be
|
|
recalculated during the subscription update. (optional)
|
|
|
|
|
|
@returns A billing response with customer ID, invoice details, and
|
|
payment URL (if next action is required).
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to update. Optional if subscription_id is
|
|
provided, or if the customer has only one product.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items / remove_items
|
|
/ deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval (reset-side,
|
|
includes day/hour/minute) so price-less items
|
|
keyed by reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
description: Customize the plan to attach. Can override the price, items, free
|
|
trial, or a combination.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
proration_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: How to handle proration when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'none' skips creating any charges.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Can be used to target
|
|
specific subscriptions in update operations when a customer
|
|
has multiple products with the same plan.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
cancel_action:
|
|
enum:
|
|
- cancel_immediately
|
|
- cancel_end_of_cycle
|
|
- uncancel
|
|
type: string
|
|
description: Action to perform for cancellation. 'cancel_immediately' cancels
|
|
now with prorated refund, 'cancel_end_of_cycle' cancels at
|
|
period end, 'uncancel' reverses a pending cancellation.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Reset the billing cycle anchor immediately with 'now'
|
|
no_billing_changes:
|
|
type: boolean
|
|
description: If true, the subscription is updated internally without applying
|
|
billing changes in Stripe.
|
|
recalculate_balances:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: If true, recalculates balances during the subscription update. Only
|
|
applicable when updating feature quantities.
|
|
required:
|
|
- enabled
|
|
description: Controls whether balances should be recalculated during the
|
|
subscription update.
|
|
required:
|
|
- customer_id
|
|
title: UpdateSubscriptionParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 10
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if the plan was attached to an entity.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
type: string
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
description: Details about any action required to complete the payment. Present
|
|
when the payment could not be processed automatically.
|
|
required:
|
|
- customer_id
|
|
- payment_url
|
|
examples:
|
|
- customer_id: cus_123
|
|
invoice:
|
|
status: paid
|
|
stripe_id: in_1234
|
|
total: 1500
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/...
|
|
payment_url: null
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.preview_update:
|
|
post:
|
|
operationId: previewUpdate
|
|
description: >-
|
|
Previews the billing changes that would occur when updating a
|
|
subscription, without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers prorated charges or refunds before
|
|
confirming subscription modifications.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Preview updating seat quantity
|
|
|
|
const response = await client.billing.previewUpdate({ customerId:
|
|
"cus_123", planId: "pro_plan", featureQuantities:
|
|
[{"featureId":"seats","quantity":15}] });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan to update. Optional if
|
|
subscription_id is provided, or if the customer has only one product.
|
|
(optional)
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param customize - Customize the plan to attach. Can override the price,
|
|
items, free trial, or a combination. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param prorationBehavior - How to handle proration when updating an
|
|
existing subscription. 'prorate_immediately' charges/credits prorated
|
|
amounts now, 'none' skips creating any charges. (optional)
|
|
|
|
@param redirectMode - Controls when to return a checkout URL. 'always'
|
|
returns a URL even if payment succeeds, 'if_required' only when payment
|
|
action is needed, 'never' disables redirects. (optional)
|
|
|
|
@param subscriptionId - A unique ID to identify this subscription. Can
|
|
be used to target specific subscriptions in update operations when a
|
|
customer has multiple products with the same plan. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param cancelAction - Action to perform for cancellation.
|
|
'cancel_immediately' cancels now with prorated refund,
|
|
'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a
|
|
pending cancellation. (optional)
|
|
|
|
@param billingCycleAnchor - Reset the billing cycle anchor immediately
|
|
with 'now' (optional)
|
|
|
|
@param noBillingChanges - If true, the subscription is updated
|
|
internally without applying billing changes in Stripe. (optional)
|
|
|
|
@param recalculateBalances - Controls whether balances should be
|
|
recalculated during the subscription update. (optional)
|
|
|
|
|
|
@returns A preview response with line items showing prorated charges or
|
|
credits for the proposed changes.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan to update. Optional if subscription_id is
|
|
provided, or if the customer has only one product.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items / remove_items
|
|
/ deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval (reset-side,
|
|
includes day/hour/minute) so price-less items
|
|
keyed by reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
description: Customize the plan to attach. Can override the price, items, free
|
|
trial, or a combination.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
invoice_template_id:
|
|
type: string
|
|
description: ID of an invoice template (configured in billing settings) whose
|
|
footer (e.g. bank details) is applied to the invoice.
|
|
net_terms_days:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Number of days the customer has to pay the invoice before it is due
|
|
(Stripe days_until_due).
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
proration_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: How to handle proration when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'none' skips creating any charges.
|
|
redirect_mode:
|
|
enum:
|
|
- always
|
|
- if_required
|
|
- never
|
|
type: string
|
|
description: Controls when to return a checkout URL. 'always' returns a URL even
|
|
if payment succeeds, 'if_required' only when payment action
|
|
is needed, 'never' disables redirects.
|
|
default: if_required
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Can be used to target
|
|
specific subscriptions in update operations when a customer
|
|
has multiple products with the same plan.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
cancel_action:
|
|
enum:
|
|
- cancel_immediately
|
|
- cancel_end_of_cycle
|
|
- uncancel
|
|
type: string
|
|
description: Action to perform for cancellation. 'cancel_immediately' cancels
|
|
now with prorated refund, 'cancel_end_of_cycle' cancels at
|
|
period end, 'uncancel' reverses a pending cancellation.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Reset the billing cycle anchor immediately with 'now'
|
|
no_billing_changes:
|
|
type: boolean
|
|
description: If true, the subscription is updated internally without applying
|
|
billing changes in Stripe.
|
|
recalculate_balances:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: If true, recalculates balances during the subscription update. Only
|
|
applicable when updating feature quantities.
|
|
required:
|
|
- enabled
|
|
description: Controls whether balances should be recalculated during the
|
|
subscription update.
|
|
required:
|
|
- customer_id
|
|
title: PreviewUpdateParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 15
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name or
|
|
the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
description: List of line items for the current billing period.
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the current
|
|
billing period.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the current
|
|
billing period.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
next_cycle:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
subtotal:
|
|
type: number
|
|
description: The total amount in cents before discounts and tax for the next
|
|
cycle.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for the next
|
|
cycle.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
subtotal:
|
|
type: number
|
|
description: The amount in cents before discounts and tax for this line item.
|
|
total:
|
|
type: number
|
|
description: The final amount in cents after discounts and tax for this line
|
|
item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount_off:
|
|
type: number
|
|
percent_off:
|
|
type: number
|
|
reward_id:
|
|
type: string
|
|
reward_name:
|
|
type: string
|
|
required:
|
|
- amount_off
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
quantity:
|
|
type: number
|
|
description: The quantity of the line item.
|
|
required:
|
|
- display_name
|
|
- description
|
|
- subtotal
|
|
- total
|
|
- plan_id
|
|
- feature_id
|
|
- quantity
|
|
description: List of line items for the next billing cycle.
|
|
usage_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
display_name:
|
|
type: string
|
|
description: The name of the line item to display to the customer if you're
|
|
building a UI. It will either be the plan name
|
|
or the feature name.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan that this line item belongs to.
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the feature that this line item belongs to.
|
|
period:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: The start of the period in milliseconds since the Unix epoch.
|
|
end:
|
|
type: number
|
|
description: The end of the period in milliseconds since the Unix epoch.
|
|
required:
|
|
- start
|
|
- end
|
|
description: The period of time that this line item is being charged for.
|
|
required:
|
|
- display_name
|
|
- plan_id
|
|
- feature_id
|
|
description: List of line items for usage-based features in the next cycle.
|
|
required:
|
|
- starts_at
|
|
- subtotal
|
|
- total
|
|
- line_items
|
|
- usage_line_items
|
|
description: Preview of the next billing cycle, if applicable. This shows what
|
|
the customer will be charged in subsequent cycles.
|
|
expand:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Expand the response with additional data.
|
|
incoming:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being added or updated.
|
|
outgoing:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan affected by this preview change.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if it was expanded in the response.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the adjustable feature included in this change.
|
|
quantity:
|
|
type: number
|
|
description: The quantity that will apply for this feature in the change.
|
|
required:
|
|
- feature_id
|
|
- quantity
|
|
description: The feature quantity selections associated with this plan change.
|
|
effective_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this change takes effect, in milliseconds since the Unix
|
|
epoch, or null if it applies immediately.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan was canceled, in milliseconds since the Unix epoch,
|
|
or null if it is not canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: When this plan expires, in milliseconds since the Unix epoch, or
|
|
null if it does not expire.
|
|
required:
|
|
- plan_id
|
|
- feature_quantities
|
|
- effective_at
|
|
- canceled_at
|
|
- expires_at
|
|
description: Products or subscription changes being removed or ended.
|
|
intent:
|
|
enum:
|
|
- update_plan
|
|
- update_quantity
|
|
- cancel_immediately
|
|
- cancel_end_of_cycle
|
|
- uncancel
|
|
- none
|
|
type: string
|
|
tax:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: number
|
|
description: Total tax amount in major currency units.
|
|
amount_inclusive:
|
|
type: number
|
|
description: Tax included in line item subtotals.
|
|
amount_exclusive:
|
|
type: number
|
|
description: Tax added on top of subtotals.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
status:
|
|
enum:
|
|
- complete
|
|
- incomplete
|
|
type: string
|
|
description: Calculation status ('complete' when Stripe Tax succeeds or
|
|
'incomplete' when Stripe Tax returned 0 or errored).
|
|
required:
|
|
- total
|
|
- amount_inclusive
|
|
- amount_exclusive
|
|
- currency
|
|
- status
|
|
description: Tax preview for the immediate charge. Contact us to enable the tax
|
|
flag on your organisation. Shows only with flag enabled, a
|
|
Stripe customer exists and has a location.
|
|
invoice_credits:
|
|
type: object
|
|
properties:
|
|
balance:
|
|
type: number
|
|
description: Stripe customer credit balance available, expressed as a positive
|
|
number in major currency units.
|
|
currency:
|
|
type: string
|
|
description: Three-letter currency code.
|
|
required:
|
|
- balance
|
|
- currency
|
|
description: Stripe customer invoice credits preview.
|
|
required:
|
|
- customer_id
|
|
- line_items
|
|
- subtotal
|
|
- total
|
|
- currency
|
|
- incoming
|
|
- outgoing
|
|
- intent
|
|
examples:
|
|
- customerId: charles
|
|
lineItems:
|
|
- display_name: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
subtotal: 20
|
|
total: 20
|
|
discounts: []
|
|
subtotal: 20
|
|
total: 20
|
|
currency: usd
|
|
x-speakeasy-name-override: previewUpdate
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.open_customer_portal:
|
|
post:
|
|
operationId: openCustomerPortal
|
|
description: Create a billing portal session for a customer to manage their
|
|
subscription.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to open the billing portal for.
|
|
configuration_id:
|
|
type: string
|
|
description: Stripe billing portal configuration ID. Create configurations in
|
|
your Stripe dashboard.
|
|
return_url:
|
|
type: string
|
|
description: URL to redirect to when back button is clicked in the billing
|
|
portal
|
|
required:
|
|
- customer_id
|
|
title: OpenCustomerPortalParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
return_url: https://useautumn.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the billing portal session
|
|
url:
|
|
type: string
|
|
description: URL to the billing portal
|
|
required:
|
|
- customer_id
|
|
- url
|
|
examples:
|
|
- customer_id: cus_123
|
|
url: https://billing.stripe.com/session/...
|
|
x-speakeasy-name-override: openCustomerPortal
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.setup_payment:
|
|
post:
|
|
operationId: setupPayment
|
|
description: Create a payment setup session for a customer to add or update
|
|
their payment method.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: If specified, the plan will be attached to the customer after
|
|
setup.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to set quantity for.
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
description: The quantity of the feature.
|
|
adjustable:
|
|
type: boolean
|
|
description: Whether the customer can adjust the quantity.
|
|
required:
|
|
- feature_id
|
|
title: FeatureQuantity
|
|
description: Quantity configuration for a prepaid feature.
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
title: BasePrice
|
|
description: Base price configuration for a plan.
|
|
- type: "null"
|
|
description: Override the base price of the plan. Pass null to remove the base
|
|
price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Override the items in the plan (PUT-style — replaces all existing
|
|
items). Mutually exclusive with add_items / remove_items
|
|
/ deprecated update_items.
|
|
add_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
description: Tiered pricing. Either 'amount' or 'tiers' is required.
|
|
tier_behavior:
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
max_percentage:
|
|
type: number
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
title: PlanItem
|
|
description: Configuration for a feature item in a plan, including usage limits,
|
|
pricing, and rollover settings.
|
|
description: Items to add to the plan.
|
|
remove_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Match items linked to this feature.
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
type: string
|
|
description: Match items with this billing method (prepaid or usage_based).
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Match items with this interval. Accepts either a BillingInterval
|
|
(price-side) or a ResetInterval (reset-side,
|
|
includes day/hour/minute) so price-less items
|
|
keyed by reset.interval can be disambiguated.
|
|
interval_count:
|
|
type: integer
|
|
minimum: -9007199254740991
|
|
maximum: 9007199254740991
|
|
exclusiveMinimum: 0
|
|
description: Match items with this interval_count. Disambiguates between items
|
|
that share an interval but differ in count.
|
|
title: PlanItemFilter
|
|
description: Filter for matching plan items. All provided fields must match
|
|
(AND).
|
|
description: Filters selecting items to remove from the plan.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
on_end:
|
|
enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial and
|
|
restores the customer's previous plan.
|
|
required:
|
|
- duration_length
|
|
title: FreeTrialParams
|
|
description: Free trial configuration for a plan.
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
description: Customize the plan to attach. Can override the price, items, free
|
|
trial, or a combination.
|
|
proration_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- none
|
|
type: string
|
|
description: How to handle proration when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'none' skips creating any charges.
|
|
subscription_id:
|
|
type: string
|
|
description: A unique ID to identify this subscription. Can be used to target
|
|
specific subscriptions in update operations when a customer
|
|
has multiple products with the same plan.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
title: AttachDiscount
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
billing_cycle_anchor:
|
|
const: now
|
|
description: Reset the billing cycle anchor immediately with 'now'.
|
|
starts_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
start. Future dates create a scheduled subscription.
|
|
ends_at:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Unix timestamp in milliseconds for when the attached plan should
|
|
end.
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters to pass into the creation of the Stripe
|
|
checkout session.
|
|
custom_line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Amount in dollars for this line item (e.g. 10.50). Can be negative
|
|
for credits.
|
|
description:
|
|
type: string
|
|
description: Description for the line item.
|
|
required:
|
|
- amount
|
|
- description
|
|
description: Custom line items that override the auto-generated proration
|
|
invoice. Only valid for immediate plan changes (eg. upgrades
|
|
or one off plans).
|
|
processor_subscription_id:
|
|
type: string
|
|
description: The processor subscription ID to link. Use this to attach an
|
|
existing Stripe subscription instead of creating a new one.
|
|
carry_over_balances:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over balances from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over balances from. If left
|
|
undefined, all features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over balances from the previous plan.
|
|
carry_over_usages:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Whether to carry over usages from the previous plan.
|
|
feature_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: The IDs of the features to carry over usages for. If left
|
|
undefined, all consumable features will be carried over.
|
|
required:
|
|
- enabled
|
|
description: Whether to carry over usages from the previous plan.
|
|
metadata:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: string
|
|
description: Key-value metadata to attach to the Stripe subscription, invoice,
|
|
and checkout session created during this attach flow. Keys
|
|
prefixed with 'autumn_' are reserved and will be stripped.
|
|
no_billing_changes:
|
|
type: boolean
|
|
description: If true, skips any billing changes for the attach operation.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
description: If true, the customer's plan is activated immediately even when
|
|
payment is deferred (invoice mode) or pending (Stripe
|
|
checkout). For Stripe checkout, the customer_product is
|
|
inserted before the customer completes the hosted form.
|
|
tax_rate_id:
|
|
type: string
|
|
description: Stripe tax rate ID (txr_...) to apply as the default tax rate on
|
|
the created subscription, invoice, or checkout session line
|
|
items.
|
|
required:
|
|
- customer_id
|
|
title: SetupPaymentParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
success_url: https://example.com/account/billing
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity the plan (if specified) will be attached to
|
|
after setup.
|
|
url:
|
|
type: string
|
|
description: URL to redirect the customer to setup their payment.
|
|
required:
|
|
- customer_id
|
|
- url
|
|
title: SetupPaymentResponse
|
|
examples:
|
|
- customer_id: cus_123
|
|
url: https://checkout.stripe.com/...
|
|
x-speakeasy-name-override: setupPayment
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.create:
|
|
post:
|
|
operationId: createBalance
|
|
description: Create a balance for a customer feature.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
included_grant:
|
|
type: number
|
|
description: The initial balance amount to grant. For metered features, this is
|
|
the number of units the customer can use.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, the balance has unlimited usage. Cannot be combined with
|
|
'included_grant'.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: The interval at which the balance resets (e.g., 'month', 'day',
|
|
'year').
|
|
interval_count:
|
|
type: number
|
|
description: "Number of intervals between resets. Defaults to 1 (e.g.,
|
|
interval_count: 2 with interval: 'month' resets every 2
|
|
months)."
|
|
required:
|
|
- interval
|
|
description: Reset configuration for the balance. If not provided, the balance
|
|
is a one-time grant that never resets.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
duration:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
default: month
|
|
length:
|
|
type: number
|
|
required:
|
|
- length
|
|
description: Rollover configuration for the balance.
|
|
expires_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the balance expires. Mutually
|
|
exclusive with reset.
|
|
balance_id:
|
|
type: string
|
|
description: A unique identifier for this balance. Use this to target the
|
|
balance in future update / delete calls.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CreateBalanceParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
included: 1000
|
|
reset:
|
|
interval: month
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.update:
|
|
post:
|
|
operationId: updateBalance
|
|
description: Update a customer balance.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
remaining:
|
|
type: number
|
|
description: Set the remaining balance to this exact value. Cannot be combined
|
|
with add_to_balance.
|
|
add_to_balance:
|
|
type: number
|
|
description: Add this amount to the current balance. Use negative values to
|
|
subtract. Cannot be combined with current_balance.
|
|
usage:
|
|
type: number
|
|
description: The usage amount to update. Cannot be combined with remaining or
|
|
add_to_balance.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Target a specific balance by its reset interval. Use when the
|
|
customer has multiple balances for the same feature with
|
|
different reset intervals.
|
|
included_grant:
|
|
type: number
|
|
description: Set the granted balance to this exact value.
|
|
balance_id:
|
|
type: string
|
|
description: Target a specific balance by its ID (set on create). Use when the
|
|
customer has multiple balances for the same feature.
|
|
next_reset_at:
|
|
type: number
|
|
description: The next reset time for the balance. If there are multiple
|
|
breakdowns, this will update the breakdown with the next
|
|
reset time.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: UpdateBalanceParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
remaining: 5
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.delete:
|
|
post:
|
|
operationId: deleteBalance
|
|
description: Delete a balance for a customer feature. Can only delete a balance
|
|
that is not attached to a price (eg. you cannot delete messages that
|
|
have an overage price).
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
balance_id:
|
|
type: string
|
|
description: The ID of the balance to delete.
|
|
recalculate_balances:
|
|
type: boolean
|
|
description: If true, deduct the deleted balance's remaining amount from the
|
|
customer's other balances for the same feature after
|
|
deletion.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
description: Target a specific balance by its reset interval. Use when the
|
|
customer has multiple balances for the same feature with
|
|
different reset intervals.
|
|
required:
|
|
- customer_id
|
|
title: DeleteBalanceParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.finalize:
|
|
post:
|
|
operationId: finalizeLock
|
|
description: Finalize a previously locked balance. Use 'confirm' to commit the
|
|
deduction, or 'release' to return the held balance.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
lock_id:
|
|
type: string
|
|
description: The lock ID that was passed into the previous check call.
|
|
action:
|
|
enum:
|
|
- confirm
|
|
- release
|
|
type: string
|
|
description: Use 'confirm' to commit the deduction, or 'release' to return the
|
|
held balance.
|
|
override_value:
|
|
type: number
|
|
description: Additional properties to attach to this finalize lock event.
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this finalize lock event.
|
|
required:
|
|
- lock_id
|
|
- action
|
|
title: FinalizeBalanceParams
|
|
examples:
|
|
- lock_id: lock_abc123
|
|
action: confirm
|
|
- lock_id: lock_abc123
|
|
action: confirm
|
|
override_value: 3
|
|
- lock_id: lock_abc123
|
|
action: release
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
"202":
|
|
description: Accepted. Autumn is experiencing degraded service from a downstream
|
|
provider, so the finalize request was allowed fail-open.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: finalize
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.check:
|
|
post:
|
|
operationId: check
|
|
description: >-
|
|
Checks whether a customer currently has enough balance to use a feature.
|
|
|
|
|
|
Use this to gate access before a feature action. Enable sendEvent when
|
|
you want to check and consume balance atomically in one request.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Check access for a feature
|
|
|
|
const response = await client.check({ customerId: "cus_123", featureId:
|
|
"messages" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Check and consume 3 units in one call
|
|
|
|
const response = await client.check({
|
|
customerId: "cus_123",
|
|
featureId: "messages",
|
|
requiredBalance: 3,
|
|
sendEvent: true,
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer.
|
|
|
|
@param featureId - The ID of the feature.
|
|
|
|
@param entityId - The ID of the entity for entity-scoped balances (e.g.,
|
|
per-seat limits). (optional)
|
|
|
|
@param requiredBalance - Minimum balance required for access. Returns
|
|
allowed: false if the customer's balance is below this value. Defaults
|
|
to 1. (optional)
|
|
|
|
@param properties - Additional properties to attach to the usage event
|
|
if send_event is true. (optional)
|
|
|
|
@param sendEvent - If true, atomically records a usage event while
|
|
checking access. The required_balance value is used as the usage amount.
|
|
Combines check + track in one call. (optional)
|
|
|
|
@param lock - Reserve units of a feature upfront by passing a lock_id,
|
|
then call balances.finalize to confirm or release the hold. (optional)
|
|
|
|
@param withPreview - If true, includes upgrade/upsell information in the
|
|
response when access is denied. Useful for displaying paywalls.
|
|
(optional)
|
|
|
|
|
|
@returns Whether access is allowed, plus the current balance for that
|
|
feature. If Autumn is experiencing degraded service from a downstream
|
|
provider, the API may return 202 and allow access fail-open.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
required_balance:
|
|
type: number
|
|
description: "Minimum balance required for access. Returns allowed: false if the
|
|
customer's balance is below this value. Defaults to 1."
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to the usage event if send_event is
|
|
true.
|
|
send_event:
|
|
type: boolean
|
|
description: If true, atomically records a usage event while checking access.
|
|
The required_balance value is used as the usage amount.
|
|
Combines check + track in one call.
|
|
lock:
|
|
type: object
|
|
properties:
|
|
lock_id:
|
|
type: string
|
|
maxLength: 256
|
|
description: A unique identifier for this lock. Used to finalize the lock later
|
|
via balances.finalize.
|
|
enabled:
|
|
const: true
|
|
description: Must be true to enable locking.
|
|
expires_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the lock automatically expires and
|
|
releases the held balance.
|
|
required:
|
|
- lock_id
|
|
- enabled
|
|
description: Reserve units of a feature upfront by passing a lock_id, then call
|
|
balances.finalize to confirm or release the hold.
|
|
with_preview:
|
|
type: boolean
|
|
description: If true, includes upgrade/upsell information in the response when
|
|
access is denied. Useful for displaying paywalls.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CheckParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
required_balance: 3
|
|
send_event: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
allowed:
|
|
type: boolean
|
|
description: Whether the customer is allowed to use the feature. True if they
|
|
have sufficient balance or the feature is
|
|
unlimited/boolean.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer that was checked.
|
|
entity_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the entity, if an entity-scoped check was performed.
|
|
required_balance:
|
|
type: number
|
|
description: The required balance that was checked against.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The customer's balance for this feature. Null if the customer has
|
|
no balance for this feature.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: "Map of feature_id to balance for the checked feature and any
|
|
related features (e.g. linked credit systems). "
|
|
flag:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
- type: "null"
|
|
description: The flag associated with this check, if any.
|
|
preview:
|
|
type: object
|
|
properties:
|
|
scenario:
|
|
enum:
|
|
- usage_limit
|
|
- feature_flag
|
|
type: string
|
|
description: The reason access was denied. 'usage_limit' means the customer
|
|
exceeded their balance, 'feature_flag' means the
|
|
feature is not included in their plan.
|
|
title:
|
|
type: string
|
|
description: A title suitable for displaying in a paywall or upgrade modal.
|
|
message:
|
|
type: string
|
|
description: A message explaining why access was denied.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature that was checked.
|
|
feature_name:
|
|
type: string
|
|
description: The display name of the feature.
|
|
products:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the product you set when creating the product
|
|
name:
|
|
type: string
|
|
description: The name of the product
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Product group which this product belongs to
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment of the product
|
|
is_add_on:
|
|
type: boolean
|
|
description: Whether the product is an add-on and can be purchased alongside
|
|
other products
|
|
is_default:
|
|
type: boolean
|
|
description: Whether the product is the default product
|
|
archived:
|
|
type: boolean
|
|
description: Whether this product has been archived and is no longer available
|
|
version:
|
|
type: number
|
|
description: The current version of the product
|
|
created_at:
|
|
type: number
|
|
description: The timestamp of when the product was created in milliseconds since
|
|
epoch
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
type:
|
|
anyOf:
|
|
- enum:
|
|
- feature
|
|
- priced_feature
|
|
- price
|
|
type: string
|
|
- type: "null"
|
|
description: The type of the product item
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID of the product item. If the item is a fixed price,
|
|
should be `null`
|
|
feature_type:
|
|
anyOf:
|
|
- enum:
|
|
- single_use
|
|
- continuous_use
|
|
- boolean
|
|
- static
|
|
type: string
|
|
- type: "null"
|
|
description: Single use features are used once and then depleted, like API calls
|
|
or credits. Continuous use features are
|
|
those being used on an ongoing-basis, like
|
|
storage or seats.
|
|
included_usage:
|
|
anyOf:
|
|
- anyOf:
|
|
- type: number
|
|
- const: inf
|
|
- type: "null"
|
|
description: The amount of usage included for this feature.
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- type: "null"
|
|
description: The reset or billing interval of the product item. If null, feature
|
|
will have no reset date, and if there's a
|
|
price, it will be billed one-off.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The interval count of the product item.
|
|
price:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The price of the product item. Should be `null` if tiered pricing
|
|
is set.
|
|
tiers:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
- type: "null"
|
|
description: Tiered pricing for the product item. Not applicable for fixed price
|
|
items.
|
|
tier_behavior:
|
|
anyOf:
|
|
- enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
- type: "null"
|
|
description: "How tiers are applied: graduated (split across bands) or volume
|
|
(flat rate for the matched tier). Defaults
|
|
to graduated."
|
|
usage_model:
|
|
anyOf:
|
|
- enum:
|
|
- prepaid
|
|
- pay_per_use
|
|
type: string
|
|
- type: "null"
|
|
description: Whether the feature should be prepaid upfront or billed for how
|
|
much they use end of billing period.
|
|
billing_units:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The amount per billing unit (eg. $9 / 250 units)
|
|
reset_usage_when_enabled:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether the usage should be reset when the product is enabled.
|
|
entity_feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The entity feature ID of the product item if applicable.
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
secondary_text:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- primary_text
|
|
- type: "null"
|
|
description: The display of the product item.
|
|
quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer has
|
|
prepaid for.
|
|
next_cycle_quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer will
|
|
prepay for in the next cycle.
|
|
config:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
rollover:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
duration:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
default: month
|
|
length:
|
|
type: number
|
|
required:
|
|
- length
|
|
- type: "null"
|
|
on_increase:
|
|
anyOf:
|
|
- enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
- type: "null"
|
|
on_decrease:
|
|
anyOf:
|
|
- enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
- type: "null"
|
|
- type: "null"
|
|
description: Configuration for rollover and proration behavior of the feature.
|
|
description: Product item defining features and pricing within a product
|
|
description: Array of product items that define the product's features and
|
|
pricing
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: The duration type of the free trial
|
|
length:
|
|
type: number
|
|
description: The length of the duration type specified
|
|
unique_fingerprint:
|
|
type: boolean
|
|
description: Whether the free trial is limited to one per customer fingerprint
|
|
card_required:
|
|
type: boolean
|
|
description: Whether the free trial requires a card. If false, the customer can
|
|
attach the product without going through
|
|
a checkout flow or having a card on
|
|
file.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial
|
|
and restores the customer's previous
|
|
plan.
|
|
trial_available:
|
|
anyOf:
|
|
- type: boolean
|
|
default: true
|
|
- type: "null"
|
|
description: Used in customer context. Whether the free trial is available for
|
|
the customer if they were to attach the
|
|
product.
|
|
required:
|
|
- duration
|
|
- length
|
|
- unique_fingerprint
|
|
- card_required
|
|
- type: "null"
|
|
description: Free trial configuration for this product, if available
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the base variant this product is derived from
|
|
scenario:
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- new
|
|
- renew
|
|
- upgrade
|
|
- update_prepaid_quantity
|
|
- downgrade
|
|
- cancel
|
|
- expired
|
|
- past_due
|
|
type: string
|
|
description: Scenario for when this product is used in attach flows
|
|
properties:
|
|
type: object
|
|
properties:
|
|
is_free:
|
|
type: boolean
|
|
description: True if the product has no base price or usage prices
|
|
is_one_off:
|
|
type: boolean
|
|
description: True if the product only contains a one-time price
|
|
interval_group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The billing interval group for recurring products (e.g., 'monthly',
|
|
'yearly')
|
|
has_trial:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product includes a free trial
|
|
updateable:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product can be updated after creation (only applicable
|
|
if there are prepaid recurring prices)
|
|
required:
|
|
- is_free
|
|
- is_one_off
|
|
required:
|
|
- id
|
|
- name
|
|
- group
|
|
- env
|
|
- is_add_on
|
|
- is_default
|
|
- archived
|
|
- version
|
|
- created_at
|
|
- items
|
|
- free_trial
|
|
- base_variant_id
|
|
description: Products that would grant access to this feature. Use to display
|
|
upgrade options.
|
|
required:
|
|
- scenario
|
|
- title
|
|
- message
|
|
- feature_id
|
|
- feature_name
|
|
- products
|
|
description: Upgrade/upsell information when access is denied. Only present if
|
|
with_preview was true and allowed is false.
|
|
required:
|
|
- allowed
|
|
- customer_id
|
|
- balance
|
|
- flag
|
|
examples:
|
|
- allowed: true
|
|
customer_id: cus_123
|
|
entity_id: null
|
|
required_balance: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
"202":
|
|
description: Accepted. Autumn is experiencing degraded service from a downstream
|
|
provider, so access was allowed fail-open.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
allowed:
|
|
type: boolean
|
|
description: Whether the customer is allowed to use the feature. True if they
|
|
have sufficient balance or the feature is
|
|
unlimited/boolean.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer that was checked.
|
|
entity_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the entity, if an entity-scoped check was performed.
|
|
required_balance:
|
|
type: number
|
|
description: The required balance that was checked against.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The customer's balance for this feature. Null if the customer has
|
|
no balance for this feature.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: "Map of feature_id to balance for the checked feature and any
|
|
related features (e.g. linked credit systems). "
|
|
flag:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- expires_at
|
|
- feature_id
|
|
examples:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
expires_at: null
|
|
feature_id: dashboard
|
|
- type: "null"
|
|
description: The flag associated with this check, if any.
|
|
preview:
|
|
type: object
|
|
properties:
|
|
scenario:
|
|
enum:
|
|
- usage_limit
|
|
- feature_flag
|
|
type: string
|
|
description: The reason access was denied. 'usage_limit' means the customer
|
|
exceeded their balance, 'feature_flag' means the
|
|
feature is not included in their plan.
|
|
title:
|
|
type: string
|
|
description: A title suitable for displaying in a paywall or upgrade modal.
|
|
message:
|
|
type: string
|
|
description: A message explaining why access was denied.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature that was checked.
|
|
feature_name:
|
|
type: string
|
|
description: The display name of the feature.
|
|
products:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the product you set when creating the product
|
|
name:
|
|
type: string
|
|
description: The name of the product
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Product group which this product belongs to
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment of the product
|
|
is_add_on:
|
|
type: boolean
|
|
description: Whether the product is an add-on and can be purchased alongside
|
|
other products
|
|
is_default:
|
|
type: boolean
|
|
description: Whether the product is the default product
|
|
archived:
|
|
type: boolean
|
|
description: Whether this product has been archived and is no longer available
|
|
version:
|
|
type: number
|
|
description: The current version of the product
|
|
created_at:
|
|
type: number
|
|
description: The timestamp of when the product was created in milliseconds since
|
|
epoch
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
type:
|
|
anyOf:
|
|
- enum:
|
|
- feature
|
|
- priced_feature
|
|
- price
|
|
type: string
|
|
- type: "null"
|
|
description: The type of the product item
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID of the product item. If the item is a fixed price,
|
|
should be `null`
|
|
feature_type:
|
|
anyOf:
|
|
- enum:
|
|
- single_use
|
|
- continuous_use
|
|
- boolean
|
|
- static
|
|
type: string
|
|
- type: "null"
|
|
description: Single use features are used once and then depleted, like API calls
|
|
or credits. Continuous use features are
|
|
those being used on an ongoing-basis, like
|
|
storage or seats.
|
|
included_usage:
|
|
anyOf:
|
|
- anyOf:
|
|
- type: number
|
|
- const: inf
|
|
- type: "null"
|
|
description: The amount of usage included for this feature.
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- type: "null"
|
|
description: The reset or billing interval of the product item. If null, feature
|
|
will have no reset date, and if there's a
|
|
price, it will be billed one-off.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The interval count of the product item.
|
|
price:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The price of the product item. Should be `null` if tiered pricing
|
|
is set.
|
|
tiers:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
- type: "null"
|
|
description: Tiered pricing for the product item. Not applicable for fixed price
|
|
items.
|
|
tier_behavior:
|
|
anyOf:
|
|
- enum:
|
|
- graduated
|
|
- volume
|
|
type: string
|
|
- type: "null"
|
|
description: "How tiers are applied: graduated (split across bands) or volume
|
|
(flat rate for the matched tier). Defaults
|
|
to graduated."
|
|
usage_model:
|
|
anyOf:
|
|
- enum:
|
|
- prepaid
|
|
- pay_per_use
|
|
type: string
|
|
- type: "null"
|
|
description: Whether the feature should be prepaid upfront or billed for how
|
|
much they use end of billing period.
|
|
billing_units:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The amount per billing unit (eg. $9 / 250 units)
|
|
reset_usage_when_enabled:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether the usage should be reset when the product is enabled.
|
|
entity_feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The entity feature ID of the product item if applicable.
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
secondary_text:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- primary_text
|
|
- type: "null"
|
|
description: The display of the product item.
|
|
quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer has
|
|
prepaid for.
|
|
next_cycle_quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer will
|
|
prepay for in the next cycle.
|
|
config:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
rollover:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
max_percentage:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
duration:
|
|
enum:
|
|
- month
|
|
- forever
|
|
type: string
|
|
default: month
|
|
length:
|
|
type: number
|
|
required:
|
|
- length
|
|
- type: "null"
|
|
on_increase:
|
|
anyOf:
|
|
- enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
type: string
|
|
- type: "null"
|
|
on_decrease:
|
|
anyOf:
|
|
- enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
type: string
|
|
- type: "null"
|
|
- type: "null"
|
|
description: Configuration for rollover and proration behavior of the feature.
|
|
description: Product item defining features and pricing within a product
|
|
description: Array of product items that define the product's features and
|
|
pricing
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
type: string
|
|
description: The duration type of the free trial
|
|
length:
|
|
type: number
|
|
description: The length of the duration type specified
|
|
unique_fingerprint:
|
|
type: boolean
|
|
description: Whether the free trial is limited to one per customer fingerprint
|
|
card_required:
|
|
type: boolean
|
|
description: Whether the free trial requires a card. If false, the customer can
|
|
attach the product without going through
|
|
a checkout flow or having a card on
|
|
file.
|
|
on_end:
|
|
anyOf:
|
|
- enum:
|
|
- bill
|
|
- revert
|
|
type: string
|
|
- type: "null"
|
|
description: Behavior when the trial ends. 'bill' charges the customer
|
|
(default). 'revert' expires the trial
|
|
and restores the customer's previous
|
|
plan.
|
|
trial_available:
|
|
anyOf:
|
|
- type: boolean
|
|
default: true
|
|
- type: "null"
|
|
description: Used in customer context. Whether the free trial is available for
|
|
the customer if they were to attach the
|
|
product.
|
|
required:
|
|
- duration
|
|
- length
|
|
- unique_fingerprint
|
|
- card_required
|
|
- type: "null"
|
|
description: Free trial configuration for this product, if available
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the base variant this product is derived from
|
|
scenario:
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- new
|
|
- renew
|
|
- upgrade
|
|
- update_prepaid_quantity
|
|
- downgrade
|
|
- cancel
|
|
- expired
|
|
- past_due
|
|
type: string
|
|
description: Scenario for when this product is used in attach flows
|
|
properties:
|
|
type: object
|
|
properties:
|
|
is_free:
|
|
type: boolean
|
|
description: True if the product has no base price or usage prices
|
|
is_one_off:
|
|
type: boolean
|
|
description: True if the product only contains a one-time price
|
|
interval_group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The billing interval group for recurring products (e.g., 'monthly',
|
|
'yearly')
|
|
has_trial:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product includes a free trial
|
|
updateable:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product can be updated after creation (only applicable
|
|
if there are prepaid recurring prices)
|
|
required:
|
|
- is_free
|
|
- is_one_off
|
|
required:
|
|
- id
|
|
- name
|
|
- group
|
|
- env
|
|
- is_add_on
|
|
- is_default
|
|
- archived
|
|
- version
|
|
- created_at
|
|
- items
|
|
- free_trial
|
|
- base_variant_id
|
|
description: Products that would grant access to this feature. Use to display
|
|
upgrade options.
|
|
required:
|
|
- scenario
|
|
- title
|
|
- message
|
|
- feature_id
|
|
- feature_name
|
|
- products
|
|
description: Upgrade/upsell information when access is denied. Only present if
|
|
with_preview was true and allowed is false.
|
|
required:
|
|
- allowed
|
|
- customer_id
|
|
- balance
|
|
- flag
|
|
examples:
|
|
- allowed: true
|
|
customer_id: cus_123
|
|
entity_id: null
|
|
required_balance: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
x-speakeasy-name-override: check
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.track:
|
|
post:
|
|
operationId: track
|
|
description: >-
|
|
Records usage for a customer feature and returns updated balances.
|
|
|
|
|
|
Use this after an action happens to decrement usage, or send a negative
|
|
value to credit balance back.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Track one message event
|
|
|
|
const response = await client.track({ customerId: "cus_123", featureId:
|
|
"messages", value: 1 });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Track an event mapped to multiple features
|
|
|
|
const response = await client.track({ customerId: "cus_123", eventName:
|
|
"ai_chat_request", value: 1 });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer.
|
|
|
|
@param featureId - The ID of the feature to track usage for. Required if
|
|
event_name is not provided. (optional)
|
|
|
|
@param entityId - The ID of the entity for entity-scoped balances (e.g.,
|
|
per-seat limits). (optional)
|
|
|
|
@param eventName - Event name to track usage for. Use instead of
|
|
feature_id when multiple features should be tracked from a single event.
|
|
(optional)
|
|
|
|
@param value - The amount of usage to record. Defaults to 1. Use
|
|
negative values to credit balance (e.g., when removing a seat).
|
|
(optional)
|
|
|
|
@param properties - Additional properties to attach to this usage event.
|
|
(optional)
|
|
|
|
@param async - If true, enqueue the event for asynchronous processing
|
|
and return 202 immediately. The response will not include balance
|
|
information. (optional)
|
|
|
|
|
|
@returns The usage value recorded, with either a single updated balance
|
|
or a map of updated balances. If Autumn is experiencing degraded service
|
|
from a downstream provider, the API may return 202 after accepting the
|
|
event for replay so it can be tracked as soon as the service is
|
|
restored.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to track usage for. Required if event_name is
|
|
not provided.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
event_name:
|
|
type: string
|
|
minLength: 1
|
|
description: Event name to track usage for. Use instead of feature_id when
|
|
multiple features should be tracked from a single event.
|
|
value:
|
|
type: number
|
|
description: The amount of usage to record. Defaults to 1. Use negative values
|
|
to credit balance (e.g., when removing a seat).
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this usage event.
|
|
async:
|
|
type: boolean
|
|
description: If true, enqueue the event for asynchronous processing and return
|
|
202 immediately. The response will not include balance
|
|
information.
|
|
lock:
|
|
type: object
|
|
properties:
|
|
lock_id:
|
|
type: string
|
|
maxLength: 256
|
|
description: A unique identifier for this lock. Used to finalize the lock later
|
|
via balances.finalize.
|
|
enabled:
|
|
const: true
|
|
description: Must be true to enable locking.
|
|
expires_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the lock automatically expires and
|
|
releases the held balance.
|
|
required:
|
|
- lock_id
|
|
- enabled
|
|
required:
|
|
- customer_id
|
|
title: TrackParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
value: 1
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer whose usage was tracked.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if entity-scoped tracking was performed.
|
|
event_name:
|
|
type: string
|
|
description: The event name that was tracked, if event_name was used instead of
|
|
feature_id.
|
|
value:
|
|
type: number
|
|
description: The amount of usage that was recorded.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The updated balance for the tracked feature. Null if tracking by
|
|
event_name that affects multiple features.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: Map of feature_id to updated balance for the tracked feature and
|
|
any related features (e.g. linked credit systems). Value
|
|
is null when the customer has no balance for that feature.
|
|
deductions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance_id:
|
|
type: string
|
|
description: ID of the underlying balance row that was deducted from
|
|
(customer_entitlement or rollover).
|
|
feature_id:
|
|
type: string
|
|
description: The feature this balance belongs to.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the plan/product this balance belongs to. Null when the
|
|
balance can't be attributed to a single plan (e.g.
|
|
it spans multiple).
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for the balance this deduction came from, or
|
|
null if the balance doesn't reset.
|
|
value:
|
|
type: number
|
|
description: Amount deducted from this balance. Positive when usage was
|
|
consumed, negative when credit was restored (e.g. a
|
|
refund via negative track value).
|
|
required:
|
|
- balance_id
|
|
- feature_id
|
|
- plan_id
|
|
- reset
|
|
- value
|
|
description: Per-balance breakdown of what this event deducted. A single event
|
|
can consume from multiple balance rows when credit systems
|
|
or rollovers are involved; this surfaces each one so
|
|
callers can build per-feature usage views without polling.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- customer_id: cus_123
|
|
value: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
deductions:
|
|
- balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2
|
|
feature_id: messages
|
|
plan_id: pro
|
|
reset:
|
|
interval: month
|
|
resets_at: 1781288736881
|
|
value: 1
|
|
"202":
|
|
description: Accepted. Autumn is experiencing degraded service from a downstream
|
|
provider, so the event was accepted for replay and will be tracked
|
|
as soon as the service is restored.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer whose usage was tracked.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if entity-scoped tracking was performed.
|
|
event_name:
|
|
type: string
|
|
description: The event name that was tracked, if event_name was used instead of
|
|
feature_id.
|
|
value:
|
|
type: number
|
|
description: The amount of usage that was recorded.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The updated balance for the tracked feature. Null if tracking by
|
|
event_name that affects multiple features.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: Map of feature_id to updated balance for the tracked feature and
|
|
any related features (e.g. linked credit systems). Value
|
|
is null when the customer has no balance for that feature.
|
|
deductions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance_id:
|
|
type: string
|
|
description: ID of the underlying balance row that was deducted from
|
|
(customer_entitlement or rollover).
|
|
feature_id:
|
|
type: string
|
|
description: The feature this balance belongs to.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the plan/product this balance belongs to. Null when the
|
|
balance can't be attributed to a single plan (e.g.
|
|
it spans multiple).
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for the balance this deduction came from, or
|
|
null if the balance doesn't reset.
|
|
value:
|
|
type: number
|
|
description: Amount deducted from this balance. Positive when usage was
|
|
consumed, negative when credit was restored (e.g. a
|
|
refund via negative track value).
|
|
required:
|
|
- balance_id
|
|
- feature_id
|
|
- plan_id
|
|
- reset
|
|
- value
|
|
description: Per-balance breakdown of what this event deducted. A single event
|
|
can consume from multiple balance rows when credit systems
|
|
or rollovers are involved; this surfaces each one so
|
|
callers can build per-feature usage views without polling.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- customer_id: cus_123
|
|
value: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
deductions:
|
|
- balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2
|
|
feature_id: messages
|
|
plan_id: pro
|
|
reset:
|
|
interval: month
|
|
resets_at: 1781288736881
|
|
value: 1
|
|
x-speakeasy-name-override: track
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.track_tokens:
|
|
post:
|
|
operationId: trackTokens
|
|
description: >-
|
|
Records AI token usage for a customer and returns the updated AI credit
|
|
balance.
|
|
|
|
|
|
Use this after an LLM request when you have input and output token
|
|
counts. Autumn converts token usage to a dollar amount using the
|
|
configured model pricing and markup, then tracks that value against the
|
|
customer's AI credit system.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Track one LLM response
|
|
|
|
const response = await client.trackTokens({
|
|
customerId: "cus_123",
|
|
featureId: "ai_credits",
|
|
modelId: "anthropic/claude-sonnet-4-20250514",
|
|
inputTokens: 1000,
|
|
outputTokens: 500,
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer.
|
|
|
|
@param entityId - The ID of the entity for entity-scoped balances.
|
|
(optional)
|
|
|
|
@param featureId - The ID of the AI credit system feature. Auto-detected
|
|
from the customer's entitlements if omitted — only required when a
|
|
customer has multiple AI credit systems. (optional)
|
|
|
|
@param modelId - The AI model as '<provider>/<model>' (e.g.
|
|
'anthropic/claude-opus-4-8', 'openrouter/openai/gpt-4o'). The provider
|
|
is the first path segment and must match a provider + model key in
|
|
models.dev.
|
|
|
|
@param inputTokens - Number of non-cached text input tokens consumed.
|
|
Exclusive of cache and audio token pools.
|
|
|
|
@param outputTokens - Number of text output tokens consumed. Exclusive
|
|
of the reasoning and audio output pools.
|
|
|
|
@param cacheReadTokens - Number of cached input tokens read. (optional)
|
|
|
|
@param cacheWriteTokens - Number of input tokens written to the cache.
|
|
(optional)
|
|
|
|
@param audioInputTokens - Number of audio input tokens consumed.
|
|
(optional)
|
|
|
|
@param audioOutputTokens - Number of audio output tokens generated.
|
|
(optional)
|
|
|
|
@param reasoningTokens - Number of reasoning tokens generated.
|
|
(optional)
|
|
|
|
@param properties - Additional properties to attach to this usage event.
|
|
(optional)
|
|
|
|
|
|
@returns The dollar value recorded and the updated AI credit system
|
|
balance. If Autumn is experiencing degraded service from a downstream
|
|
provider, the API may return 202 after accepting the token usage event
|
|
for replay so it can be tracked as soon as the service is restored.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the AI credit system feature. Auto-detected from the
|
|
customer's entitlements if omitted — only required when a
|
|
customer has multiple AI credit systems.
|
|
model_id:
|
|
type: string
|
|
description: The AI model as '<provider>/<model>' (e.g.
|
|
'anthropic/claude-opus-4-8', 'openrouter/openai/gpt-4o').
|
|
The provider is the first path segment and must match a
|
|
provider + model key in models.dev.
|
|
input_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of non-cached text input tokens consumed. Exclusive of cache
|
|
and audio token pools.
|
|
output_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of text output tokens consumed. Exclusive of the reasoning
|
|
and audio output pools.
|
|
cache_read_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of cached input tokens read.
|
|
cache_write_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of input tokens written to the cache.
|
|
audio_input_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of audio input tokens consumed.
|
|
audio_output_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of audio output tokens generated.
|
|
reasoning_tokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
description: Number of reasoning tokens generated.
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this usage event.
|
|
required:
|
|
- customer_id
|
|
- model_id
|
|
- input_tokens
|
|
- output_tokens
|
|
title: TrackTokensParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: ai_credits
|
|
model_id: anthropic/claude-sonnet-4-20250514
|
|
input_tokens: 1000
|
|
output_tokens: 500
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer whose usage was tracked.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if entity-scoped tracking was performed.
|
|
event_name:
|
|
type: string
|
|
description: The event name that was tracked, if event_name was used instead of
|
|
feature_id.
|
|
value:
|
|
type: number
|
|
description: The amount of usage that was recorded.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The updated balance for the tracked feature. Null if tracking by
|
|
event_name that affects multiple features.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: Map of feature_id to updated balance for the tracked feature and
|
|
any related features (e.g. linked credit systems). Value
|
|
is null when the customer has no balance for that feature.
|
|
deductions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance_id:
|
|
type: string
|
|
description: ID of the underlying balance row that was deducted from
|
|
(customer_entitlement or rollover).
|
|
feature_id:
|
|
type: string
|
|
description: The feature this balance belongs to.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the plan/product this balance belongs to. Null when the
|
|
balance can't be attributed to a single plan (e.g.
|
|
it spans multiple).
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for the balance this deduction came from, or
|
|
null if the balance doesn't reset.
|
|
value:
|
|
type: number
|
|
description: Amount deducted from this balance. Positive when usage was
|
|
consumed, negative when credit was restored (e.g. a
|
|
refund via negative track value).
|
|
required:
|
|
- balance_id
|
|
- feature_id
|
|
- plan_id
|
|
- reset
|
|
- value
|
|
description: Per-balance breakdown of what this event deducted. A single event
|
|
can consume from multiple balance rows when credit systems
|
|
or rollovers are involved; this surfaces each one so
|
|
callers can build per-feature usage views without polling.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- customer_id: cus_123
|
|
value: 0.006
|
|
balance:
|
|
feature_id: ai_credits
|
|
granted: 10
|
|
remaining: 9.994
|
|
usage: 0.006
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
deductions:
|
|
- balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2
|
|
feature_id: ai_credits
|
|
plan_id: pro
|
|
reset:
|
|
interval: month
|
|
resets_at: 1781288736881
|
|
value: 0.006
|
|
"202":
|
|
description: Accepted. Autumn is experiencing degraded service from a downstream
|
|
provider, so the token usage event was accepted for replay and will
|
|
be tracked as soon as the service is restored.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer whose usage was tracked.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if entity-scoped tracking was performed.
|
|
event_name:
|
|
type: string
|
|
description: The event name that was tracked, if event_name was used instead of
|
|
feature_id.
|
|
value:
|
|
type: number
|
|
description: The amount of usage that was recorded.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The updated balance for the tracked feature. Null if tracking by
|
|
event_name that affects multiple features.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: Map of feature_id to updated balance for the tracked feature and
|
|
any related features (e.g. linked credit systems). Value
|
|
is null when the customer has no balance for that feature.
|
|
deductions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance_id:
|
|
type: string
|
|
description: ID of the underlying balance row that was deducted from
|
|
(customer_entitlement or rollover).
|
|
feature_id:
|
|
type: string
|
|
description: The feature this balance belongs to.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the plan/product this balance belongs to. Null when the
|
|
balance can't be attributed to a single plan (e.g.
|
|
it spans multiple).
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for the balance this deduction came from, or
|
|
null if the balance doesn't reset.
|
|
value:
|
|
type: number
|
|
description: Amount deducted from this balance. Positive when usage was
|
|
consumed, negative when credit was restored (e.g. a
|
|
refund via negative track value).
|
|
required:
|
|
- balance_id
|
|
- feature_id
|
|
- plan_id
|
|
- reset
|
|
- value
|
|
description: Per-balance breakdown of what this event deducted. A single event
|
|
can consume from multiple balance rows when credit systems
|
|
or rollovers are involved; this surfaces each one so
|
|
callers can build per-feature usage views without polling.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- customer_id: cus_123
|
|
value: 0.006
|
|
balance:
|
|
feature_id: ai_credits
|
|
granted: 10
|
|
remaining: 9.994
|
|
usage: 0.006
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
deductions:
|
|
- balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2
|
|
feature_id: ai_credits
|
|
plan_id: pro
|
|
reset:
|
|
interval: month
|
|
resets_at: 1781288736881
|
|
value: 0.006
|
|
x-speakeasy-name-override: trackTokens
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.batch_track:
|
|
post:
|
|
operationId: batchTrack
|
|
description: Enqueue up to 1000 usage events for asynchronous processing. Items
|
|
are validated synchronously up front; validated items are then enqueued
|
|
via SQS for background deduction by workers. The response returns 202
|
|
immediately and does not include balance information. On partial enqueue
|
|
failure (some items fail to enqueue, others succeed), the endpoint still
|
|
returns 202 and logs the failures server-side; clients should NOT retry,
|
|
because retrying re-enqueues the already-succeeded items. A 503 is
|
|
returned only when zero items were successfully enqueued (queue entirely
|
|
unavailable) — that case is safe to retry.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 1000
|
|
items:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to track usage for. Required if event_name is
|
|
not provided.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
event_name:
|
|
type: string
|
|
minLength: 1
|
|
description: Event name to track usage for. Use instead of feature_id when
|
|
multiple features should be tracked from a single event.
|
|
value:
|
|
type: number
|
|
description: The amount of usage to record. Defaults to 1. Use negative values
|
|
to credit balance (e.g., when removing a seat).
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this usage event.
|
|
async:
|
|
type: boolean
|
|
description: If true, enqueue the event for asynchronous processing and return
|
|
202 immediately. The response will not include balance
|
|
information.
|
|
lock:
|
|
type: object
|
|
properties:
|
|
lock_id:
|
|
type: string
|
|
maxLength: 256
|
|
description: A unique identifier for this lock. Used to finalize the lock later
|
|
via balances.finalize.
|
|
enabled:
|
|
const: true
|
|
description: Must be true to enable locking.
|
|
expires_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the lock automatically expires and
|
|
releases the held balance.
|
|
required:
|
|
- lock_id
|
|
- enabled
|
|
required:
|
|
- customer_id
|
|
title: BatchTrackParams
|
|
examples:
|
|
- - customer_id: cus_123
|
|
feature_id: messages
|
|
value: 1
|
|
- customer_id: cus_123
|
|
event_name: message.sent
|
|
value: 1
|
|
responses:
|
|
"202":
|
|
description: "Batch accepted. All items passed synchronous validation. Enqueue
|
|
is best-effort: partial failures (some items enqueued, some not) are
|
|
logged server-side and are NOT surfaced in the response body;
|
|
clients must not retry on 202. See the endpoint description for full
|
|
partial-failure semantics."
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
const: true
|
|
required:
|
|
- success
|
|
examples:
|
|
- success: true
|
|
x-speakeasy-name-override: batchTrack
|
|
parameters:
|
|
- *a1
|
|
/v1/events.list:
|
|
post:
|
|
operationId: listEvents
|
|
description: List usage events for your organization. Filter by customer,
|
|
feature, or time range.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
start_cursor:
|
|
type: string
|
|
default: ""
|
|
description: Opaque pagination cursor. Empty string (default) requests the first
|
|
page; use next_cursor from a prior response for subsequent
|
|
pages.
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 5000
|
|
default: 50
|
|
description: Number of items to return. Default 50, hard ceiling 5000.
|
|
customer_id:
|
|
type: string
|
|
description: Filter events by customer ID
|
|
entity_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Filter events by entity ID (e.g., per-seat or per-resource)
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Filter by specific feature ID(s)
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: Filter events after this timestamp (epoch milliseconds)
|
|
end:
|
|
type: number
|
|
description: Filter events before this timestamp (epoch milliseconds)
|
|
description: Filter events by time range
|
|
title: EventsListParams
|
|
examples:
|
|
- start_cursor: ""
|
|
customer_id: cus_123
|
|
limit: 50
|
|
- start_cursor: ""
|
|
feature_id: api_calls
|
|
custom_range:
|
|
start: 1704067200000
|
|
end: 1706745600000
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Event ID (KSUID)
|
|
timestamp:
|
|
type: number
|
|
description: Event timestamp (epoch milliseconds)
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature that the event belongs to
|
|
customer_id:
|
|
type: string
|
|
description: Customer identifier
|
|
value:
|
|
type: number
|
|
description: Event value/count
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Event properties (JSON)
|
|
deductions:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance_id:
|
|
type: string
|
|
description: ID of the underlying balance row that was deducted from
|
|
(customer_entitlement or rollover).
|
|
feature_id:
|
|
type: string
|
|
description: The feature this balance belongs to.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the plan/product this balance belongs to. Null when the
|
|
balance can't be attributed to a single
|
|
plan (e.g. it spans multiple).
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
type: string
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for the balance this deduction came from, or
|
|
null if the balance doesn't reset.
|
|
value:
|
|
type: number
|
|
description: Amount deducted from this balance. Positive when usage was
|
|
consumed, negative when credit was
|
|
restored (e.g. a refund via negative track
|
|
value).
|
|
required:
|
|
- balance_id
|
|
- feature_id
|
|
- plan_id
|
|
- reset
|
|
- value
|
|
- type: "null"
|
|
description: Per-balance breakdown of what this event deducted. Null for events
|
|
ingested before deductions were tracked; an empty
|
|
array means the event was accepted but no balance
|
|
moved.
|
|
required:
|
|
- id
|
|
- timestamp
|
|
- feature_id
|
|
- customer_id
|
|
- value
|
|
- properties
|
|
- deductions
|
|
description: Items for current page.
|
|
next_cursor:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Opaque cursor for the next page. Null when there are no more
|
|
results.
|
|
required:
|
|
- list
|
|
- next_cursor
|
|
examples:
|
|
- list:
|
|
- id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg
|
|
timestamp: 1765958215459
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 30
|
|
properties: {}
|
|
deductions:
|
|
- balance_id: cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12
|
|
feature_id: credits
|
|
plan_id: pro
|
|
reset:
|
|
interval: month
|
|
resets_at: 1765958215459
|
|
value: 30
|
|
- id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM
|
|
timestamp: 1765956512057
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 49
|
|
properties: {}
|
|
deductions: null
|
|
next_cursor: eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/events.aggregate:
|
|
post:
|
|
operationId: aggregateEvents
|
|
description: Aggregate usage events by time period. Returns usage totals grouped
|
|
by feature and optionally by a custom property.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Customer ID to aggregate events for
|
|
entity_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Entity ID to filter aggregated events for (e.g., per-seat or
|
|
per-resource limits)
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Feature ID(s) to aggregate events for
|
|
group_by:
|
|
type: string
|
|
description: Property to group events by (e.g. "properties.region"), or
|
|
"$customer_id" / "$entity_id" / "$plan_id" to group by those
|
|
columns
|
|
range:
|
|
enum:
|
|
- 24h
|
|
- 7d
|
|
- 30d
|
|
- 90d
|
|
- last_cycle
|
|
- 1bc
|
|
- 3bc
|
|
type: string
|
|
description: Time range to aggregate events for. Either range or custom_range
|
|
must be provided
|
|
bin_size:
|
|
enum:
|
|
- day
|
|
- hour
|
|
- month
|
|
type: string
|
|
default: day
|
|
description: Size of the time bins to aggregate events for. Defaults to hour if
|
|
range is 24h, otherwise day
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
end:
|
|
type: number
|
|
required:
|
|
- start
|
|
- end
|
|
description: Custom time range to aggregate events for. If provided, range must
|
|
not be provided
|
|
filter_by:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: string
|
|
description: 'Filter events by property values, e.g. {"model": "gpt-4",
|
|
"region": "us"}. Maximum 5 filters.'
|
|
max_groups:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 250
|
|
description: Maximum number of distinct group values to return per time bin when
|
|
using group_by. Remaining values are bundled into an 'Other'
|
|
bucket. Defaults to 9
|
|
required:
|
|
- feature_id
|
|
title: EventsAggregateParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
range: 30d
|
|
bin_size: day
|
|
- customer_id: cus_123
|
|
feature_id:
|
|
- api_calls
|
|
- messages
|
|
range: 7d
|
|
group_by: properties.model
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: number
|
|
description: Unix timestamp (epoch ms) for this time period
|
|
values:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: number
|
|
description: "Aggregated values per feature: { [featureId]: number }"
|
|
grouped_values:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: number
|
|
description: "Values broken down by group (only present when group_by is used):
|
|
{ [featureId]: { [groupValue]: number } }"
|
|
required:
|
|
- period
|
|
- values
|
|
description: Array of time periods with aggregated values
|
|
total:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
count:
|
|
type: number
|
|
description: Number of events for this feature
|
|
sum:
|
|
type: number
|
|
description: Sum of event values for this feature
|
|
required:
|
|
- count
|
|
- sum
|
|
description: Total aggregations per feature. Keys are feature IDs, values
|
|
contain count and sum.
|
|
required:
|
|
- list
|
|
- total
|
|
examples:
|
|
- list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
- list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
grouped_values:
|
|
messages:
|
|
api: 5
|
|
web: 5
|
|
sessions:
|
|
api: 2
|
|
web: 1
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
grouped_values:
|
|
messages:
|
|
api: 1
|
|
web: 2
|
|
sessions:
|
|
api: 10
|
|
web: 2
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
x-speakeasy-name-override: aggregate
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.create:
|
|
post:
|
|
operationId: createEntity
|
|
description: >-
|
|
Creates an entity for a customer and feature, then returns the entity
|
|
with balances and subscriptions.
|
|
|
|
|
|
Use entities when usage and access must be scoped to sub-resources (for
|
|
example seats, projects, or workspaces) instead of only the customer.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a seat entity
|
|
|
|
const response = await client.entities.create({
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
featureId: "seats",
|
|
name: "Seat 42",
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the entity (optional)
|
|
|
|
@param featureId - The ID of the feature this entity is associated with
|
|
|
|
@param billingControls - Billing controls for the entity. (optional)
|
|
|
|
@param customerData - Customer attributes used to resolve the customer
|
|
when customer_id is not provided. (optional)
|
|
|
|
@param customerId - The ID of the customer to create the entity for.
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns The created entity object including its current subscriptions,
|
|
purchases, and balances.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this entity is associated with
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage (usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this is
|
|
a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
description: Customer attributes used to resolve the customer when customer_id
|
|
is not provided.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- feature_id
|
|
- customer_id
|
|
- entity_id
|
|
title: CreateEntityParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
feature_id: seats
|
|
name: Seat 42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise,
|
|
falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
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 the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.get:
|
|
post:
|
|
operationId: getEntity
|
|
description: >-
|
|
Fetches an entity by its ID.
|
|
|
|
|
|
Use this to read one entity's current state. Pass customerId when you
|
|
want to scope the lookup to a specific customer.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a seat entity
|
|
|
|
const response = await client.entities.get({ entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a seat entity for a specific customer
|
|
|
|
const response = await client.entities.get({ customerId: "cus_123",
|
|
entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to create the entity for.
|
|
(optional)
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns The entity object including its current subscriptions,
|
|
purchases, and balances.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: GetEntityParams
|
|
examples:
|
|
- entity_id: seat_42
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise,
|
|
falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
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 the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.list:
|
|
post:
|
|
operationId: listEntities
|
|
description: >-
|
|
Lists entities across the organization with pagination and optional
|
|
filters.
|
|
|
|
|
|
Use this to page through entities globally, including filtering by plans
|
|
inherited from parent customers or attached directly to entities.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// List entities on a plan
|
|
|
|
const response = await client.entities.list({ plans:
|
|
[{"id":"pro_plan"}], limit: 10, offset: 0 });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Search entities by ID or name
|
|
|
|
const response = await client.entities.list({ search: "workspace" });
|
|
|
|
```
|
|
|
|
|
|
@param offset - Number of items to skip (optional)
|
|
|
|
@param limit - Number of items to return. Default 10, max 1000.
|
|
(optional)
|
|
|
|
@param plans - Filter by plan ID and version. Returns entities with
|
|
active subscriptions to this plan, including plans inherited from the
|
|
parent customer. (optional)
|
|
|
|
@param subscriptionStatus - Filter customer products used for entity
|
|
hydration and plan matching. Defaults to active and scheduled.
|
|
(optional)
|
|
|
|
@param search - Search entities by id or name. (optional)
|
|
|
|
@param processors - Filter by parent customer processor type (stripe,
|
|
revenuecat, vercel). (optional)
|
|
|
|
@param customerId - Restrict the response to entities owned by this
|
|
customer id. Use to bulk-fetch all entities for one customer in a single
|
|
paginated call instead of iterating entities.get. (optional)
|
|
|
|
|
|
@returns A paginated list of entity objects including their current
|
|
subscriptions, purchases, balances, and flags.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
start_cursor:
|
|
type: string
|
|
default: ""
|
|
description: Opaque pagination cursor. Empty string (default) requests the first
|
|
page; use next_cursor from a prior response for subsequent
|
|
pages.
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 5000
|
|
default: 50
|
|
description: Number of items to return. Default 50, hard ceiling 5000.
|
|
plans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
versions:
|
|
type: array
|
|
items:
|
|
type: number
|
|
required:
|
|
- id
|
|
description: Filter by plan ID and version. Returns entities with active
|
|
subscriptions to this plan, including plans inherited from
|
|
the parent customer.
|
|
subscription_status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Filter customer products used for entity hydration and plan
|
|
matching. Defaults to active and scheduled.
|
|
search:
|
|
type: string
|
|
description: Search entities by id or name.
|
|
processors:
|
|
type: array
|
|
items:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
- vercel
|
|
type: string
|
|
description: Filter by parent customer processor type (stripe, revenuecat,
|
|
vercel).
|
|
customer_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Restrict the response to entities owned by this customer id. Use to
|
|
bulk-fetch all entities for one customer in a single
|
|
paginated call instead of iterating entities.get.
|
|
title: ListEntitiesParams
|
|
examples:
|
|
- start_cursor: ""
|
|
limit: 10
|
|
- plans:
|
|
- id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used;
|
|
otherwise, falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system'
|
|
for unified credit pools,
|
|
'ai_credit_system' for model-based token
|
|
pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
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 the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing
|
|
controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage,
|
|
this is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
description: Items for current page.
|
|
next_cursor:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Opaque cursor for the next page. Null when there are no more
|
|
results.
|
|
required:
|
|
- list
|
|
- next_cursor
|
|
examples:
|
|
- list:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
next_cursor: null
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.update:
|
|
post:
|
|
operationId: updateEntity
|
|
description: |-
|
|
Updates an existing entity and returns the refreshed entity object.
|
|
|
|
Use this to change entity billing controls or other mutable entity fields after the entity has already been created.
|
|
|
|
@example
|
|
```typescript
|
|
// Update a seat entity's billing controls
|
|
const response = await client.entities.update({ customerId: "cus_123", entityId: "seat_42", billingControls: {"spendLimits":[{"featureId":"messages","enabled":true,"overageLimit":25}]} });
|
|
```
|
|
|
|
@param customerId - The ID of the customer that owns the entity. (optional)
|
|
@param entityId - The ID of the entity.
|
|
@param billingControls - Billing controls to replace on the entity. (optional)
|
|
|
|
@returns The updated entity object including its current subscriptions, purchases, and balances.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer that owns the entity.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
billing_controls:
|
|
type: object
|
|
properties:
|
|
spend_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: Optional feature ID this spend limit applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage (usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this is
|
|
a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls to replace on the entity.
|
|
required:
|
|
- entity_id
|
|
title: UpdateEntityParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
billing_controls:
|
|
spend_limits:
|
|
- feature_id: messages
|
|
enabled: true
|
|
overage_limit: 25
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier of this subscription. If a subscription_id
|
|
was provided at attach time, it is used; otherwise,
|
|
falls back to the internal ID.
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
type: string
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this subscription is attached at the customer level or
|
|
entity level.
|
|
required:
|
|
- id
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
scope:
|
|
enum:
|
|
- customer
|
|
- entity
|
|
type: string
|
|
description: Whether this purchase is attached at the customer level or entity
|
|
level.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
flags:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this flag.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this flag originates from, or null for standalone
|
|
flags.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this flag expires, or null for no expiration.
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this flag is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
- ai_credit_system
|
|
type: string
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for
|
|
unified credit pools, 'ai_credit_system' for
|
|
model-based token pricing."
|
|
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."
|
|
model_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
input_cost:
|
|
type: number
|
|
minimum: 0
|
|
output_cost:
|
|
type: number
|
|
minimum: 0
|
|
- type: "null"
|
|
description: Per-model markup overrides for AI credit systems.
|
|
default_markup:
|
|
type: number
|
|
minimum: -100
|
|
description: Default percentage markup for AI credit systems. Use -100 to make
|
|
usage free.
|
|
provider_markups:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
markup:
|
|
type: number
|
|
minimum: -100
|
|
required:
|
|
- markup
|
|
- type: "null"
|
|
description: Per-provider default markup percentages for AI credit systems.
|
|
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 the overage spend limit is enabled.
|
|
overage_limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum allowed overage spend for the target feature.
|
|
description: List of spend limits per feature. Each entry caps overage
|
|
(overage_limit) and/or per-interval usage
|
|
(usage_limit).
|
|
usage_limits:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature this usage limit applies to.
|
|
limit:
|
|
type: number
|
|
minimum: 0
|
|
description: Maximum units allowed per interval.
|
|
interval:
|
|
enum:
|
|
- day
|
|
- week
|
|
- month
|
|
- year
|
|
type: string
|
|
description: Interval for the cap, aligned to the customer's billing cycle.
|
|
usage:
|
|
type: number
|
|
minimum: 0
|
|
description: Current usage already consumed in the active interval.
|
|
Response-only; not stored on billing controls.
|
|
required:
|
|
- feature_id
|
|
- limit
|
|
- interval
|
|
description: List of hard usage caps per feature for this entity. An entity
|
|
entry overrides the customer's for that feature.
|
|
usage_alerts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this alert applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
description: Whether this usage alert is enabled.
|
|
threshold:
|
|
type: number
|
|
minimum: 0
|
|
description: The threshold value that triggers the alert. For usage or
|
|
remaining, this is an absolute count. For
|
|
usage_percentage or remaining_percentage, this
|
|
is a percentage (0-100).
|
|
threshold_type:
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
type: string
|
|
description: Whether the threshold is an absolute count or a percentage of the
|
|
usage allowance or remaining balance.
|
|
name:
|
|
type: string
|
|
description: Optional user-defined label to distinguish multiple alerts on the
|
|
same feature.
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
description: List of usage alert configurations per feature.
|
|
overage_allowed:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this overage allowed control applies to.
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether overage is allowed for this feature.
|
|
required:
|
|
- feature_id
|
|
description: List of overage allowed controls per feature. When enabled, usage
|
|
can exceed balance.
|
|
description: Billing controls for the entity.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
processor_type:
|
|
enum:
|
|
- stripe
|
|
- revenuecat
|
|
type: string
|
|
default: stripe
|
|
description: The billing processor that owns this invoice.
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
- flags
|
|
examples:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.delete:
|
|
post:
|
|
operationId: deleteEntity
|
|
description: >-
|
|
Deletes an entity by entity ID.
|
|
|
|
|
|
Use this when the underlying resource is removed and you no longer want
|
|
entity-scoped balances or subscriptions tracked for it.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete a seat entity
|
|
|
|
const response = await client.entities.delete({ entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer. (optional)
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns A success flag indicating the entity was deleted.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: DeleteEntityParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
examples:
|
|
- success: true
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/referrals.create_code:
|
|
post:
|
|
operationId: createReferralCode
|
|
description: Create or fetch a referral code for a customer in a referral program.
|
|
tags:
|
|
- referrals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer
|
|
program_id:
|
|
type: string
|
|
description: ID of your referral program
|
|
required:
|
|
- customer_id
|
|
- program_id
|
|
title: CreateReferralCodeParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
program_id: prog_123
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: The referral code that can be shared with customers
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
created_at:
|
|
type: number
|
|
description: The timestamp of when the referral code was created
|
|
required:
|
|
- code
|
|
- customer_id
|
|
- created_at
|
|
examples:
|
|
- code: <string>
|
|
customer_id: <string>
|
|
created_at: 123
|
|
x-speakeasy-name-override: createCode
|
|
parameters:
|
|
- *a1
|
|
/v1/referrals.redeem_code:
|
|
post:
|
|
operationId: redeemReferralCode
|
|
description: Redeem a referral code for a customer.
|
|
tags:
|
|
- referrals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: The referral code to redeem
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer redeeming the code
|
|
required:
|
|
- code
|
|
- customer_id
|
|
title: RedeemReferralCodeParams
|
|
examples:
|
|
- code: REF123
|
|
customer_id: cus_456
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the redemption event
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward that will be granted
|
|
required:
|
|
- id
|
|
- customer_id
|
|
- reward_id
|
|
examples:
|
|
- id: <string>
|
|
customer_id: <string>
|
|
reward_id: <string>
|
|
x-speakeasy-name-override: redeemCode
|
|
parameters:
|
|
- *a1
|
|
/v1/rewards.redeem:
|
|
post:
|
|
operationId: redeemRewardCode
|
|
description: Redeem a reward promo code for a customer.
|
|
tags:
|
|
- rewards
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: The reward promo code to redeem
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer redeeming the code
|
|
required:
|
|
- code
|
|
- customer_id
|
|
title: RedeemRewardCodeParams
|
|
examples:
|
|
- code: REWARD10
|
|
customer_id: cus_456
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the redeemed reward
|
|
entitlements_granted:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature granted by the reward
|
|
balance:
|
|
type: number
|
|
description: The balance granted for the feature
|
|
required:
|
|
- feature_id
|
|
- balance
|
|
description: The feature balances granted to the customer
|
|
required:
|
|
- reward_id
|
|
- entitlements_granted
|
|
examples:
|
|
- reward_id: reward_789
|
|
entitlements_granted:
|
|
- feature_id: messages
|
|
balance: 100
|
|
x-speakeasy-name-override: redeemCode
|
|
parameters:
|
|
- *a1
|
|
/v1/platform.link_revenuecat:
|
|
post:
|
|
operationId: linkRevenueCat
|
|
description: Generate a RevenueCat OAuth URL for linking a project to an organization.
|
|
tags:
|
|
- platform
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
organization_slug:
|
|
type: string
|
|
minLength: 1
|
|
env:
|
|
enum:
|
|
- test
|
|
- live
|
|
type: string
|
|
project_name:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 255
|
|
redirect_url:
|
|
type: string
|
|
format: uri
|
|
required:
|
|
- organization_slug
|
|
- env
|
|
- project_name
|
|
- redirect_url
|
|
title: LinkRevenueCatParams
|
|
examples:
|
|
- organization_slug: acme
|
|
env: test
|
|
project_name: acme-mobile
|
|
redirect_url: https://dashboard.useautumn.com/dev?tab=revenuecat
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
oauth_url:
|
|
type: string
|
|
required:
|
|
- oauth_url
|
|
title: LinkRevenueCatResponse
|
|
examples:
|
|
- oauth_url: https://api.revenuecat.com/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=project.read+project.write
|
|
x-speakeasy-name-override: linkRevenueCat
|
|
parameters:
|
|
- *a1
|
|
/v1/platform.sync_revenuecat:
|
|
post:
|
|
operationId: syncRevenueCat
|
|
description: Push an organization's plans into RevenueCat as products (creating
|
|
or renaming them across the project's apps) and set test-store prices
|
|
from each plan's price. Requires the org to have linked RevenueCat via
|
|
OAuth.
|
|
tags:
|
|
- platform
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
organization_slug:
|
|
type: string
|
|
minLength: 1
|
|
env:
|
|
enum:
|
|
- test
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: '"test" and "sandbox" both target the sandbox environment'
|
|
product_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Plans to push. Omit to sync every plan in the org/env.
|
|
required:
|
|
- organization_slug
|
|
- env
|
|
title: SyncRevenueCatParams
|
|
examples:
|
|
- organization_slug: acme
|
|
env: test
|
|
product_ids:
|
|
- pro
|
|
- premium
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
status:
|
|
enum:
|
|
- synced
|
|
- skipped
|
|
- error
|
|
type: string
|
|
store_identifier:
|
|
type: string
|
|
apps:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
app_id:
|
|
type: string
|
|
app_type:
|
|
type: string
|
|
product:
|
|
enum:
|
|
- created
|
|
- updated
|
|
- exists
|
|
type: string
|
|
store_push:
|
|
enum:
|
|
- pushed
|
|
- failed
|
|
- skipped
|
|
type: string
|
|
price:
|
|
enum:
|
|
- set
|
|
- skipped
|
|
- failed
|
|
type: string
|
|
message:
|
|
type: string
|
|
required:
|
|
- app_id
|
|
- app_type
|
|
- product
|
|
message:
|
|
type: string
|
|
required:
|
|
- plan_id
|
|
- status
|
|
required:
|
|
- results
|
|
title: SyncRevenueCatResponse
|
|
examples:
|
|
- results:
|
|
- plan_id: pro
|
|
status: synced
|
|
store_identifier: autumn.sandbox.org_123.pro
|
|
apps:
|
|
- app_id: app_test
|
|
app_type: test_store
|
|
product: created
|
|
store_push: skipped
|
|
price: set
|
|
x-speakeasy-name-override: syncRevenueCat
|
|
parameters:
|
|
- *a1
|
|
/v1/platform.get_revenuecat_keys:
|
|
post:
|
|
operationId: getRevenueCatKeys
|
|
description: Retrieve a managed organization's RevenueCat public (SDK) API keys,
|
|
grouped by app — for the test store, App Store, and Google Play Store.
|
|
Use these to configure the RevenueCat SDK in the org's mobile app.
|
|
tags:
|
|
- platform
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
organization_slug:
|
|
type: string
|
|
minLength: 1
|
|
env:
|
|
enum:
|
|
- test
|
|
- sandbox
|
|
- live
|
|
type: string
|
|
description: '"test" and "sandbox" both target the sandbox environment'
|
|
required:
|
|
- organization_slug
|
|
- env
|
|
title: GetRevenueCatKeysParams
|
|
examples:
|
|
- organization_slug: acme
|
|
env: test
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
apps:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
app_id:
|
|
type: string
|
|
app_type:
|
|
type: string
|
|
description: RevenueCat store type, e.g. test_store / app_store / play_store
|
|
name:
|
|
type: string
|
|
api_keys:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
key:
|
|
type: string
|
|
description: The public SDK API key value
|
|
environment:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: e.g. "production" / "sandbox"
|
|
app_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
created_at:
|
|
type: number
|
|
required:
|
|
- id
|
|
- key
|
|
additionalProperties: {}
|
|
required:
|
|
- app_id
|
|
- app_type
|
|
- name
|
|
- api_keys
|
|
oauth_access_token:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Freshly-refreshed RevenueCat OAuth access token for the org (null
|
|
for api-key orgs). The refresh token is never exposed —
|
|
call this endpoint again for a new access token.
|
|
required:
|
|
- apps
|
|
- oauth_access_token
|
|
title: GetRevenueCatKeysResponse
|
|
examples:
|
|
- apps:
|
|
- app_id: app1a2b3c4d
|
|
app_type: test_store
|
|
name: Acme (Test Store)
|
|
api_keys:
|
|
- id: apikey12345
|
|
key: test_aBcDeFgHiJkLmNoPqRsTuVwXyZ
|
|
environment: production
|
|
app_id: app1a2b3c4
|
|
oauth_access_token: atk_aBcDeFgHiJkLmNoPqRsTuVwXyZ
|
|
x-speakeasy-name-override: getRevenueCatKeys
|
|
parameters:
|
|
- *a1
|
|
security:
|
|
- secretKey: []
|
|
x-speakeasy-globals:
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: 2.3.0
|
|
x-speakeasy-globals-hidden: true
|
|
- name: fail-open
|
|
in: header
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
x-speakeasy-globals-hidden: true
|
|
webhooks:
|
|
balances.usage_alert_triggered:
|
|
post:
|
|
operationId: balancesUsageAlertTriggered
|
|
summary: Usage Alert Triggered
|
|
description: Fired when a customer crosses a configured usage alert threshold.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: balances.usage_alert_triggered
|
|
description: The webhook event type.
|
|
data:
|
|
examples:
|
|
- customer_id: org_123
|
|
feature_id: api_calls
|
|
entity_id: workspace_abc
|
|
usage_alert:
|
|
name: 80% usage warning
|
|
threshold: 80
|
|
threshold_type: usage_percentage_threshold
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
description: The ID of the customer whose usage alert was triggered.
|
|
type: string
|
|
feature_id:
|
|
description: The feature ID the alert applies to.
|
|
type: string
|
|
entity_id:
|
|
description: The entity ID the alert applies to, if the usage was entity-scoped.
|
|
type: string
|
|
usage_alert:
|
|
description: Details of the usage alert that was triggered.
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: User-defined label for the alert, if provided.
|
|
type: string
|
|
threshold:
|
|
description: The threshold value that was crossed.
|
|
type: number
|
|
threshold_type:
|
|
description: Whether the threshold is an absolute usage count or a percentage.
|
|
type: string
|
|
enum:
|
|
- usage
|
|
- usage_percentage
|
|
- remaining
|
|
- remaining_percentage
|
|
required:
|
|
- threshold
|
|
- threshold_type
|
|
additionalProperties: false
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
- usage_alert
|
|
additionalProperties: false
|
|
example:
|
|
type: balances.usage_alert_triggered
|
|
data:
|
|
customer_id: org_123
|
|
feature_id: api_calls
|
|
entity_id: workspace_abc
|
|
usage_alert:
|
|
name: 80% usage warning
|
|
threshold: 80
|
|
threshold_type: usage_percentage_threshold
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
balances.limit_reached:
|
|
post:
|
|
operationId: balancesLimitReached
|
|
summary: Limit Reached
|
|
description: Fired when a customer reaches the limit for a feature (included
|
|
allowance, max purchase, or spend limit).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: balances.limit_reached
|
|
description: The webhook event type.
|
|
data:
|
|
examples:
|
|
- customer_id: org_123
|
|
entity_id: workspace_abc
|
|
feature_id: api_calls
|
|
limit_type: included
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
description: The ID of the customer who hit the limit.
|
|
type: string
|
|
entity_id:
|
|
description: The entity ID, if the limit was reached on a specific entity.
|
|
type: string
|
|
feature_id:
|
|
description: The feature ID whose limit was reached.
|
|
type: string
|
|
limit_type:
|
|
description: "Which limit was hit: included allowance, max purchase cap, or
|
|
spend limit."
|
|
type: string
|
|
enum:
|
|
- included
|
|
- max_purchase
|
|
- spend_limit
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
- limit_type
|
|
additionalProperties: false
|
|
example:
|
|
type: balances.limit_reached
|
|
data:
|
|
customer_id: org_123
|
|
entity_id: workspace_abc
|
|
feature_id: api_calls
|
|
limit_type: included
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
billing.auto_topup_succeeded:
|
|
post:
|
|
operationId: billingAutoTopupSucceeded
|
|
summary: Auto Top-Up Succeeded
|
|
description: Fired when an automatic top-up grants additional prepaid balance.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: billing.auto_topup_succeeded
|
|
description: The webhook event type.
|
|
data:
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
quantity_granted: 100
|
|
threshold: 20
|
|
balance_after: 115
|
|
invoice_mode: false
|
|
invoice:
|
|
stripe_id: in_1A2B3C4D5E6F7G8H
|
|
status: paid
|
|
total: 1000
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
description: The ID of the customer whose balance was topped up.
|
|
type: string
|
|
feature_id:
|
|
description: The feature ID that was automatically topped up.
|
|
type: string
|
|
quantity_granted:
|
|
description: The normalized amount of balance granted by the top-up.
|
|
type: number
|
|
threshold:
|
|
description: The configured balance threshold that triggered the top-up.
|
|
type: number
|
|
balance_after:
|
|
description: The customer's remaining balance for the feature after the top-up.
|
|
type: number
|
|
invoice_mode:
|
|
description: Whether the auto top-up created a send_invoice invoice instead of
|
|
auto-charging.
|
|
type: boolean
|
|
invoice:
|
|
description: The invoice created for the auto top-up.
|
|
type: object
|
|
properties:
|
|
stripe_id:
|
|
description: The Stripe invoice ID. Use this as a stable dedupe key.
|
|
type: string
|
|
status:
|
|
description: The status of the invoice. "paid" for auto-charged top-ups; "open"
|
|
for invoice-mode top-ups where credits were granted
|
|
but the invoice has not yet been paid.
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
total:
|
|
description: The total amount of the invoice in the smallest currency unit (e.g.
|
|
cents for USD), matching Stripe's invoice.total.
|
|
type: number
|
|
currency:
|
|
description: The ISO currency code for the invoice.
|
|
type: string
|
|
hosted_invoice_url:
|
|
description: URL to the hosted invoice page, if available.
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
additionalProperties: false
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
- quantity_granted
|
|
- threshold
|
|
- balance_after
|
|
- invoice_mode
|
|
- invoice
|
|
additionalProperties: false
|
|
example:
|
|
type: billing.auto_topup_succeeded
|
|
data:
|
|
customer_id: cus_123
|
|
feature_id: messages
|
|
quantity_granted: 100
|
|
threshold: 20
|
|
balance_after: 115
|
|
invoice_mode: false
|
|
invoice:
|
|
stripe_id: in_1A2B3C4D5E6F7G8H
|
|
status: paid
|
|
total: 1000
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
billing.updated:
|
|
post:
|
|
operationId: billingUpdated
|
|
summary: Plans Updated
|
|
description: Fired when a customer's plans change — activated, scheduled,
|
|
updated, or expired. Each event carries a `plan_changes` array
|
|
describing what happened and a `tags` array (e.g. `trial_ended`,
|
|
`phase_changed`) describing why.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: billing.updated
|
|
description: The webhook event type.
|
|
data:
|
|
examples:
|
|
- object: billing.updated
|
|
customer_id: cus_123
|
|
plan_changes:
|
|
- action: activated
|
|
subscription:
|
|
plan_id: pro
|
|
status: active
|
|
past_due: false
|
|
started_at: 1779000000000
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
current_period_start: 1779000000000
|
|
current_period_end: 1781592000000
|
|
previous_attributes: null
|
|
item_changes: []
|
|
- action: expired
|
|
subscription:
|
|
plan_id: free
|
|
status: expired
|
|
past_due: false
|
|
started_at: 1776000000000
|
|
canceled_at: 1779000000000
|
|
expires_at: 1779000000000
|
|
trial_ends_at: null
|
|
current_period_start: null
|
|
current_period_end: null
|
|
previous_attributes:
|
|
status: active
|
|
item_changes: []
|
|
tags: []
|
|
type: object
|
|
properties:
|
|
object:
|
|
type: string
|
|
const: billing.updated
|
|
customer_id:
|
|
description: The ID of the customer whose plans changed.
|
|
type: string
|
|
entity_id:
|
|
description: The ID of the entity, if the changes are scoped to a specific
|
|
entity.
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plan_changes:
|
|
description: The plans that were activated, scheduled, updated, or expired.
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
action:
|
|
description: "The lifecycle action applied to this plan: activated (newly active
|
|
on the customer), scheduled (queued for a future
|
|
start), updated (mutated in place), or expired
|
|
(ended)."
|
|
type: string
|
|
enum:
|
|
- activated
|
|
- scheduled
|
|
- updated
|
|
- expired
|
|
subscription:
|
|
description: The subscription as it stands after this change. Present when the
|
|
plan is billed as a recurring subscription.
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
description: The ID of the customer plan.
|
|
type: string
|
|
status:
|
|
description: The current status of the subscription on the customer.
|
|
type: string
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
- expired
|
|
past_due:
|
|
description: Whether the subscription has overdue payments.
|
|
type: boolean
|
|
started_at:
|
|
description: When the subscription started, in milliseconds since the Unix
|
|
epoch.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
canceled_at:
|
|
description: When the subscription was canceled, in milliseconds since the Unix
|
|
epoch, or null if not canceled.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
expires_at:
|
|
description: When the subscription ends, in milliseconds since the Unix epoch,
|
|
or null if no expiry is set.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
trial_ends_at:
|
|
description: When the trial ends, in milliseconds since the Unix epoch. Null
|
|
when not actively trialing.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
current_period_start:
|
|
description: Start of the current billing period, or null if not applicable.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
current_period_end:
|
|
description: End of the current billing period, or null if not applicable.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- status
|
|
- past_due
|
|
- started_at
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- current_period_start
|
|
- current_period_end
|
|
additionalProperties: false
|
|
purchase:
|
|
description: The purchase as it stands after this change. Present when the plan
|
|
is a one-off purchase.
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
description: The ID of the customer plan.
|
|
type: string
|
|
status:
|
|
description: The current status of the purchase on the customer.
|
|
type: string
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
- expired
|
|
expires_at:
|
|
description: When the purchase ends, in milliseconds since the Unix epoch, or
|
|
null if no expiry is set.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- status
|
|
- expires_at
|
|
additionalProperties: false
|
|
previous_attributes:
|
|
description: Sparse map of scalar fields whose values changed, holding their
|
|
previous values. Null when the plan is newly
|
|
activated or scheduled.
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
item_changes:
|
|
description: Features that were added to or removed from this plan. Only
|
|
populated for updated plans.
|
|
default: []
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
action:
|
|
description: Whether the feature was added to or removed from the plan.
|
|
type: string
|
|
enum:
|
|
- created
|
|
- deleted
|
|
feature_id:
|
|
description: The ID of the feature that was added or removed.
|
|
type: string
|
|
item:
|
|
description: The item snapshot that was added or removed.
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
description: The ID of the feature this item configures.
|
|
type: string
|
|
feature:
|
|
description: The full feature object if expanded.
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
type: string
|
|
name:
|
|
description: The name of the feature.
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
type:
|
|
description: The type of the feature
|
|
type: string
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
- ai_credit_system
|
|
display:
|
|
description: Singular and plural display names for the feature.
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
description: The singular display name for the feature.
|
|
type: string
|
|
plural:
|
|
description: The plural display name for the feature.
|
|
type: string
|
|
required:
|
|
- singular
|
|
- plural
|
|
additionalProperties: false
|
|
- type: "null"
|
|
credit_schema:
|
|
description: Credit cost schema for credit system features.
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
type: string
|
|
credit_cost:
|
|
description: The credit cost of the metered feature.
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
additionalProperties: false
|
|
- type: "null"
|
|
archived:
|
|
description: Whether or not the feature is archived.
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
- type
|
|
additionalProperties: false
|
|
included:
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
type: number
|
|
unlimited:
|
|
description: Whether the customer has unlimited access to this feature.
|
|
type: boolean
|
|
reset:
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where
|
|
usage persists across billing cycles.
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
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.
|
|
type: string
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
type: number
|
|
required:
|
|
- interval
|
|
additionalProperties: false
|
|
- type: "null"
|
|
price:
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
type: number
|
|
tiers:
|
|
description: Tiered pricing configuration. Each tier's 'to' INCLUDES the
|
|
included amount. Either 'tiers'
|
|
or 'amount' is required.
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- type: string
|
|
const: inf
|
|
amount:
|
|
type: number
|
|
flat_amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
additionalProperties: false
|
|
tier_behavior:
|
|
type: string
|
|
enum:
|
|
- graduated
|
|
- volume
|
|
interval:
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
type: string
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
type: number
|
|
billing_units:
|
|
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).
|
|
type: number
|
|
billing_method:
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go
|
|
after included usage."
|
|
type: string
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
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.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
additionalProperties: false
|
|
- type: "null"
|
|
display:
|
|
description: Display text for showing this item in pricing pages.
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
type: string
|
|
secondary_text:
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
type: string
|
|
required:
|
|
- primary_text
|
|
additionalProperties: false
|
|
rollover:
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
type: object
|
|
properties:
|
|
max:
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
max_percentage:
|
|
description: Maximum rollover as a percentage (0-100) of included + prepaid
|
|
grant. Mutually exclusive with max.
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
expiry_duration_type:
|
|
description: When rolled over units expire.
|
|
type: string
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
description: Number of periods before expiry.
|
|
type: number
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
additionalProperties: false
|
|
proration:
|
|
internal: true
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
description: How to handle billing when quantity increases mid-cycle.
|
|
type: string
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
description: How to handle credits when quantity decreases mid-cycle.
|
|
type: string
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
additionalProperties: false
|
|
entity_feature_id:
|
|
internal: true
|
|
type: string
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
additionalProperties: false
|
|
required:
|
|
- action
|
|
- feature_id
|
|
- item
|
|
additionalProperties: false
|
|
required:
|
|
- action
|
|
- previous_attributes
|
|
- item_changes
|
|
additionalProperties: false
|
|
tags:
|
|
description: Reason tags describing why this event fired (e.g. 'trial_ended',
|
|
'phase_changed'). Always present; empty when no specific
|
|
reason applies.
|
|
default: []
|
|
type: array
|
|
items:
|
|
type: string
|
|
required:
|
|
- object
|
|
- customer_id
|
|
- plan_changes
|
|
- tags
|
|
additionalProperties: false
|
|
example:
|
|
type: billing.updated
|
|
data:
|
|
object: billing.updated
|
|
customer_id: cus_123
|
|
plan_changes:
|
|
- action: activated
|
|
subscription:
|
|
plan_id: pro
|
|
status: active
|
|
past_due: false
|
|
started_at: 1779000000000
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
current_period_start: 1779000000000
|
|
current_period_end: 1781592000000
|
|
previous_attributes: null
|
|
item_changes: []
|
|
- action: expired
|
|
subscription:
|
|
plan_id: free
|
|
status: expired
|
|
past_due: false
|
|
started_at: 1776000000000
|
|
canceled_at: 1779000000000
|
|
expires_at: 1779000000000
|
|
trial_ends_at: null
|
|
current_period_start: null
|
|
current_period_end: null
|
|
previous_attributes:
|
|
status: active
|
|
item_changes: []
|
|
tags: []
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
vercel.resources.deleted:
|
|
post:
|
|
operationId: vercelResourcesDeleted
|
|
summary: Resource Deleted
|
|
description: When a Vercel resource is deleted, you'll need to handle
|
|
de-provisioning any API keys or other non-Autumn controlled data for
|
|
this user.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: vercel.resources.deleted
|
|
description: The webhook event type.
|
|
data:
|
|
type: object
|
|
properties:
|
|
resource:
|
|
description: The resource that was deleted.
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: The unique identifier of the deleted resource.
|
|
type: string
|
|
required:
|
|
- id
|
|
additionalProperties: false
|
|
installation_id:
|
|
description: The Vercel integration configuration ID.
|
|
type: string
|
|
required:
|
|
- resource
|
|
- installation_id
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
vercel.resources.provisioned:
|
|
post:
|
|
operationId: vercelResourcesProvisioned
|
|
summary: Resource Provisioned
|
|
description: When a Vercel resource is created, you'll need to provision a
|
|
secret key for your service. Then you can use the provided access token
|
|
to patch the resource's secrets.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: vercel.resources.provisioned
|
|
description: The webhook event type.
|
|
data:
|
|
type: object
|
|
properties:
|
|
resource:
|
|
description: The resource that was provisioned.
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: The unique identifier of the provisioned resource.
|
|
type: string
|
|
name:
|
|
description: The display name of the provisioned resource.
|
|
type: string
|
|
required:
|
|
- id
|
|
- name
|
|
additionalProperties: false
|
|
installation_id:
|
|
description: The Vercel integration configuration ID.
|
|
type: string
|
|
access_token:
|
|
description: An access token that can be used to patch the resource's secrets.
|
|
type: string
|
|
required:
|
|
- resource
|
|
- installation_id
|
|
- access_token
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
vercel.resources.rotate_secrets:
|
|
post:
|
|
operationId: vercelResourcesRotateSecrets
|
|
summary: Rotate Secrets
|
|
description: This event is sent when Vercel requires a resource's secrets to be
|
|
rotated.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: vercel.resources.rotate_secrets
|
|
description: The webhook event type.
|
|
data:
|
|
type: object
|
|
properties:
|
|
resource:
|
|
description: The resource whose secrets should be rotated.
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: The unique identifier of the resource.
|
|
type: string
|
|
required:
|
|
- id
|
|
additionalProperties: false
|
|
installation_id:
|
|
description: The Vercel integration configuration ID.
|
|
type: string
|
|
vercel_request_body:
|
|
description: The raw request body from Vercel's rotation request.
|
|
required:
|
|
- resource
|
|
- installation_id
|
|
- vercel_request_body
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|
|
vercel.webhooks.event:
|
|
post:
|
|
operationId: vercelWebhooksEvent
|
|
summary: Webhook Event
|
|
description: Passthrough webhook for Vercel events.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- type
|
|
- data
|
|
properties:
|
|
type:
|
|
type: string
|
|
const: vercel.webhooks.event
|
|
description: The webhook event type.
|
|
data:
|
|
type: object
|
|
properties:
|
|
installation_id:
|
|
description: The Vercel integration configuration ID.
|
|
type: string
|
|
event:
|
|
description: The raw Vercel webhook event payload.
|
|
required:
|
|
- installation_id
|
|
- event
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Webhook received successfully.
|