8910 lines
366 KiB
YAML
8910 lines
366 KiB
YAML
info:
|
|
title: Autumn API
|
|
version: 2.1.0
|
|
servers:
|
|
- url: https://api.useautumn.com
|
|
description: Production server
|
|
openapi: 3.1.1
|
|
components:
|
|
schemas:
|
|
CustomerId:
|
|
type: string
|
|
title: CustomerId
|
|
description: Your unique identifier for the customer
|
|
CustomerData:
|
|
type: object
|
|
properties:
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
create_in_stripe:
|
|
type: boolean
|
|
description: Whether to create the customer in Stripe
|
|
auto_enable_plan_id:
|
|
type: string
|
|
description: The ID of the free plan to auto-enable for the customer
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
title: CustomerData
|
|
description: Customer details to set when creating a customer
|
|
CustomerExpand:
|
|
enum:
|
|
- invoices
|
|
- trials_used
|
|
- rewards
|
|
- entities
|
|
- referrals
|
|
- payment_method
|
|
- subscriptions.plan
|
|
- purchases.plan
|
|
- balances.feature
|
|
title: CustomerExpand
|
|
Customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
entities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
autumn_id:
|
|
type: string
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment (sandbox/live)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
trials_used:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
customer_id:
|
|
type: string
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- customer_id
|
|
rewards:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this discount
|
|
name:
|
|
type: string
|
|
description: The name of the discount or coupon
|
|
type:
|
|
enum:
|
|
- percentage_discount
|
|
- fixed_discount
|
|
- free_product
|
|
- invoice_credits
|
|
description: The type of reward
|
|
discount_value:
|
|
type: number
|
|
description: The discount value (percentage or fixed amount)
|
|
duration_type:
|
|
enum:
|
|
- one_off
|
|
- months
|
|
- forever
|
|
description: How long the discount lasts
|
|
duration_value:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Number of billing periods the discount applies for repeating
|
|
durations
|
|
currency:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The currency code for fixed amount discounts
|
|
start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount becomes active
|
|
end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount expires
|
|
subscription_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The Stripe subscription ID this discount is applied to
|
|
total_discount_amount:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Total amount saved from this discount
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- discount_value
|
|
- duration_type
|
|
description: Array of active discounts applied to the customer
|
|
required:
|
|
- discounts
|
|
- type: "null"
|
|
referrals:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
program_id:
|
|
type: string
|
|
customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
reward_applied:
|
|
type: boolean
|
|
created_at:
|
|
type: number
|
|
required:
|
|
- program_id
|
|
- customer
|
|
- reward_applied
|
|
- created_at
|
|
payment_method:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
Plan:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
description: The type of the feature
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
description: The singular display name for the feature.
|
|
plural:
|
|
type: string
|
|
description: The plural display name for the feature.
|
|
required:
|
|
- singular
|
|
- plural
|
|
- type: "null"
|
|
description: Singular and plural display names for the feature.
|
|
credit_schema:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
credit_cost:
|
|
type: number
|
|
description: The credit cost of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
- type: "null"
|
|
description: Credit cost schema for credit system features.
|
|
archived:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether or not the feature is archived.
|
|
required:
|
|
- id
|
|
- type
|
|
description: The full feature object if expanded.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the customer has unlimited access to this feature.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the feature balance resets (e.g. 'month',
|
|
'year'). For consumable features, usage resets to 0
|
|
and included units are restored.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where usage persists across
|
|
billing cycles.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'up_to' does NOT include
|
|
the included amount. Either 'tiers' or 'amount' is
|
|
required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer can use up
|
|
to 400 total before usage is capped. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
Balance:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools."
|
|
consumable:
|
|
type: boolean
|
|
description: "For metered features: true if usage resets periodically (API
|
|
calls, credits), false if allocated persistently (seats,
|
|
storage)."
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Event names that trigger this feature's balance. Allows multiple
|
|
features to respond to a single event.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: ID of the metered feature that draws from this credit system.
|
|
credit_cost:
|
|
type: number
|
|
description: Credits consumed per unit of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: "For credit_system features: maps metered features to their credit
|
|
costs."
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
description: The full feature object if expanded.
|
|
granted:
|
|
type: number
|
|
description: Total balance granted (included + prepaid).
|
|
remaining:
|
|
type: number
|
|
minimum: 0
|
|
description: Remaining balance available for use.
|
|
usage:
|
|
type: number
|
|
description: Total usage consumed in the current period.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether this feature has unlimited usage.
|
|
overage_allowed:
|
|
type: boolean
|
|
description: Whether usage beyond the granted balance is allowed (with overage
|
|
charges).
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum quantity that can be purchased as a top-up, or null for
|
|
unlimited.
|
|
next_reset_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will reset, or null for no reset.
|
|
breakdown:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
default: ""
|
|
description: The unique identifier for this balance breakdown.
|
|
plan_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The plan ID this balance originates from, or null for standalone
|
|
balances.
|
|
included_grant:
|
|
type: number
|
|
description: Amount granted from the plan's included usage.
|
|
prepaid_grant:
|
|
type: number
|
|
description: Amount granted from prepaid purchases or top-ups.
|
|
remaining:
|
|
type: number
|
|
description: Remaining balance available for use.
|
|
usage:
|
|
type: number
|
|
description: Amount consumed in the current period.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether this balance has unlimited usage.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
- const: multiple
|
|
description: The reset interval (hour, day, week, month, etc.) or 'multiple' if
|
|
combined from different intervals.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets (eg. 2 for bi-monthly).
|
|
resets_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the balance will next reset.
|
|
required:
|
|
- interval
|
|
- resets_at
|
|
- type: "null"
|
|
description: Reset configuration for this balance, or null if no reset.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: The per-unit price amount.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration if applicable.
|
|
billing_units:
|
|
type: number
|
|
description: The number of units per billing increment (eg. $9 / 250 units).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: Whether usage is prepaid or billed pay-per-use.
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum quantity that can be purchased, or null for unlimited.
|
|
required:
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration if this balance has usage-based pricing.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when this balance expires, or null for no expiration.
|
|
required:
|
|
- plan_id
|
|
- included_grant
|
|
- prepaid_grant
|
|
- remaining
|
|
- usage
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
- expires_at
|
|
description: Detailed breakdown of balance sources when stacking multiple plans
|
|
or grants.
|
|
rollovers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
balance:
|
|
type: number
|
|
description: Amount of balance rolled over from a previous period.
|
|
expires_at:
|
|
type: number
|
|
description: Timestamp when the rollover balance expires.
|
|
required:
|
|
- balance
|
|
- expires_at
|
|
description: Rollover balances carried over from previous periods.
|
|
required:
|
|
- feature_id
|
|
- granted
|
|
- remaining
|
|
- usage
|
|
- unlimited
|
|
- overage_allowed
|
|
- max_purchase
|
|
- next_reset_at
|
|
examples:
|
|
- feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
securitySchemes:
|
|
secretKey:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
paths:
|
|
/v1/customers.get_or_create:
|
|
post:
|
|
operationId: getOrCreateCustomer
|
|
description: >-
|
|
Creates a customer if they do not exist, or returns the existing
|
|
customer by your external customer ID.
|
|
|
|
|
|
Use this as the primary entrypoint before billing operations so the
|
|
customer record is always present and up to date.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create or fetch a customer by external ID
|
|
|
|
const response = await client.getOrCreate({ customerId: "cus_123", name:
|
|
"John Doe", email: "john@example.com" });
|
|
|
|
```
|
|
|
|
|
|
@param name - Customer's name (optional)
|
|
|
|
@param email - Customer's email address (optional)
|
|
|
|
@param fingerprint - Unique identifier (eg, serial number) to detect
|
|
duplicate customers and prevent free trial abuse (optional)
|
|
|
|
@param metadata - Additional metadata for the customer (optional)
|
|
|
|
@param stripeId - Stripe customer ID if you already have one (optional)
|
|
|
|
@param createInStripe - Whether to create the customer in Stripe
|
|
(optional)
|
|
|
|
@param autoEnablePlanId - The ID of the free plan to auto-enable for the
|
|
customer (optional)
|
|
|
|
@param sendEmailReceipts - Whether to send email receipts to this
|
|
customer (optional)
|
|
|
|
@param expand - Customer expand options (optional)
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/CustomerId"
|
|
- type: "null"
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
create_in_stripe:
|
|
type: boolean
|
|
description: Whether to create the customer in Stripe
|
|
auto_enable_plan_id:
|
|
type: string
|
|
description: The ID of the free plan to auto-enable for the customer
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
expand:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerExpand"
|
|
description: Customer expand options
|
|
required:
|
|
- customer_id
|
|
title: GetOrCreateCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
name: John Doe
|
|
email: john@example.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
x-speakeasy-name-override: getOrCreate
|
|
parameters:
|
|
- &a1
|
|
name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
/v1/customers.list:
|
|
post:
|
|
operationId: listCustomers
|
|
description: Lists customers with pagination and optional filters.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
default: 0
|
|
description: Number of items to skip
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 10
|
|
description: Number of items to return. Default 10, max 1000.
|
|
plans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
versions:
|
|
type: array
|
|
items:
|
|
type: number
|
|
required:
|
|
- id
|
|
description: Filter by plan ID and version. Returns customers with active
|
|
subscriptions to this plan.
|
|
subscription_status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Filter by customer product status. Defaults to active and scheduled
|
|
search:
|
|
type: string
|
|
description: Search customers by id, name, or email
|
|
title: ListCustomersParams
|
|
examples:
|
|
- limit: 10
|
|
offset: 0
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple
|
|
device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
description: Array of items for current page
|
|
has_more:
|
|
type: boolean
|
|
description: Whether more results exist after this page
|
|
offset:
|
|
type: number
|
|
description: Current offset position
|
|
limit:
|
|
type: number
|
|
description: Limit passed in the request
|
|
total:
|
|
type: number
|
|
description: Total number of items returned in the current page
|
|
required:
|
|
- list
|
|
- has_more
|
|
- offset
|
|
- limit
|
|
- total
|
|
examples:
|
|
- list:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
has_more: false
|
|
offset: 0
|
|
total: 1
|
|
limit: 10
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/customers.update:
|
|
post:
|
|
operationId: updateCustomer
|
|
description: Updates an existing customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to update
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
new_customer_id:
|
|
$ref: "#/components/schemas/CustomerId"
|
|
description: New ID for the customer
|
|
required:
|
|
- customer_id
|
|
title: UpdateCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
name: Jane Doe
|
|
email: jane@example.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/customers.delete:
|
|
post:
|
|
operationId: deleteCustomer
|
|
description: Deletes a customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to delete
|
|
delete_in_stripe:
|
|
type: boolean
|
|
default: false
|
|
description: Whether to also delete the customer in Stripe
|
|
required:
|
|
- customer_id
|
|
title: DeleteCustomerParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
delete_in_stripe: false
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.create:
|
|
post:
|
|
operationId: createPlan
|
|
summary: Create a plan
|
|
description: |-
|
|
Creates a new plan with optional base price and feature configurations.
|
|
|
|
Use this to programmatically create pricing plans. See [How plans work](/documentation/pricing/plans) for concepts.
|
|
|
|
@example
|
|
```typescript
|
|
// Create a free plan with limited features
|
|
const response = await client.plans.create({
|
|
planId: "free_plan",
|
|
name: "Free",
|
|
autoEnable: true,
|
|
items: [{"featureId":"messages","included":100,"reset":{"interval":"month"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a paid plan with base price and usage-based feature
|
|
const response = await client.plans.create({
|
|
planId: "pro_plan",
|
|
name: "Pro Plan",
|
|
price: {"amount":10,"interval":"month"},
|
|
items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"},"price":{"amount":0.01,"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with prepaid seats
|
|
const response = await client.plans.create({
|
|
planId: "team_plan",
|
|
name: "Team Plan",
|
|
price: {"amount":49,"interval":"month"},
|
|
items: [{"featureId":"seats","included":5,"price":{"amount":10,"interval":"month","billingUnits":1,"billingMethod":"prepaid"}}],
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create an add-on plan
|
|
const response = await client.plans.create({
|
|
planId: "analytics_addon",
|
|
name: "Advanced Analytics",
|
|
addOn: true,
|
|
price: {"amount":20,"interval":"month"},
|
|
});
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with tiered pricing
|
|
const response = await client.plans.create({ planId: "api_plan", name: "API Plan", items: [{"featureId":"api_calls","included":1000,"reset":{"interval":"month"},"price":{"tiers":[{"to":10000,"amount":0.001},{"to":100000,"amount":0.0005},{"to":"inf","amount":0.0001}],"interval":"month","billingUnits":1,"billingMethod":"usage_based"}}] });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Create a plan with free trial
|
|
const response = await client.plans.create({
|
|
planId: "premium_plan",
|
|
name: "Premium",
|
|
price: {"amount":99,"interval":"month"},
|
|
freeTrial: {"durationLength":14,"durationType":"day","cardRequired":true},
|
|
});
|
|
```
|
|
|
|
@param planId - The ID of the plan to create.
|
|
@param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional)
|
|
@param name - Display name of the plan.
|
|
@param description - Optional description of the plan. (optional)
|
|
@param addOn - If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group. (optional)
|
|
@param autoEnable - If true, plan is automatically attached when a customer is created. Use for free tiers. (optional)
|
|
@param price - Base recurring price for the plan. Omit for free or usage-only plans. (optional)
|
|
@param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional)
|
|
@param freeTrial - Free trial configuration. Customers can try this plan before being charged. (optional)
|
|
|
|
@returns The created plan object.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The ID of the plan to create.
|
|
group:
|
|
type: string
|
|
default: ""
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
default: null
|
|
description: Optional description of the plan.
|
|
add_on:
|
|
type: boolean
|
|
default: false
|
|
description: If true, this plan can be attached alongside other plans.
|
|
Otherwise, attaching replaces existing plans in the same
|
|
group.
|
|
auto_enable:
|
|
type: boolean
|
|
default: false
|
|
description: If true, plan is automatically attached when a customer is created.
|
|
Use for free tiers.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
description: Base recurring price for the plan. Omit for free or usage-only
|
|
plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Feature configurations for this plan. Each item defines included
|
|
units, pricing, and reset behavior.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
description: Free trial configuration. Customers can try this plan before being
|
|
charged.
|
|
required:
|
|
- plan_id
|
|
- name
|
|
title: CreatePlanParams
|
|
examples:
|
|
- plan_id: free_plan
|
|
name: Free
|
|
auto_enable: true
|
|
items:
|
|
- feature_id: messages
|
|
included: 100
|
|
reset:
|
|
interval: month
|
|
- plan_id: pro_plan
|
|
name: Pro Plan
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
items:
|
|
- feature_id: messages
|
|
included: 1000
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.01
|
|
interval: month
|
|
billing_units: 1
|
|
billing_method: usage_based
|
|
- plan_id: team_plan
|
|
name: Team Plan
|
|
price:
|
|
amount: 49
|
|
interval: month
|
|
items:
|
|
- feature_id: seats
|
|
included: 5
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billing_units: 1
|
|
billing_method: prepaid
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
description: The type of the feature
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
description: The singular display name for the feature.
|
|
plural:
|
|
type: string
|
|
description: The plural display name for the feature.
|
|
required:
|
|
- singular
|
|
- plural
|
|
- type: "null"
|
|
description: Singular and plural display names for the feature.
|
|
credit_schema:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
credit_cost:
|
|
type: number
|
|
description: The credit cost of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
- type: "null"
|
|
description: Credit cost schema for credit system features.
|
|
archived:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether or not the feature is archived.
|
|
required:
|
|
- id
|
|
- type
|
|
description: The full feature object if expanded.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the customer has unlimited access to this feature.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the feature balance resets (e.g. 'month',
|
|
'year'). For consumable features, usage
|
|
resets to 0 and included units are restored.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where usage
|
|
persists across billing cycles.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'up_to' does NOT include
|
|
the included amount. Either 'tiers' or
|
|
'amount' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.get:
|
|
post:
|
|
operationId: getPlan
|
|
summary: Get a plan
|
|
description: >-
|
|
Retrieves a single plan by its ID.
|
|
|
|
|
|
Use this to fetch the full configuration of a specific plan, including
|
|
its features and pricing.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Get a plan by ID
|
|
|
|
const response = await client.plans.get({ planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Get a specific version of a plan
|
|
|
|
const response = await client.plans.get({ planId: "pro_plan", version: 2
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param planId - The ID of the plan to retrieve.
|
|
|
|
@param version - The version of the plan to get. Defaults to the latest
|
|
version. (optional)
|
|
|
|
|
|
@returns The plan object with its full configuration.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
description: The ID of the plan to retrieve.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to get. Defaults to the latest version.
|
|
required:
|
|
- plan_id
|
|
title: GetPlanParams
|
|
examples:
|
|
- plan_id: pro_plan
|
|
- plan_id: pro_plan
|
|
version: 2
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
description: The type of the feature
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
description: The singular display name for the feature.
|
|
plural:
|
|
type: string
|
|
description: The plural display name for the feature.
|
|
required:
|
|
- singular
|
|
- plural
|
|
- type: "null"
|
|
description: Singular and plural display names for the feature.
|
|
credit_schema:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
credit_cost:
|
|
type: number
|
|
description: The credit cost of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
- type: "null"
|
|
description: Credit cost schema for credit system features.
|
|
archived:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether or not the feature is archived.
|
|
required:
|
|
- id
|
|
- type
|
|
description: The full feature object if expanded.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the customer has unlimited access to this feature.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the feature balance resets (e.g. 'month',
|
|
'year'). For consumable features, usage
|
|
resets to 0 and included units are restored.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where usage
|
|
persists across billing cycles.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'up_to' does NOT include
|
|
the included amount. Either 'tiers' or
|
|
'amount' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.list:
|
|
post:
|
|
operationId: listPlans
|
|
summary: List all plans
|
|
description: >-
|
|
Lists all plans in the current environment.
|
|
|
|
|
|
Use this to retrieve all plans for displaying pricing pages or managing
|
|
plan configurations.
|
|
|
|
|
|
@returns A list of all plans with their pricing and feature
|
|
configurations.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: Customer ID to include eligibility info (trial availability, attach
|
|
scenario).
|
|
entity_id:
|
|
type: string
|
|
description: Entity ID for entity-scoped plans.
|
|
include_archived:
|
|
type: boolean
|
|
description: If true, includes archived plans in the response.
|
|
title: ListPlansParams
|
|
examples:
|
|
- {}
|
|
- customer_id: cus_123
|
|
- include_archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
description: The type of the feature
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
description: The singular display name for the feature.
|
|
plural:
|
|
type: string
|
|
description: The plural display name for the feature.
|
|
required:
|
|
- singular
|
|
- plural
|
|
- type: "null"
|
|
description: Singular and plural display names for the feature.
|
|
credit_schema:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
credit_cost:
|
|
type: number
|
|
description: The credit cost of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
- type: "null"
|
|
description: Credit cost schema for credit system features.
|
|
archived:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether or not the feature is archived.
|
|
required:
|
|
- id
|
|
- type
|
|
description: The full feature object if expanded.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the customer has unlimited access to this feature.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the feature balance resets (e.g. 'month',
|
|
'year'). For consumable features,
|
|
usage resets to 0 and included units
|
|
are restored.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where usage
|
|
persists across billing cycles.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'up_to' does NOT include
|
|
the included amount. Either 'tiers' or
|
|
'amount' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed
|
|
(e.g. billing_units=100 means 101
|
|
usage rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300,
|
|
customer can use up to 400 total
|
|
before usage is capped. Null for no
|
|
limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a
|
|
feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
required:
|
|
- list
|
|
examples:
|
|
- list:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.update:
|
|
post:
|
|
operationId: updatePlan
|
|
summary: Update a plan
|
|
description: |-
|
|
Updates an existing plan. Creates a new version unless `disableVersion` is set.
|
|
|
|
Use this to modify plan properties, pricing, or feature configurations. See [Adding features to plans](/documentation/pricing/plan-features) for item configuration.
|
|
|
|
@example
|
|
```typescript
|
|
// Update plan name and price
|
|
const response = await client.plans.update({ planId: "pro_plan", name: "Pro Plan (Updated)", price: {"amount":15,"interval":"month"} });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Add a feature to an existing plan
|
|
const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":1000,"reset":{"interval":"month"}},{"featureId":"storage","included":10,"reset":{"interval":"month"}}] });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Remove the base price (make usage-only)
|
|
const response = await client.plans.update({ planId: "pro_plan", price: null });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Archive a plan
|
|
const response = await client.plans.update({ planId: "old_plan", archived: true });
|
|
```
|
|
|
|
@example
|
|
```typescript
|
|
// Update feature's included amount
|
|
const response = await client.plans.update({ planId: "pro_plan", items: [{"featureId":"messages","included":2000,"reset":{"interval":"month"}}] });
|
|
```
|
|
|
|
@param planId - The ID of the plan to update.
|
|
@param group - Group identifier for organizing related plans. Plans in the same group are mutually exclusive. (optional)
|
|
@param name - Display name of the plan. (optional)
|
|
@param addOn - Whether the plan is an add-on. (optional)
|
|
@param autoEnable - Whether the plan is automatically enabled. (optional)
|
|
@param price - The price of the plan. Set to null to remove the base price. (optional)
|
|
@param items - Feature configurations for this plan. Each item defines included units, pricing, and reset behavior. (optional)
|
|
@param freeTrial - The free trial of the plan. Set to null to remove the free trial. (optional)
|
|
@param newPlanId - The new ID to use for the plan. Can only be updated if the plan has not been used by any customers. (optional)
|
|
|
|
@returns The updated plan object.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The ID of the plan to update.
|
|
group:
|
|
type: string
|
|
default: ""
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: Display name of the plan.
|
|
description:
|
|
type: string
|
|
add_on:
|
|
type: boolean
|
|
description: Whether the plan is an add-on.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan is automatically enabled.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: The price of the plan. Set to null to remove the base price.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Feature configurations for this plan. Each item defines included
|
|
units, pricing, and reset behavior.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- type: "null"
|
|
description: The free trial of the plan. Set to null to remove the free trial.
|
|
version:
|
|
type: number
|
|
archived:
|
|
type: boolean
|
|
default: false
|
|
new_plan_id:
|
|
type: string
|
|
minLength: 1
|
|
pattern: ^[a-zA-Z0-9_-]+$
|
|
description: The new ID to use for the plan. Can only be updated if the plan has
|
|
not been used by any customers.
|
|
required:
|
|
- plan_id
|
|
title: UpdatePlanParams
|
|
examples:
|
|
- plan_id: pro_plan
|
|
name: Pro Plan (Updated)
|
|
price:
|
|
amount: 15
|
|
interval: month
|
|
- plan_id: pro_plan
|
|
price: null
|
|
- plan_id: old_plan
|
|
archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for the plan.
|
|
name:
|
|
type: string
|
|
description: Display name of the plan.
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Optional description of the plan.
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Group identifier for organizing related plans. Plans in the same
|
|
group are mutually exclusive.
|
|
version:
|
|
type: number
|
|
description: Version number of the plan. Incremented when plan configuration
|
|
changes.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan that can be attached alongside a
|
|
main plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: If true, this plan is automatically attached when a customer is
|
|
created. Used for free plans.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this price in pricing pages.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
description: Base recurring price for the plan. Null for free plans or
|
|
usage-only plans.
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this item configures.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the feature, used to refer to it in other API calls like
|
|
/track or /check.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- static
|
|
- boolean
|
|
- single_use
|
|
- continuous_use
|
|
- credit_system
|
|
description: The type of the feature
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
description: The singular display name for the feature.
|
|
plural:
|
|
type: string
|
|
description: The plural display name for the feature.
|
|
required:
|
|
- singular
|
|
- plural
|
|
- type: "null"
|
|
description: Singular and plural display names for the feature.
|
|
credit_schema:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: The ID of the metered feature (should be a single_use feature).
|
|
credit_cost:
|
|
type: number
|
|
description: The credit cost of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
- type: "null"
|
|
description: Credit cost schema for credit system features.
|
|
archived:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether or not the feature is archived.
|
|
required:
|
|
- id
|
|
- type
|
|
description: The full feature object if expanded.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. For consumable features, balance
|
|
resets to this number each interval.
|
|
unlimited:
|
|
type: boolean
|
|
description: Whether the customer has unlimited access to this feature.
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the feature balance resets (e.g. 'month',
|
|
'year'). For consumable features, usage
|
|
resets to 0 and included units are restored.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
description: Reset configuration for consumable features. Null for
|
|
non-consumable features like seats where usage
|
|
persists across billing cycles.
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage is consumed. Mutually
|
|
exclusive with tiers.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing configuration. Each tier's 'up_to' does NOT include
|
|
the included amount. Either 'tiers' or
|
|
'amount' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval for this price. For consumable features, should
|
|
match reset.interval.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
description: Number of units per price increment. Usage is rounded UP to the
|
|
nearest billing_units when billed (e.g.
|
|
billing_units=100 means 101 usage rounds to
|
|
200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for features like seats where customers pay upfront,
|
|
'usage_based' for pay-as-you-go after
|
|
included usage."
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum units a customer can purchase beyond included. E.g. if
|
|
included=100 and max_purchase=300, customer
|
|
can use up to 400 total before usage is
|
|
capped. Null for no limit.
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
description: Pricing configuration for usage beyond included units. Null if
|
|
feature is entirely free.
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
description: Main display text (e.g. '$10' or '100 messages').
|
|
secondary_text:
|
|
type: string
|
|
description: Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
|
|
required:
|
|
- primary_text
|
|
description: Display text for showing this item in pricing pages.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Maximum rollover units. Null for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
description: Rollover configuration for unused units. If set, unused included
|
|
units roll over to the next period.
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
description: Feature configurations included in this plan. Each item defines
|
|
included units, pricing, and reset behavior for a feature.
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: Unit of time for the trial duration ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
description: Whether a payment method is required to start the trial. If true,
|
|
customer will be charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
description: Free trial configuration. If set, new customers can try this plan
|
|
before being charged.
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp (ms) when the plan was created.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: Environment this plan belongs to ('sandbox' or 'live').
|
|
archived:
|
|
type: boolean
|
|
description: Whether the plan is archived. Archived plans cannot be attached to
|
|
new customers.
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: If this is a variant, the ID of the base plan it was created from.
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
description: A plan defines a set of features, pricing, and entitlements that
|
|
can be attached to customers.
|
|
examples:
|
|
- id: pro
|
|
name: Pro Plan
|
|
description: null
|
|
group: null
|
|
version: 1
|
|
addOn: false
|
|
autoEnable: false
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
display:
|
|
primaryText: $10
|
|
secondaryText: per month
|
|
items:
|
|
- featureId: messages
|
|
included: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
price:
|
|
amount: 0.5
|
|
interval: month
|
|
billingUnits: 100
|
|
billingMethod: usage_based
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: 100 messages
|
|
secondaryText: then $0.5 per 100 messages
|
|
- featureId: users
|
|
included: 0
|
|
unlimited: false
|
|
reset: null
|
|
price:
|
|
amount: 10
|
|
interval: month
|
|
billingUnits: 1
|
|
billingMethod: prepaid
|
|
maxPurchase: null
|
|
display:
|
|
primaryText: $10 per Users
|
|
createdAt: 1771513979217
|
|
env: sandbox
|
|
archived: false
|
|
baseVariantId: null
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/plans.delete:
|
|
post:
|
|
operationId: deletePlan
|
|
summary: Delete a plan
|
|
description: >-
|
|
Deletes a plan by its ID.
|
|
|
|
|
|
Use this to permanently remove a plan. Plans with active customers
|
|
cannot be deleted - archive them instead.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete a plan
|
|
|
|
const response = await client.plans.delete({ planId: "unused_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete all versions of a plan
|
|
|
|
const response = await client.plans.delete({ planId: "legacy_plan",
|
|
allVersions: true });
|
|
|
|
```
|
|
|
|
|
|
@param planId - The ID of the plan to delete.
|
|
|
|
@param allVersions - If true, deletes all versions of the plan.
|
|
Otherwise, only deletes the latest version. (optional)
|
|
|
|
|
|
@returns A success flag indicating the plan was deleted.
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
minLength: 1
|
|
description: The ID of the plan to delete.
|
|
all_versions:
|
|
type: boolean
|
|
default: false
|
|
description: If true, deletes all versions of the plan. Otherwise, only deletes
|
|
the latest version.
|
|
required:
|
|
- plan_id
|
|
title: DeletePlanParams
|
|
examples:
|
|
- plan_id: unused_plan
|
|
- plan_id: legacy_plan
|
|
all_versions: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/features.create:
|
|
post:
|
|
operationId: createFeature
|
|
description: >-
|
|
Creates a new feature.
|
|
|
|
|
|
Use this to programmatically create features for metering usage,
|
|
managing access, or building credit systems.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a metered feature for API calls
|
|
|
|
const response = await client.features.create({
|
|
featureId: "api-calls",
|
|
name: "API Calls",
|
|
type: "metered",
|
|
consumable: true,
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a boolean feature for a premium feature flag
|
|
|
|
const response = await client.features.create({ featureId:
|
|
"advanced-analytics", name: "Advanced Analytics", type: "boolean" });
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the feature.
|
|
|
|
@param type - The type of the feature. 'single_use' features are
|
|
consumed, like API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects. 'credit_system'
|
|
features are schemas that unify multiple 'single_use' features into a
|
|
single credit system.
|
|
|
|
@param consumable - Whether this feature is consumable. A consumable
|
|
feature is one that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable only for
|
|
'metered' features. (optional)
|
|
|
|
@param display - Singular and plural display names for the feature in
|
|
your user interface. (optional)
|
|
|
|
@param creditSchema - A schema that maps 'single_use' feature IDs to
|
|
credit costs. Applicable only for 'credit_system' features. (optional)
|
|
|
|
@param featureId - The ID of the feature to create.
|
|
|
|
|
|
@returns The created feature object.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: The type of the feature. 'single_use' features are consumed, like
|
|
API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects.
|
|
'credit_system' features are schemas that unify multiple
|
|
'single_use' features into a single credit system.
|
|
consumable:
|
|
type: boolean
|
|
description: Whether this feature is consumable. A consumable feature is one
|
|
that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable
|
|
only for 'metered' features.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
plural:
|
|
type: string
|
|
required:
|
|
- singular
|
|
- plural
|
|
description: Singular and plural display names for the feature in your user
|
|
interface.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: A schema that maps 'single_use' feature IDs to credit costs.
|
|
Applicable only for 'credit_system' features.
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to create.
|
|
required:
|
|
- name
|
|
- type
|
|
- feature_id
|
|
title: CreateFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
- feature_id: credits
|
|
name: Credits
|
|
type: credit_system
|
|
consumable: true
|
|
credit_schema:
|
|
- metered_feature_id: api-calls
|
|
credit_cost: 1
|
|
- metered_feature_id: image-generations
|
|
credit_cost: 10
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools."
|
|
consumable:
|
|
type: boolean
|
|
description: "For metered features: true if usage resets periodically (API
|
|
calls, credits), false if allocated persistently (seats,
|
|
storage)."
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Event names that trigger this feature's balance. Allows multiple
|
|
features to respond to a single event.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: ID of the metered feature that draws from this credit system.
|
|
credit_cost:
|
|
type: number
|
|
description: Credits consumed per unit of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: "For credit_system features: maps metered features to their credit
|
|
costs."
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/features.get:
|
|
post:
|
|
operationId: getFeature
|
|
description: |-
|
|
Retrieves a single feature by its ID.
|
|
|
|
Use this when you need to fetch the details of a specific feature.
|
|
|
|
@example
|
|
```typescript
|
|
// Get a feature by ID
|
|
const response = await client.features.get({ featureId: "api-calls" });
|
|
```
|
|
|
|
@param featureId - The ID of the feature.
|
|
|
|
@returns The feature object with its full configuration.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
required:
|
|
- feature_id
|
|
title: GetFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools."
|
|
consumable:
|
|
type: boolean
|
|
description: "For metered features: true if usage resets periodically (API
|
|
calls, credits), false if allocated persistently (seats,
|
|
storage)."
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Event names that trigger this feature's balance. Allows multiple
|
|
features to respond to a single event.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: ID of the metered feature that draws from this credit system.
|
|
credit_cost:
|
|
type: number
|
|
description: Credits consumed per unit of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: "For credit_system features: maps metered features to their credit
|
|
costs."
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/features.list:
|
|
post:
|
|
operationId: listFeatures
|
|
description: >-
|
|
Lists all features in the current environment.
|
|
|
|
|
|
Use this to retrieve all features configured for your organization to
|
|
display in dashboards or for feature management.
|
|
|
|
|
|
@returns A list of all features with their configuration and metadata.
|
|
tags:
|
|
- features
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified
|
|
credit pools."
|
|
consumable:
|
|
type: boolean
|
|
description: "For metered features: true if usage resets periodically (API
|
|
calls, credits), false if allocated persistently
|
|
(seats, storage)."
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Event names that trigger this feature's balance. Allows multiple
|
|
features to respond to a single event.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: ID of the metered feature that draws from this credit system.
|
|
credit_cost:
|
|
type: number
|
|
description: Credits consumed per unit of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: "For credit_system features: maps metered features to their credit
|
|
costs."
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
required:
|
|
- list
|
|
examples:
|
|
- list:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
- id: credits
|
|
name: Credits
|
|
type: credit_system
|
|
consumable: true
|
|
archived: false
|
|
credit_schema:
|
|
- metered_feature_id: api-calls
|
|
credit_cost: 1
|
|
- metered_feature_id: image-generations
|
|
credit_cost: 10
|
|
display:
|
|
singular: credit
|
|
plural: credits
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/features.update:
|
|
post:
|
|
operationId: updateFeature
|
|
description: >-
|
|
Updates an existing feature.
|
|
|
|
|
|
Use this to modify feature properties like name, display settings, or to
|
|
archive a feature.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Update a feature's display name
|
|
|
|
const response = await client.features.update({ featureId: "api-calls",
|
|
name: "API Requests", display: {"singular":"API request","plural":"API
|
|
requests"} });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Archive a feature
|
|
|
|
const response = await client.features.update({ featureId:
|
|
"deprecated-feature", archived: true });
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the feature. (optional)
|
|
|
|
@param type - The type of the feature. 'single_use' features are
|
|
consumed, like API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects. 'credit_system'
|
|
features are schemas that unify multiple 'single_use' features into a
|
|
single credit system. (optional)
|
|
|
|
@param consumable - Whether this feature is consumable. A consumable
|
|
feature is one that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable only for
|
|
'metered' features. (optional)
|
|
|
|
@param display - Singular and plural display names for the feature in
|
|
your user interface. (optional)
|
|
|
|
@param creditSchema - A schema that maps 'single_use' feature IDs to
|
|
credit costs. Applicable only for 'credit_system' features. (optional)
|
|
|
|
@param archived - Whether the feature is archived. Archived features are
|
|
hidden from the dashboard. (optional)
|
|
|
|
@param featureId - The ID of the feature to update.
|
|
|
|
@param newFeatureId - The new ID of the feature. Feature ID can only be
|
|
updated if it's not being used by any customers. (optional)
|
|
|
|
|
|
@returns The updated feature object.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
minLength: 1
|
|
description: The name of the feature.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: The type of the feature. 'single_use' features are consumed, like
|
|
API calls, tokens, or messages. 'continuous_use' features
|
|
are allocated, like seats, workspaces, or projects.
|
|
'credit_system' features are schemas that unify multiple
|
|
'single_use' features into a single credit system.
|
|
consumable:
|
|
type: boolean
|
|
description: Whether this feature is consumable. A consumable feature is one
|
|
that periodically resets and is consumed rather than
|
|
allocated (like credits, API requests, etc.). Applicable
|
|
only for 'metered' features.
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
type: string
|
|
plural:
|
|
type: string
|
|
required:
|
|
- singular
|
|
- plural
|
|
description: Singular and plural display names for the feature in your user
|
|
interface.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: A schema that maps 'single_use' feature IDs to credit costs.
|
|
Applicable only for 'credit_system' features.
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived. Archived features are hidden from
|
|
the dashboard.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to update.
|
|
new_feature_id:
|
|
type: string
|
|
description: The new ID of the feature. Feature ID can only be updated if it's
|
|
not being used by any customers.
|
|
required:
|
|
- feature_id
|
|
title: UpdateFeatureParams
|
|
examples:
|
|
- feature_id: api-calls
|
|
name: API Requests
|
|
display:
|
|
singular: API request
|
|
plural: API requests
|
|
- feature_id: old-feature
|
|
archived: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this feature, used in /check and /track
|
|
calls.
|
|
name:
|
|
type: string
|
|
description: Human-readable name displayed in the dashboard and billing UI.
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
description: "Feature type: 'boolean' for on/off access, 'metered' for
|
|
usage-tracked features, 'credit_system' for unified credit
|
|
pools."
|
|
consumable:
|
|
type: boolean
|
|
description: "For metered features: true if usage resets periodically (API
|
|
calls, credits), false if allocated persistently (seats,
|
|
storage)."
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Event names that trigger this feature's balance. Allows multiple
|
|
features to respond to a single event.
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
description: ID of the metered feature that draws from this credit system.
|
|
credit_cost:
|
|
type: number
|
|
description: Credits consumed per unit of the metered feature.
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
description: "For credit_system features: maps metered features to their credit
|
|
costs."
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Singular form for UI display (e.g., 'API call', 'seat').
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Plural form for UI display (e.g., 'API calls', 'seats').
|
|
description: Display names for the feature in billing UI and customer-facing
|
|
components.
|
|
archived:
|
|
type: boolean
|
|
description: Whether the feature is archived and hidden from the dashboard.
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- consumable
|
|
- archived
|
|
examples:
|
|
- id: api-calls
|
|
name: API Calls
|
|
type: metered
|
|
consumable: true
|
|
archived: false
|
|
display:
|
|
singular: API call
|
|
plural: API calls
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/features.delete:
|
|
post:
|
|
operationId: deleteFeature
|
|
description: >-
|
|
Deletes a feature by its ID.
|
|
|
|
|
|
Use this to permanently remove a feature. Note: features that are used
|
|
in products cannot be deleted - archive them instead.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete an unused feature
|
|
|
|
const response = await client.features.delete({ featureId: "old-feature"
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param featureId - The ID of the feature to delete.
|
|
|
|
|
|
@returns A success flag indicating the feature was deleted.
|
|
tags:
|
|
- features
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to delete.
|
|
required:
|
|
- feature_id
|
|
title: DeleteFeatureParams
|
|
examples:
|
|
- feature_id: old-feature
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
examples:
|
|
- success: true
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.attach:
|
|
post:
|
|
operationId: billingAttach
|
|
description: >-
|
|
Attaches a plan to a customer. Handles new subscriptions, upgrades and
|
|
downgrades.
|
|
|
|
|
|
Use this endpoint to subscribe a customer to a plan, upgrade/downgrade
|
|
between plans, or add an add-on product.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach a plan to a customer
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach with a free trial
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan", freeTrial:
|
|
{"durationLength":14,"durationType":"day"} });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Attach with custom pricing
|
|
|
|
const response = await client.billing.attach({ customerId: "cus_123",
|
|
planId: "pro_plan", customize:
|
|
{"price":{"amount":4900,"interval":"month"}} });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan.
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param freeTrial - Override the plan's default free trial. Pass an
|
|
object to set a custom trial, or null to remove the trial entirely.
|
|
(optional)
|
|
|
|
@param customize - Customize the plan to attach. Can either override the
|
|
price of the plan, the items in the plan, or both. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param billingBehavior - How to handle billing when updating an existing
|
|
subscription. 'prorate_immediately' charges/credits prorated amounts
|
|
now, 'next_cycle_only' skips creating any charges and applies the change
|
|
at the next billing cycle. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param successUrl - URL to redirect to after successful checkout.
|
|
(optional)
|
|
|
|
@param newBillingSubscription - Only applicable when the customer has an
|
|
existing Stripe subscription. If true, creates a new separate
|
|
subscription instead of merging into the existing one. (optional)
|
|
|
|
@param planSchedule - When the plan change should take effect.
|
|
'immediate' applies now, 'end_of_cycle' schedules for the end of the
|
|
current billing cycle. By default, upgrades are immediate and downgrades
|
|
are scheduled. (optional)
|
|
|
|
|
|
@returns A billing response with customer ID, invoice details, and
|
|
payment URL (if checkout required).
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
adjustable:
|
|
type: boolean
|
|
required:
|
|
- feature_id
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Customize the plan to attach. Can either override the price of the
|
|
plan, the items in the plan, or both.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
billing_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- next_cycle_only
|
|
description: How to handle billing when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'next_cycle_only' skips creating any charges and applies the
|
|
change at the next billing cycle.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
required:
|
|
- reward_id
|
|
- type: object
|
|
properties:
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
required:
|
|
- promotion_code
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
plan_schedule:
|
|
enum:
|
|
- immediate
|
|
- end_of_cycle
|
|
description: When the plan change should take effect. 'immediate' applies now,
|
|
'end_of_cycle' schedules for the end of the current billing
|
|
cycle. By default, upgrades are immediate and downgrades are
|
|
scheduled.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: AttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if the plan was attached to an entity.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
description: Details about any action required to complete the payment. Present
|
|
when the payment could not be processed automatically.
|
|
required:
|
|
- customer_id
|
|
- payment_url
|
|
examples:
|
|
- customer_id: cus_123
|
|
payment_url: https://checkout.stripe.com/...
|
|
x-speakeasy-name-override: attach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.preview_attach:
|
|
post:
|
|
operationId: previewAttach
|
|
description: >-
|
|
Previews the billing changes that would occur when attaching a plan,
|
|
without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers what they will be charged before
|
|
confirming a subscription change.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Preview attaching a plan
|
|
|
|
const response = await client.billing.previewAttach({ customerId:
|
|
"cus_123", planId: "pro_plan" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param planId - The ID of the plan.
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param freeTrial - Override the plan's default free trial. Pass an
|
|
object to set a custom trial, or null to remove the trial entirely.
|
|
(optional)
|
|
|
|
@param customize - Customize the plan to attach. Can either override the
|
|
price of the plan, the items in the plan, or both. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param billingBehavior - How to handle billing when updating an existing
|
|
subscription. 'prorate_immediately' charges/credits prorated amounts
|
|
now, 'next_cycle_only' skips creating any charges and applies the change
|
|
at the next billing cycle. (optional)
|
|
|
|
@param discounts - List of discounts to apply. Each discount can be an
|
|
Autumn reward ID, Stripe coupon ID, or Stripe promotion code. (optional)
|
|
|
|
@param successUrl - URL to redirect to after successful checkout.
|
|
(optional)
|
|
|
|
@param newBillingSubscription - Only applicable when the customer has an
|
|
existing Stripe subscription. If true, creates a new separate
|
|
subscription instead of merging into the existing one. (optional)
|
|
|
|
@param planSchedule - When the plan change should take effect.
|
|
'immediate' applies now, 'end_of_cycle' schedules for the end of the
|
|
current billing cycle. By default, upgrades are immediate and downgrades
|
|
are scheduled. (optional)
|
|
|
|
|
|
@returns A preview response with line items, totals, and effective dates
|
|
for the proposed changes.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
adjustable:
|
|
type: boolean
|
|
required:
|
|
- feature_id
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Customize the plan to attach. Can either override the price of the
|
|
plan, the items in the plan, or both.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
billing_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- next_cycle_only
|
|
description: How to handle billing when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'next_cycle_only' skips creating any charges and applies the
|
|
change at the next billing cycle.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
reward_id:
|
|
type: string
|
|
description: The ID of the reward to apply as a discount.
|
|
required:
|
|
- reward_id
|
|
- type: object
|
|
properties:
|
|
promotion_code:
|
|
type: string
|
|
description: The promotion code to apply as a discount.
|
|
required:
|
|
- promotion_code
|
|
description: A discount to apply. Can be either a reward ID or a promotion code.
|
|
description: List of discounts to apply. Each discount can be an Autumn reward
|
|
ID, Stripe coupon ID, or Stripe promotion code.
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful checkout.
|
|
new_billing_subscription:
|
|
type: boolean
|
|
description: Only applicable when the customer has an existing Stripe
|
|
subscription. If true, creates a new separate subscription
|
|
instead of merging into the existing one.
|
|
plan_schedule:
|
|
enum:
|
|
- immediate
|
|
- end_of_cycle
|
|
description: When the plan change should take effect. 'immediate' applies now,
|
|
'end_of_cycle' schedules for the end of the current billing
|
|
cycle. By default, upgrades are immediate and downgrades are
|
|
scheduled.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: PreviewAttachParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: The title of the line item.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
amount:
|
|
type: number
|
|
description: The amount in cents for this line item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amountOff:
|
|
type: number
|
|
percentOff:
|
|
type: number
|
|
stripeCouponId:
|
|
type: string
|
|
couponName:
|
|
type: string
|
|
required:
|
|
- amountOff
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
required:
|
|
- title
|
|
- description
|
|
- amount
|
|
description: List of line items for the current billing period.
|
|
total:
|
|
type: number
|
|
description: The total amount in cents for the current billing period.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
next_cycle:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
total:
|
|
type: number
|
|
description: The total amount in cents for the next cycle.
|
|
required:
|
|
- starts_at
|
|
- total
|
|
description: Preview of the next billing cycle, if applicable. This shows what
|
|
the customer will be charged in subsequent cycles.
|
|
required:
|
|
- customer_id
|
|
- line_items
|
|
- total
|
|
- currency
|
|
examples:
|
|
- customerId: charles
|
|
lineItems:
|
|
- title: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
amount: 20
|
|
discounts: []
|
|
total: 20
|
|
currency: usd
|
|
x-speakeasy-name-override: previewAttach
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.update:
|
|
post:
|
|
operationId: billingUpdate
|
|
description: >-
|
|
Updates an existing subscription. Use to modify feature quantities,
|
|
cancel, or change plan configuration.
|
|
|
|
|
|
Use this endpoint to update prepaid quantities, cancel a subscription
|
|
(immediately or at end of cycle), or modify subscription settings.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Update prepaid feature quantity
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", featureQuantities:
|
|
[{"featureId":"seats","quantity":10}] });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Cancel a subscription at end of billing cycle
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", cancelAction: "cancel_end_of_cycle" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Uncancel a subscription at the end of the billing cycle
|
|
|
|
const response = await client.billing.update({ customerId: "cus_123",
|
|
planId: "pro_plan", cancelAction: "uncancel" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param freeTrial - Override the plan's default free trial. Pass an
|
|
object to set a custom trial, or null to remove the trial entirely.
|
|
(optional)
|
|
|
|
@param customize - Customize the plan to attach. Can either override the
|
|
price of the plan, the items in the plan, or both. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param billingBehavior - How to handle billing when updating an existing
|
|
subscription. 'prorate_immediately' charges/credits prorated amounts
|
|
now, 'next_cycle_only' skips creating any charges and applies the change
|
|
at the next billing cycle. (optional)
|
|
|
|
@param cancelAction - Action to perform for cancellation.
|
|
'cancel_immediately' cancels now with prorated refund,
|
|
'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a
|
|
pending cancellation. (optional)
|
|
|
|
|
|
@returns A billing response with customer ID, invoice details, and
|
|
payment URL (if next action is required).
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
adjustable:
|
|
type: boolean
|
|
required:
|
|
- feature_id
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Customize the plan to attach. Can either override the price of the
|
|
plan, the items in the plan, or both.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
billing_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- next_cycle_only
|
|
description: How to handle billing when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'next_cycle_only' skips creating any charges and applies the
|
|
change at the next billing cycle.
|
|
cancel_action:
|
|
enum:
|
|
- cancel_immediately
|
|
- cancel_end_of_cycle
|
|
- uncancel
|
|
description: Action to perform for cancellation. 'cancel_immediately' cancels
|
|
now with prorated refund, 'cancel_end_of_cycle' cancels at
|
|
period end, 'uncancel' reverses a pending cancellation.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: UpdateSubscriptionParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 10
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if the plan was attached to an entity.
|
|
invoice:
|
|
type: object
|
|
properties:
|
|
status:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The status of the invoice (e.g., 'paid', 'open', 'draft').
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID.
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice in cents.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the hosted invoice page where the customer can view and pay
|
|
the invoice.
|
|
required:
|
|
- status
|
|
- stripe_id
|
|
- total
|
|
- currency
|
|
- hosted_invoice_url
|
|
description: Invoice details if an invoice was created. Only present when a
|
|
charge was made.
|
|
payment_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to redirect the customer to complete payment. Null if no
|
|
payment action is required.
|
|
required_action:
|
|
type: object
|
|
properties:
|
|
code:
|
|
enum:
|
|
- 3ds_required
|
|
- payment_method_required
|
|
- payment_failed
|
|
description: The type of action required to complete the payment.
|
|
reason:
|
|
type: string
|
|
description: A human-readable explanation of why this action is required.
|
|
required:
|
|
- code
|
|
- reason
|
|
description: Details about any action required to complete the payment. Present
|
|
when the payment could not be processed automatically.
|
|
required:
|
|
- customer_id
|
|
- payment_url
|
|
examples:
|
|
- customer_id: cus_123
|
|
invoice:
|
|
status: paid
|
|
stripe_id: in_1234
|
|
total: 1500
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/...
|
|
payment_url: null
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.preview_update:
|
|
post:
|
|
operationId: previewUpdate
|
|
description: >-
|
|
Previews the billing changes that would occur when updating a
|
|
subscription, without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers prorated charges or refunds before
|
|
confirming subscription modifications.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Preview updating seat quantity
|
|
|
|
const response = await client.billing.previewUpdate({ customerId:
|
|
"cus_123", planId: "pro_plan", featureQuantities:
|
|
[{"featureId":"seats","quantity":15}] });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to attach the plan to.
|
|
|
|
@param entityId - The ID of the entity to attach the plan to. (optional)
|
|
|
|
@param featureQuantities - If this plan contains prepaid features, use
|
|
this field to specify the quantity of each prepaid feature. This
|
|
quantity includes the included amount and billing units defined when
|
|
setting up the plan. (optional)
|
|
|
|
@param version - The version of the plan to attach. (optional)
|
|
|
|
@param freeTrial - Override the plan's default free trial. Pass an
|
|
object to set a custom trial, or null to remove the trial entirely.
|
|
(optional)
|
|
|
|
@param customize - Customize the plan to attach. Can either override the
|
|
price of the plan, the items in the plan, or both. (optional)
|
|
|
|
@param invoiceMode - Invoice mode creates a draft or open invoice and
|
|
sends it to the customer, instead of charging their card immediately.
|
|
This uses Stripe's send_invoice collection method. (optional)
|
|
|
|
@param billingBehavior - How to handle billing when updating an existing
|
|
subscription. 'prorate_immediately' charges/credits prorated amounts
|
|
now, 'next_cycle_only' skips creating any charges and applies the change
|
|
at the next billing cycle. (optional)
|
|
|
|
@param cancelAction - Action to perform for cancellation.
|
|
'cancel_immediately' cancels now with prorated refund,
|
|
'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a
|
|
pending cancellation. (optional)
|
|
|
|
|
|
@returns A preview response with line items showing prorated charges or
|
|
credits for the proposed changes.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
quantity:
|
|
type: number
|
|
minimum: 0
|
|
adjustable:
|
|
type: boolean
|
|
required:
|
|
- feature_id
|
|
description: If this plan contains prepaid features, use this field to specify
|
|
the quantity of each prepaid feature. This quantity includes
|
|
the included amount and billing units defined when setting
|
|
up the plan.
|
|
version:
|
|
type: number
|
|
description: The version of the plan to attach.
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
description: Number of duration_type periods the trial lasts.
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
description: Unit of time for the trial ('day', 'month', 'year').
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
description: If true, payment method required to start trial. Customer is
|
|
charged after trial ends.
|
|
required:
|
|
- duration_length
|
|
- type: "null"
|
|
description: Override the plan's default free trial. Pass an object to set a
|
|
custom trial, or null to remove the trial entirely.
|
|
customize:
|
|
type: object
|
|
properties:
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Base price amount for the plan.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval (e.g. 'month', 'year').
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to configure.
|
|
included:
|
|
type: number
|
|
description: Number of free units included. Balance resets to this each interval
|
|
for consumable features.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, customer has unlimited access to this feature.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Interval at which balance resets (e.g. 'month', 'year'). For
|
|
consumable features only.
|
|
interval_count:
|
|
type: number
|
|
description: Number of intervals between resets. Defaults to 1.
|
|
required:
|
|
- interval
|
|
description: Reset configuration for consumable features. Omit for
|
|
non-consumable features like seats.
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
description: Price per billing_units after included usage. Either 'amount' or
|
|
'tiers' is required.
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
description: Tiered pricing. Each tier's 'to' does NOT include included amount.
|
|
Either 'amount' or 'tiers' is required.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Billing interval. For consumable features, should match
|
|
reset.interval.
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
description: Number of intervals per billing cycle. Defaults to 1.
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
description: Units per price increment. Usage is rounded UP when billed (e.g.
|
|
billing_units=100 means 101 rounds to 200).
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
description: "'prepaid' for upfront payment (seats), 'usage_based' for
|
|
pay-as-you-go."
|
|
max_purchase:
|
|
type: number
|
|
description: Max units purchasable beyond included. E.g. included=100,
|
|
max_purchase=300 allows 400 total.
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
description: Pricing for usage beyond included units. Omit for free features.
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
description: Billing behavior when quantity increases mid-cycle.
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
description: Credit behavior when quantity decreases mid-cycle.
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
description: Proration settings for prepaid features. Controls mid-cycle
|
|
quantity change billing.
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
description: Max rollover units. Omit for unlimited rollover.
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
description: When rolled over units expire.
|
|
expiry_duration_length:
|
|
type: number
|
|
description: Number of periods before expiry.
|
|
required:
|
|
- expiry_duration_type
|
|
description: Rollover config for unused units. If set, unused included units
|
|
carry over.
|
|
required:
|
|
- feature_id
|
|
description: Customize the plan to attach. Can either override the price of the
|
|
plan, the items in the plan, or both.
|
|
invoice_mode:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: When true, creates an invoice and sends it to the customer instead
|
|
of charging their card immediately. Uses Stripe's
|
|
send_invoice collection method.
|
|
enable_plan_immediately:
|
|
type: boolean
|
|
default: false
|
|
description: If true, enables the plan immediately even though the invoice is
|
|
not paid yet.
|
|
finalize:
|
|
type: boolean
|
|
default: true
|
|
description: If true, finalizes the invoice so it can be sent to the customer.
|
|
If false, keeps it as a draft for manual review.
|
|
required:
|
|
- enabled
|
|
description: Invoice mode creates a draft or open invoice and sends it to the
|
|
customer, instead of charging their card immediately. This
|
|
uses Stripe's send_invoice collection method.
|
|
billing_behavior:
|
|
enum:
|
|
- prorate_immediately
|
|
- next_cycle_only
|
|
description: How to handle billing when updating an existing subscription.
|
|
'prorate_immediately' charges/credits prorated amounts now,
|
|
'next_cycle_only' skips creating any charges and applies the
|
|
change at the next billing cycle.
|
|
cancel_action:
|
|
enum:
|
|
- cancel_immediately
|
|
- cancel_end_of_cycle
|
|
- uncancel
|
|
description: Action to perform for cancellation. 'cancel_immediately' cancels
|
|
now with prorated refund, 'cancel_end_of_cycle' cancels at
|
|
period end, 'uncancel' reverses a pending cancellation.
|
|
required:
|
|
- customer_id
|
|
- plan_id
|
|
title: PreviewUpdateParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 15
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
line_items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: The title of the line item.
|
|
description:
|
|
type: string
|
|
description: A detailed description of the line item.
|
|
amount:
|
|
type: number
|
|
description: The amount in cents for this line item.
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
amountOff:
|
|
type: number
|
|
percentOff:
|
|
type: number
|
|
stripeCouponId:
|
|
type: string
|
|
couponName:
|
|
type: string
|
|
required:
|
|
- amountOff
|
|
default: []
|
|
description: List of discounts applied to this line item.
|
|
required:
|
|
- title
|
|
- description
|
|
- amount
|
|
description: List of line items for the current billing period.
|
|
total:
|
|
type: number
|
|
description: The total amount in cents for the current billing period.
|
|
currency:
|
|
type: string
|
|
description: The three-letter ISO currency code (e.g., 'usd').
|
|
next_cycle:
|
|
type: object
|
|
properties:
|
|
starts_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the next billing cycle starts.
|
|
total:
|
|
type: number
|
|
description: The total amount in cents for the next cycle.
|
|
required:
|
|
- starts_at
|
|
- total
|
|
description: Preview of the next billing cycle, if applicable. This shows what
|
|
the customer will be charged in subsequent cycles.
|
|
required:
|
|
- customer_id
|
|
- line_items
|
|
- total
|
|
- currency
|
|
examples:
|
|
- customerId: charles
|
|
lineItems:
|
|
- title: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
amount: 20
|
|
discounts: []
|
|
total: 20
|
|
currency: usd
|
|
x-speakeasy-name-override: previewUpdate
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.open_customer_portal:
|
|
post:
|
|
operationId: openCustomerPortal
|
|
description: Create a billing portal session for a customer to manage their
|
|
subscription.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to open the billing portal for.
|
|
configuration_id:
|
|
type: string
|
|
description: Stripe billing portal configuration ID. Create configurations in
|
|
your Stripe dashboard.
|
|
return_url:
|
|
type: string
|
|
description: URL to redirect to when back button is clicked in the billing
|
|
portal
|
|
required:
|
|
- customer_id
|
|
title: OpenCustomerPortalParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
return_url: https://useautumn.com
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the billing portal session
|
|
url:
|
|
type: string
|
|
description: URL to the billing portal
|
|
required:
|
|
- customer_id
|
|
- url
|
|
examples:
|
|
- customer_id: cus_123
|
|
url: https://billing.stripe.com/session/...
|
|
x-speakeasy-name-override: openCustomerPortal
|
|
parameters:
|
|
- *a1
|
|
/v1/billing.setup_payment:
|
|
post:
|
|
operationId: setupPayment
|
|
description: Create a payment setup session for a customer to add or update
|
|
their payment method.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer
|
|
success_url:
|
|
type: string
|
|
description: URL to redirect to after successful payment setup. Must start with
|
|
either http:// or https://
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
checkout_session_params:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional parameters for the checkout session
|
|
required:
|
|
- customer_id
|
|
title: SetupPaymentParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
success_url: https://example.com/account/billing
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer
|
|
url:
|
|
type: string
|
|
description: URL to the payment setup page
|
|
required:
|
|
- customer_id
|
|
- url
|
|
examples:
|
|
- customer_id: cus_123
|
|
payment_url: https://checkout.stripe.com/...
|
|
x-speakeasy-name-override: setupPayment
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.create:
|
|
post:
|
|
operationId: createBalance
|
|
description: Create a balance for a customer feature.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
included:
|
|
type: number
|
|
description: The initial balance amount to grant. For metered features, this is
|
|
the number of units the customer can use.
|
|
unlimited:
|
|
type: boolean
|
|
description: If true, the balance has unlimited usage. Cannot be combined with
|
|
'included'.
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: The interval at which the balance resets (e.g., 'month', 'day',
|
|
'year').
|
|
interval_count:
|
|
type: number
|
|
description: "Number of intervals between resets. Defaults to 1 (e.g.,
|
|
interval_count: 2 with interval: 'month' resets every 2
|
|
months)."
|
|
required:
|
|
- interval
|
|
description: Reset configuration for the balance. If not provided, the balance
|
|
is a one-time grant that never resets.
|
|
expires_at:
|
|
type: number
|
|
description: Unix timestamp (milliseconds) when the balance expires. Mutually
|
|
exclusive with reset.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CreateBalanceParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
included: 1000
|
|
reset:
|
|
interval: month
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.update:
|
|
post:
|
|
operationId: updateBalance
|
|
description: Update a customer balance.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
remaining:
|
|
type: number
|
|
description: Set the remaining balance to this exact value. Cannot be combined
|
|
with add_to_balance.
|
|
add_to_balance:
|
|
type: number
|
|
description: Add this amount to the current balance. Use negative values to
|
|
subtract. Cannot be combined with current_balance.
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
description: Target a specific balance by its reset interval. Use when the
|
|
customer has multiple balances for the same feature with
|
|
different reset intervals.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: UpdateBalanceParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
remaining: 5
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.check:
|
|
post:
|
|
operationId: check
|
|
description: >-
|
|
Checks whether a customer currently has enough balance to use a feature.
|
|
|
|
|
|
Use this to gate access before a feature action. Enable sendEvent when
|
|
you want to check and consume balance atomically in one request.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Check access for a feature
|
|
|
|
const response = await client.check({ customerId: "cus_123", featureId:
|
|
"messages" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Check and consume 3 units in one call
|
|
|
|
const response = await client.check({
|
|
customerId: "cus_123",
|
|
featureId: "messages",
|
|
requiredBalance: 3,
|
|
sendEvent: true,
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer.
|
|
|
|
@param featureId - The ID of the feature.
|
|
|
|
@param entityId - The ID of the entity for entity-scoped balances (e.g.,
|
|
per-seat limits). (optional)
|
|
|
|
@param requiredBalance - Minimum balance required for access. Returns
|
|
allowed: false if the customer's balance is below this value. Defaults
|
|
to 1. (optional)
|
|
|
|
@param properties - Additional properties to attach to the usage event
|
|
if send_event is true. (optional)
|
|
|
|
@param sendEvent - If true, atomically records a usage event while
|
|
checking access. The required_balance value is used as the usage amount.
|
|
Combines check + track in one call. (optional)
|
|
|
|
@param withPreview - If true, includes upgrade/upsell information in the
|
|
response when access is denied. Useful for displaying paywalls.
|
|
(optional)
|
|
|
|
|
|
@returns Whether access is allowed, plus the current balance for that
|
|
feature.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
required_balance:
|
|
type: number
|
|
description: "Minimum balance required for access. Returns allowed: false if the
|
|
customer's balance is below this value. Defaults to 1."
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to the usage event if send_event is
|
|
true.
|
|
send_event:
|
|
type: boolean
|
|
description: If true, atomically records a usage event while checking access.
|
|
The required_balance value is used as the usage amount.
|
|
Combines check + track in one call.
|
|
with_preview:
|
|
type: boolean
|
|
description: If true, includes upgrade/upsell information in the response when
|
|
access is denied. Useful for displaying paywalls.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CheckParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
required_balance: 3
|
|
send_event: true
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
allowed:
|
|
type: boolean
|
|
description: Whether the customer is allowed to use the feature. True if they
|
|
have sufficient balance or the feature is
|
|
unlimited/boolean.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer that was checked.
|
|
entity_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The ID of the entity, if an entity-scoped check was performed.
|
|
required_balance:
|
|
type: number
|
|
description: The required balance that was checked against.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The customer's balance for this feature. Null if the customer has
|
|
no balance for this feature.
|
|
preview:
|
|
type: object
|
|
properties:
|
|
scenario:
|
|
enum:
|
|
- usage_limit
|
|
- feature_flag
|
|
description: The reason access was denied. 'usage_limit' means the customer
|
|
exceeded their balance, 'feature_flag' means the
|
|
feature is not included in their plan.
|
|
title:
|
|
type: string
|
|
description: A title suitable for displaying in a paywall or upgrade modal.
|
|
message:
|
|
type: string
|
|
description: A message explaining why access was denied.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature that was checked.
|
|
feature_name:
|
|
type: string
|
|
description: The display name of the feature.
|
|
products:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the product you set when creating the product
|
|
name:
|
|
type: string
|
|
description: The name of the product
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Product group which this product belongs to
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment of the product
|
|
is_add_on:
|
|
type: boolean
|
|
description: Whether the product is an add-on and can be purchased alongside
|
|
other products
|
|
is_default:
|
|
type: boolean
|
|
description: Whether the product is the default product
|
|
archived:
|
|
type: boolean
|
|
description: Whether this product has been archived and is no longer available
|
|
version:
|
|
type: number
|
|
description: The current version of the product
|
|
created_at:
|
|
type: number
|
|
description: The timestamp of when the product was created in milliseconds since
|
|
epoch
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
type:
|
|
anyOf:
|
|
- enum:
|
|
- feature
|
|
- priced_feature
|
|
- price
|
|
- type: "null"
|
|
description: The type of the product item
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID of the product item. If the item is a fixed price,
|
|
should be `null`
|
|
feature_type:
|
|
anyOf:
|
|
- enum:
|
|
- single_use
|
|
- continuous_use
|
|
- boolean
|
|
- static
|
|
- type: "null"
|
|
description: Single use features are used once and then depleted, like API calls
|
|
or credits. Continuous use features are
|
|
those being used on an ongoing-basis, like
|
|
storage or seats.
|
|
included_usage:
|
|
anyOf:
|
|
- anyOf:
|
|
- type: number
|
|
- const: inf
|
|
- type: "null"
|
|
description: The amount of usage included for this feature.
|
|
interval:
|
|
anyOf:
|
|
- enum:
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
- type: "null"
|
|
description: The reset or billing interval of the product item. If null, feature
|
|
will have no reset date, and if there's a
|
|
price, it will be billed one-off.
|
|
interval_count:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The interval count of the product item.
|
|
price:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The price of the product item. Should be `null` if tiered pricing
|
|
is set.
|
|
tiers:
|
|
anyOf:
|
|
- type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
description: The maximum amount of usage for this tier.
|
|
amount:
|
|
type: number
|
|
description: The price of the product item for this tier.
|
|
required:
|
|
- to
|
|
- amount
|
|
- type: "null"
|
|
description: Tiered pricing for the product item. Not applicable for fixed price
|
|
items.
|
|
usage_model:
|
|
anyOf:
|
|
- enum:
|
|
- prepaid
|
|
- pay_per_use
|
|
- type: "null"
|
|
description: Whether the feature should be prepaid upfront or billed for how
|
|
much they use end of billing period.
|
|
billing_units:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: The amount per billing unit (eg. $9 / 250 units)
|
|
reset_usage_when_enabled:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: Whether the usage should be reset when the product is enabled.
|
|
entity_feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The entity feature ID of the product item if applicable.
|
|
display:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
secondary_text:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- primary_text
|
|
- type: "null"
|
|
description: The display of the product item.
|
|
quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer has
|
|
prepaid for.
|
|
next_cycle_quantity:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Used in customer context. Quantity of the feature the customer will
|
|
prepay for in the next cycle.
|
|
config:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
rollover:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
duration:
|
|
enum:
|
|
- month
|
|
- forever
|
|
default: month
|
|
length:
|
|
type: number
|
|
required:
|
|
- max
|
|
- length
|
|
- type: "null"
|
|
on_increase:
|
|
anyOf:
|
|
- enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
- type: "null"
|
|
on_decrease:
|
|
anyOf:
|
|
- enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
- type: "null"
|
|
- type: "null"
|
|
description: Configuration for rollover and proration behavior of the feature.
|
|
description: Product item defining features and pricing within a product
|
|
description: Array of product items that define the product's features and
|
|
pricing
|
|
free_trial:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
duration:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
description: The duration type of the free trial
|
|
length:
|
|
type: number
|
|
description: The length of the duration type specified
|
|
unique_fingerprint:
|
|
type: boolean
|
|
description: Whether the free trial is limited to one per customer fingerprint
|
|
card_required:
|
|
type: boolean
|
|
description: Whether the free trial requires a card. If false, the customer can
|
|
attach the product without going through
|
|
a checkout flow or having a card on
|
|
file.
|
|
trial_available:
|
|
anyOf:
|
|
- type: boolean
|
|
default: true
|
|
- type: "null"
|
|
description: Used in customer context. Whether the free trial is available for
|
|
the customer if they were to attach the
|
|
product.
|
|
required:
|
|
- duration
|
|
- length
|
|
- unique_fingerprint
|
|
- card_required
|
|
- type: "null"
|
|
description: Free trial configuration for this product, if available
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: ID of the base variant this product is derived from
|
|
scenario:
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- new
|
|
- renew
|
|
- upgrade
|
|
- downgrade
|
|
- cancel
|
|
- expired
|
|
- past_due
|
|
description: Scenario for when this product is used in attach flows
|
|
properties:
|
|
type: object
|
|
properties:
|
|
is_free:
|
|
type: boolean
|
|
description: True if the product has no base price or usage prices
|
|
is_one_off:
|
|
type: boolean
|
|
description: True if the product only contains a one-time price
|
|
interval_group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The billing interval group for recurring products (e.g., 'monthly',
|
|
'yearly')
|
|
has_trial:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product includes a free trial
|
|
updateable:
|
|
anyOf:
|
|
- type: boolean
|
|
- type: "null"
|
|
description: True if the product can be updated after creation (only applicable
|
|
if there are prepaid recurring prices)
|
|
required:
|
|
- is_free
|
|
- is_one_off
|
|
required:
|
|
- id
|
|
- name
|
|
- group
|
|
- env
|
|
- is_add_on
|
|
- is_default
|
|
- archived
|
|
- version
|
|
- created_at
|
|
- items
|
|
- free_trial
|
|
- base_variant_id
|
|
description: Products that would grant access to this feature. Use to display
|
|
upgrade options.
|
|
required:
|
|
- scenario
|
|
- title
|
|
- message
|
|
- feature_id
|
|
- feature_name
|
|
- products
|
|
description: Upgrade/upsell information when access is denied. Only present if
|
|
with_preview was true and allowed is false.
|
|
required:
|
|
- allowed
|
|
- customer_id
|
|
- balance
|
|
examples:
|
|
- allowed: true
|
|
customer_id: cus_123
|
|
entity_id: null
|
|
required_balance: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
x-speakeasy-name-override: check
|
|
parameters:
|
|
- *a1
|
|
/v1/balances.track:
|
|
post:
|
|
operationId: track
|
|
description: >-
|
|
Records usage for a customer feature and returns updated balances.
|
|
|
|
|
|
Use this after an action happens to decrement usage, or send a negative
|
|
value to credit balance back.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Track one message event
|
|
|
|
const response = await client.track({ customerId: "cus_123", featureId:
|
|
"messages", value: 1 });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Track an event mapped to multiple features
|
|
|
|
const response = await client.track({ customerId: "cus_123", eventName:
|
|
"ai_chat_request", value: 1 });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer.
|
|
|
|
@param featureId - The ID of the feature to track usage for. Required if
|
|
event_name is not provided. (optional)
|
|
|
|
@param entityId - The ID of the entity for entity-scoped balances (e.g.,
|
|
per-seat limits). (optional)
|
|
|
|
@param eventName - Event name to track usage for. Use instead of
|
|
feature_id when multiple features should be tracked from a single event.
|
|
(optional)
|
|
|
|
@param value - The amount of usage to record. Defaults to 1. Use
|
|
negative values to credit balance (e.g., when removing a seat).
|
|
(optional)
|
|
|
|
@param properties - Additional properties to attach to this usage event.
|
|
(optional)
|
|
|
|
|
|
@returns The usage value recorded, with either a single updated balance
|
|
or a map of updated balances.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to track usage for. Required if event_name is
|
|
not provided.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
event_name:
|
|
type: string
|
|
minLength: 1
|
|
description: Event name to track usage for. Use instead of feature_id when
|
|
multiple features should be tracked from a single event.
|
|
value:
|
|
type: number
|
|
description: The amount of usage to record. Defaults to 1. Use negative values
|
|
to credit balance (e.g., when removing a seat).
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this usage event.
|
|
required:
|
|
- customer_id
|
|
title: TrackParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
value: 1
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer whose usage was tracked.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity, if entity-scoped tracking was performed.
|
|
event_name:
|
|
type: string
|
|
description: The event name that was tracked, if event_name was used instead of
|
|
feature_id.
|
|
value:
|
|
type: number
|
|
description: The amount of usage that was recorded.
|
|
balance:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/Balance"
|
|
- type: "null"
|
|
description: The updated balance for the tracked feature. Null if tracking by
|
|
event_name that affects multiple features.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
description: Map of feature_id to updated balance when tracking by event_name
|
|
affects multiple features.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- customer_id: cus_123
|
|
value: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
x-speakeasy-name-override: track
|
|
parameters:
|
|
- *a1
|
|
/v1/events.list:
|
|
post:
|
|
operationId: listEvents
|
|
description: List usage events for your organization. Filter by customer,
|
|
feature, or time range.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
default: 0
|
|
description: Number of items to skip
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 100
|
|
description: Number of items to return. Default 100, max 1000.
|
|
customer_id:
|
|
type: string
|
|
description: Filter events by customer ID
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Filter by specific feature ID(s)
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: Filter events after this timestamp (epoch milliseconds)
|
|
end:
|
|
type: number
|
|
description: Filter events before this timestamp (epoch milliseconds)
|
|
description: Filter events by time range
|
|
title: EventsListParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
limit: 50
|
|
- feature_id: api_calls
|
|
custom_range:
|
|
start: 1704067200000
|
|
end: 1706745600000
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Event ID (KSUID)
|
|
timestamp:
|
|
type: number
|
|
description: Event timestamp (epoch milliseconds)
|
|
feature_id:
|
|
type: string
|
|
description: ID of the feature that the event belongs to
|
|
customer_id:
|
|
type: string
|
|
description: Customer identifier
|
|
value:
|
|
type: number
|
|
description: Event value/count
|
|
properties:
|
|
type: object
|
|
description: Event properties (JSONB)
|
|
required:
|
|
- id
|
|
- timestamp
|
|
- feature_id
|
|
- customer_id
|
|
- value
|
|
- properties
|
|
description: Array of items for current page
|
|
has_more:
|
|
type: boolean
|
|
description: Whether more results exist after this page
|
|
offset:
|
|
type: number
|
|
description: Current offset position
|
|
limit:
|
|
type: number
|
|
description: Limit passed in the request
|
|
total:
|
|
type: number
|
|
description: Total number of items returned in the current page
|
|
required:
|
|
- list
|
|
- has_more
|
|
- offset
|
|
- limit
|
|
- total
|
|
examples:
|
|
- list:
|
|
- id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg
|
|
timestamp: 1765958215459
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 30
|
|
properties: {}
|
|
- id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM
|
|
timestamp: 1765956512057
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 49
|
|
properties: {}
|
|
total: 2
|
|
has_more: false
|
|
offset: 0
|
|
limit: 100
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- *a1
|
|
/v1/events.aggregate:
|
|
post:
|
|
operationId: aggregateEvents
|
|
description: Aggregate usage events by time period. Returns usage totals grouped
|
|
by feature and optionally by a custom property.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Customer ID to aggregate events for
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Feature ID(s) to aggregate events for
|
|
group_by:
|
|
type: string
|
|
pattern: ^properties\..*
|
|
description: Property to group events by. If provided, each key in the response
|
|
will be an object with distinct groups as the keys
|
|
range:
|
|
enum:
|
|
- 24h
|
|
- 7d
|
|
- 30d
|
|
- 90d
|
|
- last_cycle
|
|
- 1bc
|
|
- 3bc
|
|
description: Time range to aggregate events for. Either range or custom_range
|
|
must be provided
|
|
bin_size:
|
|
enum:
|
|
- day
|
|
- hour
|
|
- month
|
|
default: day
|
|
description: Size of the time bins to aggregate events for. Defaults to hour if
|
|
range is 24h, otherwise day
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
end:
|
|
type: number
|
|
required:
|
|
- start
|
|
- end
|
|
description: Custom time range to aggregate events for. If provided, range must
|
|
not be provided
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: EventsAggregateParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
feature_id: api_calls
|
|
range: 30d
|
|
bin_size: day
|
|
- customer_id: cus_123
|
|
feature_id:
|
|
- api_calls
|
|
- messages
|
|
range: 7d
|
|
group_by: properties.model
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
period:
|
|
type: number
|
|
description: Unix timestamp (epoch ms) for this time period
|
|
values:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: number
|
|
description: "Aggregated values per feature: { [featureId]: number }"
|
|
grouped_values:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: number
|
|
description: "Values broken down by group (only present when group_by is used):
|
|
{ [featureId]: { [groupValue]: number } }"
|
|
required:
|
|
- period
|
|
- values
|
|
description: Array of time periods with aggregated values
|
|
total:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
count:
|
|
type: number
|
|
description: Number of events for this feature
|
|
sum:
|
|
type: number
|
|
description: Sum of event values for this feature
|
|
required:
|
|
- count
|
|
- sum
|
|
description: Total aggregations per feature. Keys are feature IDs, values
|
|
contain count and sum.
|
|
required:
|
|
- list
|
|
- total
|
|
examples:
|
|
- list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
- list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
grouped_values:
|
|
messages:
|
|
api: 5
|
|
web: 5
|
|
sessions:
|
|
api: 2
|
|
web: 1
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
grouped_values:
|
|
messages:
|
|
api: 1
|
|
web: 2
|
|
sessions:
|
|
api: 10
|
|
web: 2
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
x-speakeasy-name-override: aggregate
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.create:
|
|
post:
|
|
operationId: createEntity
|
|
description: >-
|
|
Creates an entity for a customer and feature, then returns the entity
|
|
with balances and subscriptions.
|
|
|
|
|
|
Use entities when usage and access must be scoped to sub-resources (for
|
|
example seats, projects, or workspaces) instead of only the customer.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Create a seat entity
|
|
|
|
const response = await client.entities.create({
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
featureId: "seats",
|
|
name: "Seat 42",
|
|
});
|
|
|
|
```
|
|
|
|
|
|
@param name - The name of the entity (optional)
|
|
|
|
@param featureId - The ID of the feature this entity is associated with
|
|
|
|
@param customerData - Customer attributes used to resolve the customer
|
|
when customer_id is not provided. (optional)
|
|
|
|
@param customerId - The ID of the customer to create the entity for.
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns The created entity object including its current subscriptions,
|
|
purchases, and balances.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this entity is associated with
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
description: Customer attributes used to resolve the customer when customer_id
|
|
is not provided.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- feature_id
|
|
- customer_id
|
|
- entity_id
|
|
title: CreateEntityParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
feature_id: seats
|
|
name: Seat 42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
autumn_id:
|
|
type: string
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.get:
|
|
post:
|
|
operationId: getEntity
|
|
description: >-
|
|
Fetches an entity by its ID.
|
|
|
|
|
|
Use this to read one entity's current state. Pass customerId when you
|
|
want to scope the lookup to a specific customer.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a seat entity
|
|
|
|
const response = await client.entities.get({ entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Fetch a seat entity for a specific customer
|
|
|
|
const response = await client.entities.get({ customerId: "cus_123",
|
|
entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer to create the entity for.
|
|
(optional)
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns The entity object including its current subscriptions,
|
|
purchases, and balances.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: GetEntityParams
|
|
examples:
|
|
- entity_id: seat_42
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
autumn_id:
|
|
type: string
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment (sandbox/live)
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/Balance"
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
description: Invoices for this entity (only included when expand=invoices)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- *a1
|
|
/v1/entities.delete:
|
|
post:
|
|
operationId: deleteEntity
|
|
description: >-
|
|
Deletes an entity by entity ID.
|
|
|
|
|
|
Use this when the underlying resource is removed and you no longer want
|
|
entity-scoped balances or subscriptions tracked for it.
|
|
|
|
|
|
@example
|
|
|
|
```typescript
|
|
|
|
// Delete a seat entity
|
|
|
|
const response = await client.entities.delete({ entityId: "seat_42" });
|
|
|
|
```
|
|
|
|
|
|
@param customerId - The ID of the customer. (optional)
|
|
|
|
@param entityId - The ID of the entity.
|
|
|
|
|
|
@returns A success flag indicating the entity was deleted.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: DeleteEntityParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
examples:
|
|
- success: true
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- *a1
|
|
/v1/referrals.create_code:
|
|
post:
|
|
operationId: createReferralCode
|
|
description: Create or fetch a referral code for a customer in a referral program.
|
|
tags:
|
|
- referrals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer
|
|
program_id:
|
|
type: string
|
|
description: ID of your referral program
|
|
required:
|
|
- customer_id
|
|
- program_id
|
|
title: CreateReferralCodeParams
|
|
examples:
|
|
- customer_id: cus_123
|
|
program_id: prog_123
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: The referral code that can be shared with customers
|
|
customer_id:
|
|
type: string
|
|
description: Your unique identifier for the customer
|
|
created_at:
|
|
type: number
|
|
description: The timestamp of when the referral code was created
|
|
required:
|
|
- code
|
|
- customer_id
|
|
- created_at
|
|
examples:
|
|
- code: <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
|
|
security:
|
|
- secretKey: []
|
|
x-speakeasy-globals:
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|