7477 lines
305 KiB
YAML
7477 lines
305 KiB
YAML
info:
|
|
title: Autumn API
|
|
version: 2.1.0
|
|
servers:
|
|
- url: http://localhost:8080
|
|
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:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
invoices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of plan IDs included in this invoice
|
|
stripe_id:
|
|
type: string
|
|
description: The Stripe invoice ID
|
|
status:
|
|
type: string
|
|
description: The status of the invoice
|
|
total:
|
|
type: number
|
|
description: The total amount of the invoice
|
|
currency:
|
|
type: string
|
|
description: The currency code for the invoice
|
|
created_at:
|
|
type: number
|
|
description: Timestamp when the invoice was created
|
|
hosted_invoice_url:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: URL to the Stripe-hosted invoice page
|
|
required:
|
|
- plan_ids
|
|
- stripe_id
|
|
- status
|
|
- total
|
|
- currency
|
|
- created_at
|
|
entities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
autumn_id:
|
|
type: string
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The unique identifier of the entity
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
customer_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The customer ID this entity belongs to
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The feature ID this entity belongs to
|
|
created_at:
|
|
type: number
|
|
description: Unix timestamp when the entity was created
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment (sandbox/live)
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- env
|
|
trials_used:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan_id:
|
|
type: string
|
|
customer_id:
|
|
type: string
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- plan_id
|
|
- customer_id
|
|
rewards:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
discounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique identifier for this discount
|
|
name:
|
|
type: string
|
|
description: The name of the discount or coupon
|
|
type:
|
|
enum:
|
|
- percentage_discount
|
|
- fixed_discount
|
|
- free_product
|
|
- invoice_credits
|
|
description: The type of reward
|
|
discount_value:
|
|
type: number
|
|
description: The discount value (percentage or fixed amount)
|
|
duration_type:
|
|
enum:
|
|
- one_off
|
|
- months
|
|
- forever
|
|
description: How long the discount lasts
|
|
duration_value:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Number of billing periods the discount applies for repeating
|
|
durations
|
|
currency:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The currency code for fixed amount discounts
|
|
start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount becomes active
|
|
end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the discount expires
|
|
subscription_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The Stripe subscription ID this discount is applied to
|
|
total_discount_amount:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Total amount saved from this discount
|
|
required:
|
|
- id
|
|
- name
|
|
- type
|
|
- discount_value
|
|
- duration_type
|
|
description: Array of active discounts applied to the customer
|
|
required:
|
|
- discounts
|
|
- type: "null"
|
|
referrals:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
program_id:
|
|
type: string
|
|
customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
reward_applied:
|
|
type: boolean
|
|
created_at:
|
|
type: number
|
|
required:
|
|
- program_id
|
|
- customer
|
|
- reward_applied
|
|
- created_at
|
|
payment_method:
|
|
anyOf:
|
|
- {}
|
|
- type: "null"
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- &a2
|
|
id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
Plan:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
group:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
version:
|
|
type: number
|
|
add_on:
|
|
type: boolean
|
|
auto_enable:
|
|
type: boolean
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
secondary_text:
|
|
type: string
|
|
required:
|
|
- primary_text
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
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
|
|
included:
|
|
type: number
|
|
unlimited:
|
|
type: boolean
|
|
reset:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- interval
|
|
- type: "null"
|
|
price:
|
|
anyOf:
|
|
- type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
billing_units:
|
|
type: number
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
required:
|
|
- interval
|
|
- billing_units
|
|
- billing_method
|
|
- max_purchase
|
|
- type: "null"
|
|
display:
|
|
type: object
|
|
properties:
|
|
primary_text:
|
|
type: string
|
|
secondary_text:
|
|
type: string
|
|
required:
|
|
- primary_text
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
type: number
|
|
required:
|
|
- max
|
|
- expiry_duration_type
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
required:
|
|
- feature_id
|
|
- included
|
|
- unlimited
|
|
- reset
|
|
- price
|
|
free_trial:
|
|
type: object
|
|
properties:
|
|
duration_length:
|
|
type: number
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
card_required:
|
|
type: boolean
|
|
required:
|
|
- duration_length
|
|
- duration_type
|
|
- card_required
|
|
created_at:
|
|
type: number
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
archived:
|
|
type: boolean
|
|
base_variant_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
customer_eligibility:
|
|
type: object
|
|
properties:
|
|
trial_available:
|
|
type: boolean
|
|
scenario:
|
|
enum:
|
|
- scheduled
|
|
- active
|
|
- new
|
|
- renew
|
|
- upgrade
|
|
- downgrade
|
|
- cancel
|
|
- expired
|
|
- past_due
|
|
required:
|
|
- scenario
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- group
|
|
- version
|
|
- add_on
|
|
- auto_enable
|
|
- price
|
|
- items
|
|
- created_at
|
|
- env
|
|
- archived
|
|
- base_variant_id
|
|
securitySchemes:
|
|
secretKey:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
paths:
|
|
/v1/customers.get_or_create:
|
|
post:
|
|
operationId: getOrCreateCustomer
|
|
description: >-
|
|
Creates a customer if they do not exist, or returns the existing
|
|
customer by your external customer ID.
|
|
|
|
|
|
Use this as the primary entrypoint before billing operations so the
|
|
customer record is always present and up to date.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
anyOf:
|
|
- $ref: "#/components/schemas/CustomerId"
|
|
- type: "null"
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
create_in_stripe:
|
|
type: boolean
|
|
description: Whether to create the customer in Stripe
|
|
auto_enable_plan_id:
|
|
type: string
|
|
description: The ID of the free plan to auto-enable for the customer
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
expand:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CustomerExpand"
|
|
description: Customer expand options
|
|
required:
|
|
- customer_id
|
|
title: GetOrCreateCustomerParams
|
|
examples:
|
|
- &a1
|
|
customer_id: cus_123
|
|
name: John Doe
|
|
email: john@example.com
|
|
example: *a1
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
example: *a2
|
|
x-speakeasy-name-override: getOrCreate
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.customers.getOrCreate({
|
|
customerId: "cus_123",
|
|
name: "John Doe",
|
|
email: "john@example.com",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.customers.get_or_create(
|
|
customer_id="cus_123",
|
|
name="John Doe",
|
|
email="john@example.com",
|
|
)
|
|
/v1/customers.list:
|
|
post:
|
|
operationId: listCustomers
|
|
description: Lists customers with pagination and optional filters.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
default: 0
|
|
description: Number of items to skip
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 10
|
|
description: Number of items to return. Default 10, max 1000.
|
|
plans:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
versions:
|
|
type: array
|
|
items:
|
|
type: number
|
|
required:
|
|
- id
|
|
description: Filter by plan ID and version. Returns customers with active
|
|
subscriptions to this plan.
|
|
subscription_status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Filter by customer product status. Defaults to active and scheduled
|
|
search:
|
|
type: string
|
|
description: Search customers by id, name, or email
|
|
title: ListCustomersParams
|
|
examples:
|
|
- &a3
|
|
limit: 10
|
|
offset: 0
|
|
example: *a3
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple
|
|
device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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:
|
|
- {}
|
|
- {}
|
|
amount:
|
|
type: number
|
|
required:
|
|
- 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
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
description: Array of items for current page
|
|
has_more:
|
|
type: boolean
|
|
description: Whether more results exist after this page
|
|
offset:
|
|
type: number
|
|
description: Current offset position
|
|
limit:
|
|
type: number
|
|
description: Limit passed in the request
|
|
total:
|
|
type: number
|
|
description: Total number of items returned in the current page
|
|
required:
|
|
- list
|
|
- has_more
|
|
- offset
|
|
- limit
|
|
- total
|
|
examples:
|
|
- &a4
|
|
list:
|
|
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
has_more: false
|
|
offset: 0
|
|
total: 1
|
|
limit: 10
|
|
example: *a4
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.customers.list({});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.customers.list(request={})
|
|
/v1/customers.update:
|
|
post:
|
|
operationId: updateCustomer
|
|
description: Updates an existing customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to update
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Customer's name
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
format: email
|
|
- type: "null"
|
|
description: Customer's email address
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Unique identifier (eg, serial number) to detect duplicate customers
|
|
and prevent free trial abuse
|
|
metadata:
|
|
anyOf:
|
|
- type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
- type: "null"
|
|
description: Additional metadata for the customer
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID if you already have one
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to this customer
|
|
new_customer_id:
|
|
$ref: "#/components/schemas/CustomerId"
|
|
description: New ID for the customer
|
|
required:
|
|
- customer_id
|
|
title: UpdateCustomerParams
|
|
examples:
|
|
- &a5
|
|
customer_id: cus_123
|
|
name: Jane Doe
|
|
email: jane@example.com
|
|
example: *a5
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Your unique identifier for the customer.
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the customer.
|
|
email:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The email address of the customer.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp of customer creation in milliseconds since epoch.
|
|
fingerprint:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: "A unique identifier (eg. serial number) to de-duplicate customers
|
|
across devices or browsers. For example: apple device ID."
|
|
stripe_id:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: Stripe customer ID.
|
|
env:
|
|
enum:
|
|
- sandbox
|
|
- live
|
|
description: The environment this customer was created in.
|
|
metadata:
|
|
type: object
|
|
propertyNames: {}
|
|
additionalProperties: {}
|
|
description: The metadata for the customer.
|
|
send_email_receipts:
|
|
type: boolean
|
|
description: Whether to send email receipts to the customer.
|
|
subscriptions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the subscribed plan.
|
|
auto_enable:
|
|
type: boolean
|
|
description: Whether the plan was automatically enabled for the customer.
|
|
add_on:
|
|
type: boolean
|
|
description: Whether this is an add-on plan rather than a base subscription.
|
|
status:
|
|
enum:
|
|
- active
|
|
- scheduled
|
|
description: Current status of the subscription.
|
|
past_due:
|
|
type: boolean
|
|
description: Whether the subscription has overdue payments.
|
|
canceled_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription was canceled, or null if not
|
|
canceled.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the subscription will expire, or null if no expiry
|
|
set.
|
|
trial_ends_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the trial period ends, or null if not on trial.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the subscription started.
|
|
current_period_start:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Start timestamp of the current billing period.
|
|
current_period_end:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: End timestamp of the current billing period.
|
|
quantity:
|
|
type: number
|
|
description: Number of units of this subscription (for per-seat plans).
|
|
required:
|
|
- plan_id
|
|
- auto_enable
|
|
- add_on
|
|
- status
|
|
- past_due
|
|
- canceled_at
|
|
- expires_at
|
|
- trial_ends_at
|
|
- started_at
|
|
- current_period_start
|
|
- current_period_end
|
|
- quantity
|
|
description: Active and scheduled recurring plans that this customer has
|
|
attached.
|
|
purchases:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
plan:
|
|
$ref: "#/components/schemas/Plan"
|
|
description: The full plan object if expanded.
|
|
plan_id:
|
|
type: string
|
|
description: The unique identifier of the purchased plan.
|
|
expires_at:
|
|
anyOf:
|
|
- type: number
|
|
- type: "null"
|
|
description: Timestamp when the purchase expires, or null for lifetime access.
|
|
started_at:
|
|
type: number
|
|
description: Timestamp when the purchase was made.
|
|
quantity:
|
|
type: number
|
|
description: Number of units purchased.
|
|
required:
|
|
- plan_id
|
|
- expires_at
|
|
- started_at
|
|
- quantity
|
|
description: One-time purchases made by the customer.
|
|
balances:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
description: Feature balances keyed by feature ID, showing usage limits and
|
|
remaining amounts.
|
|
required:
|
|
- id
|
|
- name
|
|
- email
|
|
- created_at
|
|
- fingerprint
|
|
- stripe_id
|
|
- env
|
|
- metadata
|
|
- send_email_receipts
|
|
- subscriptions
|
|
- purchases
|
|
- balances
|
|
examples:
|
|
- &a6
|
|
id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
|
|
name: Patrick
|
|
email: patrick@useautumn.com
|
|
createdAt: 1771409161016
|
|
fingerprint: null
|
|
stripeId: cus_U0BKxpq1mFhuJO
|
|
env: sandbox
|
|
metadata: {}
|
|
sendEmailReceipts: false
|
|
subscriptions:
|
|
- planId: pro_plan
|
|
autoEnable: true
|
|
addOn: false
|
|
status: active
|
|
pastDue: false
|
|
canceledAt: null
|
|
expiresAt: null
|
|
trialEndsAt: null
|
|
startedAt: 1771431921437
|
|
currentPeriodStart: 1771431921437
|
|
currentPeriodEnd: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
featureId: messages
|
|
granted: 100
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
overageAllowed: false
|
|
maxPurchase: null
|
|
nextResetAt: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
planId: pro_plan
|
|
includedGrant: 100
|
|
prepaidGrant: 0
|
|
remaining: 0
|
|
usage: 100
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resetsAt: 1773851121437
|
|
price: null
|
|
expiresAt: null
|
|
example: *a6
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.customers.update({
|
|
customerId: "cus_123",
|
|
name: "Jane Doe",
|
|
email: "jane@example.com",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.customers.update(
|
|
customer_id="cus_123",
|
|
name="Jane Doe",
|
|
email="jane@example.com",
|
|
)
|
|
/v1/customers.delete:
|
|
post:
|
|
operationId: deleteCustomer
|
|
description: Deletes a customer by ID.
|
|
tags:
|
|
- customers
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
title: CustomerId
|
|
description: ID of the customer to delete
|
|
delete_in_stripe:
|
|
type: boolean
|
|
default: false
|
|
description: Whether to also delete the customer in Stripe
|
|
required:
|
|
- customer_id
|
|
title: DeleteCustomerParams
|
|
examples:
|
|
- &a7
|
|
customer_id: cus_123
|
|
delete_in_stripe: false
|
|
example: *a7
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.customers.delete({
|
|
customerId: "cus_123",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.customers.delete(
|
|
customer_id="cus_123",
|
|
delete_in_stripe=False,
|
|
)
|
|
/v1/plans.list:
|
|
post:
|
|
operationId: listPlans
|
|
summary: List all plans
|
|
tags:
|
|
- plans
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
entity_id:
|
|
type: string
|
|
include_archived:
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Plan"
|
|
required:
|
|
- list
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.plans.list();
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.plans.list()
|
|
/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.
|
|
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
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
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
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
included:
|
|
type: number
|
|
unlimited:
|
|
type: boolean
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- interval
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
type: number
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
type: number
|
|
required:
|
|
- expiry_duration_type
|
|
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:
|
|
- &a8
|
|
customer_id: cus_123
|
|
plan_id: pro_plan
|
|
example: *a8
|
|
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:
|
|
- &a9
|
|
customer_id: cus_123
|
|
payment_url: https://checkout.stripe.com/...
|
|
example: *a9
|
|
x-speakeasy-name-override: attach
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.billing.attach({
|
|
customerId: "cus_123",
|
|
planId: "pro_plan",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.billing.attach(
|
|
customer_id="cus_123",
|
|
plan_id="pro_plan",
|
|
)
|
|
/v1/billing.preview_attach:
|
|
post:
|
|
operationId: previewAttach
|
|
description: >-
|
|
Previews the billing changes that would occur when attaching a plan,
|
|
without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers what they will be charged before
|
|
confirming a subscription change.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
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
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
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
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
included:
|
|
type: number
|
|
unlimited:
|
|
type: boolean
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- interval
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
type: number
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
type: number
|
|
required:
|
|
- expiry_duration_type
|
|
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:
|
|
- &a10
|
|
customer_id: cus_123
|
|
plan_id: pro_plan
|
|
example: *a10
|
|
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:
|
|
- &a11
|
|
customerId: charles
|
|
lineItems:
|
|
- title: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
amount: 20
|
|
discounts: []
|
|
total: 20
|
|
currency: usd
|
|
example: *a11
|
|
x-speakeasy-name-override: previewAttach
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.billing.previewAttach({
|
|
customerId: "cus_123",
|
|
planId: "pro_plan",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.billing.preview_attach(
|
|
customer_id="cus_123",
|
|
plan_id="pro_plan",
|
|
)
|
|
/v1/billing.update:
|
|
post:
|
|
operationId: billingUpdate
|
|
description: >-
|
|
Updates an existing subscription. Use to modify feature quantities,
|
|
cancel, or change plan configuration.
|
|
|
|
|
|
Use this endpoint to update prepaid quantities, cancel a subscription
|
|
(immediately or at end of cycle), or modify subscription settings.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
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
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
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
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
included:
|
|
type: number
|
|
unlimited:
|
|
type: boolean
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- interval
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
type: number
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
type: number
|
|
required:
|
|
- expiry_duration_type
|
|
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:
|
|
- &a12
|
|
customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 10
|
|
example: *a12
|
|
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:
|
|
- &a13
|
|
customer_id: cus_123
|
|
invoice:
|
|
status: paid
|
|
stripe_id: in_1234
|
|
total: 1500
|
|
currency: usd
|
|
hosted_invoice_url: https://invoice.stripe.com/...
|
|
payment_url: null
|
|
example: *a13
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.billing.update({
|
|
customerId: "cus_123",
|
|
planId: "pro_plan",
|
|
featureQuantities: [
|
|
{
|
|
featureId: "seats",
|
|
quantity: 10,
|
|
},
|
|
],
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.billing.update(
|
|
customer_id="cus_123",
|
|
plan_id="pro_plan",
|
|
feature_quantities=[
|
|
{
|
|
"feature_id": "seats",
|
|
"quantity": 10,
|
|
},
|
|
],
|
|
)
|
|
/v1/billing.preview_update:
|
|
post:
|
|
operationId: previewUpdate
|
|
description: >-
|
|
Previews the billing changes that would occur when updating a
|
|
subscription, without actually making any changes.
|
|
|
|
|
|
Use this endpoint to show customers prorated charges or refunds before
|
|
confirming subscription modifications.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to attach the plan to.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity to attach the plan to.
|
|
plan_id:
|
|
type: string
|
|
description: The ID of the plan.
|
|
feature_quantities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
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
|
|
duration_type:
|
|
enum:
|
|
- day
|
|
- month
|
|
- year
|
|
default: month
|
|
card_required:
|
|
type: boolean
|
|
default: true
|
|
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
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- amount
|
|
- interval
|
|
- type: "null"
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
included:
|
|
type: number
|
|
unlimited:
|
|
type: boolean
|
|
reset:
|
|
type: object
|
|
properties:
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- minute
|
|
- hour
|
|
- day
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
required:
|
|
- interval
|
|
price:
|
|
type: object
|
|
properties:
|
|
amount:
|
|
type: number
|
|
tiers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
to:
|
|
anyOf:
|
|
- type: number
|
|
- const: inf
|
|
amount:
|
|
type: number
|
|
required:
|
|
- to
|
|
- amount
|
|
interval:
|
|
enum:
|
|
- one_off
|
|
- week
|
|
- month
|
|
- quarter
|
|
- semi_annual
|
|
- year
|
|
interval_count:
|
|
type: number
|
|
default: 1
|
|
billing_units:
|
|
type: number
|
|
default: 1
|
|
billing_method:
|
|
enum:
|
|
- prepaid
|
|
- usage_based
|
|
max_purchase:
|
|
type: number
|
|
required:
|
|
- interval
|
|
- billing_method
|
|
proration:
|
|
type: object
|
|
properties:
|
|
on_increase:
|
|
enum:
|
|
- bill_immediately
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- bill_next_cycle
|
|
on_decrease:
|
|
enum:
|
|
- prorate
|
|
- prorate_immediately
|
|
- prorate_next_cycle
|
|
- none
|
|
- no_prorations
|
|
required:
|
|
- on_increase
|
|
- on_decrease
|
|
rollover:
|
|
type: object
|
|
properties:
|
|
max:
|
|
type: number
|
|
expiry_duration_type:
|
|
enum:
|
|
- month
|
|
- forever
|
|
expiry_duration_length:
|
|
type: number
|
|
required:
|
|
- expiry_duration_type
|
|
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:
|
|
- &a14
|
|
customer_id: cus_123
|
|
plan_id: pro_plan
|
|
feature_quantities:
|
|
- feature_id: seats
|
|
quantity: 15
|
|
example: *a14
|
|
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:
|
|
- &a15
|
|
customerId: charles
|
|
lineItems:
|
|
- title: Pro seed
|
|
description: Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)
|
|
amount: 20
|
|
discounts: []
|
|
total: 20
|
|
currency: usd
|
|
example: *a15
|
|
x-speakeasy-name-override: previewUpdate
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.billing.previewUpdate({
|
|
customerId: "cus_123",
|
|
planId: "pro_plan",
|
|
featureQuantities: [
|
|
{
|
|
featureId: "seats",
|
|
quantity: 15,
|
|
},
|
|
],
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.billing.preview_update(
|
|
customer_id="cus_123",
|
|
plan_id="pro_plan",
|
|
feature_quantities=[
|
|
{
|
|
"feature_id": "seats",
|
|
"quantity": 15,
|
|
},
|
|
],
|
|
)
|
|
/v1/billing.open_customer_portal:
|
|
post:
|
|
operationId: openCustomerPortal
|
|
description: Create a billing portal session for a customer to manage their
|
|
subscription.
|
|
tags:
|
|
- billing
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to open the billing portal for.
|
|
configuration_id:
|
|
type: string
|
|
description: Stripe billing portal configuration ID. Create configurations in
|
|
your Stripe dashboard.
|
|
return_url:
|
|
type: string
|
|
description: URL to redirect to when back button is clicked in the billing
|
|
portal
|
|
required:
|
|
- customer_id
|
|
title: OpenCustomerPortalParams
|
|
examples:
|
|
- &a16
|
|
customer_id: cus_123
|
|
return_url: https://useautumn.com
|
|
example: *a16
|
|
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:
|
|
- &a17
|
|
customer_id: cus_123
|
|
url: https://billing.stripe.com/session/...
|
|
example: *a17
|
|
x-speakeasy-name-override: openCustomerPortal
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.billing.openCustomerPortal({
|
|
customerId: "cus_123",
|
|
returnUrl: "https://useautumn.com",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.billing.open_customer_portal(
|
|
customer_id="cus_123",
|
|
return_url="https://useautumn.com",
|
|
)
|
|
/v1/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.
|
|
granted_balance:
|
|
type: number
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CreateBalanceParams
|
|
examples:
|
|
- &a18
|
|
customer_id: cus_123
|
|
feature_id: api_calls
|
|
included: 1000
|
|
reset:
|
|
interval: month
|
|
example: *a18
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.balances.create({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
included: 1000,
|
|
reset: {
|
|
interval: "month",
|
|
},
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.balances.create(
|
|
customer_id="cus_123",
|
|
feature_id="api_calls",
|
|
included=1000,
|
|
reset={
|
|
"interval": "month",
|
|
},
|
|
)
|
|
/v1/balances.update:
|
|
post:
|
|
operationId: updateBalance
|
|
description: Update a customer balance.
|
|
tags:
|
|
- balances
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
remaining:
|
|
type: number
|
|
description: Set the remaining balance to this exact value. Cannot be combined
|
|
with add_to_balance.
|
|
add_to_balance:
|
|
type: number
|
|
description: Add this amount to the current balance. Use negative values to
|
|
subtract. Cannot be combined with current_balance.
|
|
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:
|
|
- &a19
|
|
customer_id: cus_123
|
|
feature_id: api_calls
|
|
remaining: 5
|
|
example: *a19
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
x-speakeasy-name-override: update
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.balances.update({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
remaining: 5,
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.balances.update(
|
|
customer_id="cus_123",
|
|
feature_id="api_calls",
|
|
remaining=5,
|
|
)
|
|
/v1/balances.check:
|
|
post:
|
|
operationId: check
|
|
description: >-
|
|
Checks whether a customer currently has enough balance to use a feature.
|
|
|
|
|
|
Use this to gate access before a feature action. Enable sendEvent when
|
|
you want to check and consume balance atomically in one request.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
required_balance:
|
|
type: number
|
|
description: "Minimum balance required for access. Returns allowed: false if the
|
|
customer's balance is below this value. Defaults to 1."
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to the usage event if send_event is
|
|
true.
|
|
send_event:
|
|
type: boolean
|
|
description: If true, atomically records a usage event while checking access.
|
|
The required_balance value is used as the usage amount.
|
|
Combines check + track in one call.
|
|
with_preview:
|
|
type: boolean
|
|
description: If true, includes upgrade/upsell information in the response when
|
|
access is denied. Useful for displaying paywalls.
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: CheckParams
|
|
examples:
|
|
- &a20
|
|
customer_id: cus_123
|
|
feature_id: messages
|
|
- customer_id: cus_123
|
|
feature_id: messages
|
|
required_balance: 3
|
|
send_event: true
|
|
example: *a20
|
|
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:
|
|
- type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
- 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:
|
|
- &a21
|
|
allowed: true
|
|
customer_id: cus_123
|
|
entity_id: null
|
|
required_balance: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
example: *a21
|
|
x-speakeasy-name-override: check
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.check({
|
|
customerId: "cus_123",
|
|
featureId: "messages",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.check(
|
|
customer_id="cus_123",
|
|
feature_id="messages",
|
|
)
|
|
/v1/balances.track:
|
|
post:
|
|
operationId: track
|
|
description: >-
|
|
Records usage for a customer feature and returns updated balances.
|
|
|
|
|
|
Use this after an action happens to decrement usage, or send a negative
|
|
value to credit balance back.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature to track usage for. Required if event_name is
|
|
not provided.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity for entity-scoped balances (e.g., per-seat
|
|
limits).
|
|
event_name:
|
|
type: string
|
|
minLength: 1
|
|
description: Event name to track usage for. Use instead of feature_id when
|
|
multiple features should be tracked from a single event.
|
|
value:
|
|
type: number
|
|
description: The amount of usage to record. Defaults to 1. Use negative values
|
|
to credit balance (e.g., when removing a seat).
|
|
properties:
|
|
type: object
|
|
propertyNames:
|
|
type: string
|
|
additionalProperties: {}
|
|
description: Additional properties to attach to this usage event.
|
|
required:
|
|
- customer_id
|
|
title: TrackParams
|
|
examples:
|
|
- &a22
|
|
customer_id: cus_123
|
|
feature_id: messages
|
|
value: 1
|
|
example: *a22
|
|
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:
|
|
- type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
- 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:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
description: Map of feature_id to updated balance when tracking by event_name
|
|
affects multiple features.
|
|
required:
|
|
- customer_id
|
|
- value
|
|
- balance
|
|
examples:
|
|
- &a23
|
|
customer_id: cus_123
|
|
value: 1
|
|
balance:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
example: *a23
|
|
x-speakeasy-name-override: track
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.track({
|
|
customerId: "cus_123",
|
|
featureId: "messages",
|
|
value: 1,
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.track(
|
|
customer_id="cus_123",
|
|
feature_id="messages",
|
|
value=1,
|
|
)
|
|
/v1/events.list:
|
|
post:
|
|
operationId: listEvents
|
|
description: List usage events for your organization. Filter by customer,
|
|
feature, or time range.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 9007199254740991
|
|
default: 0
|
|
description: Number of items to skip
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 100
|
|
description: Number of items to return. Default 100, max 1000.
|
|
customer_id:
|
|
type: string
|
|
description: Filter events by customer ID
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Filter by specific feature ID(s)
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
description: Filter events after this timestamp (epoch milliseconds)
|
|
end:
|
|
type: number
|
|
description: Filter events before this timestamp (epoch milliseconds)
|
|
description: Filter events by time range
|
|
title: EventsListParams
|
|
examples:
|
|
- &a24
|
|
customer_id: cus_123
|
|
limit: 50
|
|
- feature_id: api_calls
|
|
custom_range:
|
|
start: 1704067200000
|
|
end: 1706745600000
|
|
example: *a24
|
|
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:
|
|
- &a25
|
|
list:
|
|
- id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg
|
|
timestamp: 1765958215459
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 30
|
|
properties: {}
|
|
- id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM
|
|
timestamp: 1765956512057
|
|
feature_id: credits
|
|
customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
|
|
value: 49
|
|
properties: {}
|
|
total: 2
|
|
has_more: false
|
|
offset: 0
|
|
limit: 100
|
|
example: *a25
|
|
x-speakeasy-name-override: list
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.events.list({
|
|
limit: 50,
|
|
customerId: "cus_123",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.events.list(
|
|
offset=0,
|
|
limit=50,
|
|
customer_id="cus_123",
|
|
)
|
|
/v1/events.aggregate:
|
|
post:
|
|
operationId: aggregateEvents
|
|
description: Aggregate usage events by time period. Returns usage totals grouped
|
|
by feature and optionally by a custom property.
|
|
tags:
|
|
- events
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
minLength: 1
|
|
description: Customer ID to aggregate events for
|
|
feature_id:
|
|
anyOf:
|
|
- type: string
|
|
minLength: 1
|
|
- type: array
|
|
items:
|
|
type: string
|
|
minLength: 1
|
|
description: Feature ID(s) to aggregate events for
|
|
group_by:
|
|
type: string
|
|
pattern: ^properties\..*
|
|
description: Property to group events by. If provided, each key in the response
|
|
will be an object with distinct groups as the keys
|
|
range:
|
|
enum:
|
|
- 24h
|
|
- 7d
|
|
- 30d
|
|
- 90d
|
|
- last_cycle
|
|
- 1bc
|
|
- 3bc
|
|
description: Time range to aggregate events for. Either range or custom_range
|
|
must be provided
|
|
bin_size:
|
|
enum:
|
|
- day
|
|
- hour
|
|
- month
|
|
default: day
|
|
description: Size of the time bins to aggregate events for. Defaults to hour if
|
|
range is 24h, otherwise day
|
|
custom_range:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: number
|
|
end:
|
|
type: number
|
|
required:
|
|
- start
|
|
- end
|
|
description: Custom time range to aggregate events for. If provided, range must
|
|
not be provided
|
|
required:
|
|
- customer_id
|
|
- feature_id
|
|
title: EventsAggregateParams
|
|
examples:
|
|
- &a26
|
|
customer_id: cus_123
|
|
feature_id: api_calls
|
|
range: 30d
|
|
bin_size: day
|
|
- customer_id: cus_123
|
|
feature_id:
|
|
- api_calls
|
|
- messages
|
|
range: 7d
|
|
group_by: properties.model
|
|
example: *a26
|
|
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:
|
|
- &a27
|
|
list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
- list:
|
|
- period: 1762905600000
|
|
values:
|
|
messages: 10
|
|
sessions: 3
|
|
grouped_values:
|
|
messages:
|
|
api: 5
|
|
web: 5
|
|
sessions:
|
|
api: 2
|
|
web: 1
|
|
- period: 1762992000000
|
|
values:
|
|
messages: 3
|
|
sessions: 12
|
|
grouped_values:
|
|
messages:
|
|
api: 1
|
|
web: 2
|
|
sessions:
|
|
api: 10
|
|
web: 2
|
|
total:
|
|
messages:
|
|
count: 2
|
|
sum: 13
|
|
sessions:
|
|
count: 2
|
|
sum: 15
|
|
example: *a27
|
|
x-speakeasy-name-override: aggregate
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.events.aggregate({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
range: "30d",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.events.aggregate(
|
|
customer_id="cus_123",
|
|
feature_id="api_calls",
|
|
range="30d",
|
|
bin_size="day",
|
|
)
|
|
/v1/entities.create:
|
|
post:
|
|
operationId: createEntity
|
|
description: >-
|
|
Creates an entity for a customer and feature, then returns the entity
|
|
with balances and subscriptions.
|
|
|
|
|
|
Use entities when usage and access must be scoped to sub-resources (for
|
|
example seats, projects, or workspaces) instead of only the customer.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
description: The name of the entity
|
|
feature_id:
|
|
type: string
|
|
description: The ID of the feature this entity is associated with
|
|
customer_data:
|
|
$ref: "#/components/schemas/CustomerData"
|
|
description: Customer attributes used to resolve the customer when customer_id
|
|
is not provided.
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- feature_id
|
|
- customer_id
|
|
- entity_id
|
|
title: CreateEntityParams
|
|
examples:
|
|
- &a28
|
|
customer_id: cus_123
|
|
entity_id: seat_42
|
|
feature_id: seats
|
|
name: Seat 42
|
|
example: *a28
|
|
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:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
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:
|
|
- &a29
|
|
id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
example: *a29
|
|
x-speakeasy-name-override: create
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.entities.create({
|
|
name: "Seat 42",
|
|
featureId: "seats",
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.entities.create(
|
|
feature_id="seats",
|
|
customer_id="cus_123",
|
|
entity_id="seat_42",
|
|
name="Seat 42",
|
|
)
|
|
/v1/entities.get:
|
|
post:
|
|
operationId: getEntity
|
|
description: >-
|
|
Fetches a single entity by entity ID.
|
|
|
|
|
|
Use this to read one entity's current state. Pass customerId when you
|
|
want to scope the lookup to a specific customer.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer to create the entity for.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: GetEntityParams
|
|
examples:
|
|
- &a30
|
|
entity_id: seat_42
|
|
- customer_id: cus_123
|
|
entity_id: seat_42
|
|
example: *a30
|
|
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:
|
|
type: object
|
|
properties:
|
|
feature_id:
|
|
type: string
|
|
description: The feature ID this balance is for.
|
|
feature:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
type:
|
|
enum:
|
|
- boolean
|
|
- metered
|
|
- credit_system
|
|
consumable:
|
|
type: boolean
|
|
event_names:
|
|
type: array
|
|
items:
|
|
type: string
|
|
credit_schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
metered_feature_id:
|
|
type: string
|
|
credit_cost:
|
|
type: number
|
|
required:
|
|
- metered_feature_id
|
|
- credit_cost
|
|
display:
|
|
type: object
|
|
properties:
|
|
singular:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
plural:
|
|
anyOf:
|
|
- type: string
|
|
- type: "null"
|
|
archived:
|
|
type: boolean
|
|
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
|
|
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:
|
|
- &a31
|
|
id: seat_42
|
|
name: Seat 42
|
|
customer_id: cus_123
|
|
feature_id: seats
|
|
created_at: 1771409161016
|
|
env: sandbox
|
|
subscriptions:
|
|
- plan_id: pro_plan
|
|
auto_enable: true
|
|
add_on: false
|
|
status: active
|
|
past_due: false
|
|
canceled_at: null
|
|
expires_at: null
|
|
trial_ends_at: null
|
|
started_at: 1771431921437
|
|
current_period_start: 1771431921437
|
|
current_period_end: 1771999921437
|
|
quantity: 1
|
|
purchases: []
|
|
balances:
|
|
messages:
|
|
feature_id: messages
|
|
granted: 100
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
overage_allowed: false
|
|
max_purchase: null
|
|
next_reset_at: 1773851121437
|
|
breakdown:
|
|
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
|
|
plan_id: pro_plan
|
|
included_grant: 100
|
|
prepaid_grant: 0
|
|
remaining: 72
|
|
usage: 28
|
|
unlimited: false
|
|
reset:
|
|
interval: month
|
|
resets_at: 1773851121437
|
|
price: null
|
|
expires_at: null
|
|
invoices: []
|
|
example: *a31
|
|
x-speakeasy-name-override: get
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.entities.get({
|
|
entityId: "seat_42",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.entities.get(entity_id="seat_42")
|
|
/v1/entities.delete:
|
|
post:
|
|
operationId: deleteEntity
|
|
description: >-
|
|
Deletes an entity by entity ID.
|
|
|
|
|
|
Use this when the underlying resource is removed and you no longer want
|
|
entity-scoped balances or subscriptions tracked for it.
|
|
tags:
|
|
- entities
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The ID of the customer.
|
|
entity_id:
|
|
type: string
|
|
description: The ID of the entity.
|
|
required:
|
|
- entity_id
|
|
title: DeleteEntityParams
|
|
examples:
|
|
- &a32
|
|
customer_id: cus_123
|
|
entity_id: seat_42
|
|
example: *a32
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
required:
|
|
- success
|
|
examples:
|
|
- &a33
|
|
success: true
|
|
example: *a33
|
|
x-speakeasy-name-override: delete
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.entities.delete({
|
|
customerId: "cus_123",
|
|
entityId: "seat_42",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.entities.delete(
|
|
entity_id="seat_42",
|
|
customer_id="cus_123",
|
|
)
|
|
/v1/referrals.create_code:
|
|
post:
|
|
operationId: createReferralCode
|
|
description: Create or fetch a referral code for a customer in a referral program.
|
|
tags:
|
|
- referrals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer
|
|
program_id:
|
|
type: string
|
|
description: ID of your referral program
|
|
required:
|
|
- customer_id
|
|
- program_id
|
|
title: CreateReferralCodeParams
|
|
examples:
|
|
- &a34
|
|
customer_id: cus_123
|
|
program_id: prog_123
|
|
example: *a34
|
|
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:
|
|
- &a35
|
|
code: <string>
|
|
customer_id: <string>
|
|
created_at: 123
|
|
example: *a35
|
|
x-speakeasy-name-override: createCode
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.referrals.createCode({
|
|
customerId: "cus_123",
|
|
programId: "prog_123",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.referrals.create_code(
|
|
customer_id="cus_123",
|
|
program_id="prog_123",
|
|
)
|
|
/v1/referrals.redeem_code:
|
|
post:
|
|
operationId: redeemReferralCode
|
|
description: Redeem a referral code for a customer.
|
|
tags:
|
|
- referrals
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: The referral code to redeem
|
|
customer_id:
|
|
type: string
|
|
description: The unique identifier of the customer redeeming the code
|
|
required:
|
|
- code
|
|
- customer_id
|
|
title: RedeemReferralCodeParams
|
|
examples:
|
|
- &a36
|
|
code: REF123
|
|
customer_id: cus_456
|
|
example: *a36
|
|
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:
|
|
- &a37
|
|
id: <string>
|
|
customer_id: <string>
|
|
reward_id: <string>
|
|
example: *a37
|
|
x-speakeasy-name-override: redeemCode
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|
|
x-codeSamples:
|
|
- lang: typescript
|
|
label: Typescript (SDK)
|
|
source: |-
|
|
import { Autumn } from 'autumn-js'
|
|
|
|
const autumn = new Autumn()
|
|
|
|
const result = await autumn.referrals.redeemCode({
|
|
code: "REF123",
|
|
customerId: "cus_456",
|
|
});
|
|
- lang: python
|
|
label: Python (SDK)
|
|
source: |-
|
|
from autumn_sdk import Autumn
|
|
|
|
autumn = Autumn(secret_key="am_sk_test...")
|
|
|
|
res = autumn.referrals.redeem_code(
|
|
code="REF123",
|
|
customer_id="cus_456",
|
|
)
|
|
security:
|
|
- secretKey: []
|
|
x-speakeasy-globals:
|
|
parameters:
|
|
- name: x-api-version
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
default: "2.1"
|
|
x-speakeasy-globals-hidden: true
|