> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi Attach
> Attaches multiple plans to a customer in a single request. Creates a single Stripe subscription with all plans consolidated.
Use this endpoint when you need to subscribe a customer to multiple plans at once, such as a base plan plus add-ons, or to create a bundle of products.
export const DynamicResponseExample = ({json, statusCode = "200"}) => {
const toCamelCase = str => {
return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
};
const convertKeysToCamelCase = obj => {
if (Array.isArray(obj)) {
return obj.map(item => convertKeysToCamelCase(item));
}
if (obj !== null && typeof obj === "object") {
return Object.keys(obj).reduce((acc, key) => {
const camelKey = toCamelCase(key);
acc[camelKey] = convertKeysToCamelCase(obj[key]);
return acc;
}, {});
}
return obj;
};
const [isTypeScript, setIsTypeScript] = useState(() => {
if (typeof window !== "undefined") {
try {
const lang = localStorage.getItem("code");
return JSON.parse(lang) === "typescript";
} catch {
return true;
}
}
return true;
});
useEffect(() => {
const onMintlifyStorage = event => {
if (event.detail?.key === "code") {
try {
const value = JSON.parse(event.detail.value);
setIsTypeScript(value === "typescript");
} catch {}
}
};
const pollInterval = setInterval(() => {
try {
const lang = localStorage.getItem("code");
const value = JSON.parse(lang);
setIsTypeScript(value === "typescript");
} catch {}
}, 300);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, []);
const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
const snakeCaseString = JSON.stringify(json, null, 2);
const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
return
{isTypeScript ?
{camelCaseString}
:
{snakeCaseString}
}
;
};
export const DynamicResponseField = ({children, name, ...props}) => {
const convertToCamelCase = str => {
if (typeof str !== "string") return str;
return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
};
const [lang, setLang] = useState(() => {
if (typeof window !== "undefined") {
const stored = localStorage.getItem("code");
return stored || '"typescript"';
}
return '"typescript"';
});
useEffect(() => {
const onMintlifyStorage = event => {
const key = event.detail?.key;
if (key === "code") {
setLang(event.detail.value);
}
};
const pollInterval = setInterval(() => {
const current = localStorage.getItem("code");
if (current && current !== lang) {
setLang(current);
}
}, 500);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, [lang]);
const resolvedName = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(name) : name;
} catch {
return name;
}
}, [name, lang]);
return
{children}
;
};
export const DynamicParamField = ({children, body, path, ...props}) => {
const convertToCamelCase = str => {
if (typeof str !== "string") return str;
return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
};
const [lang, setLang] = useState(() => {
if (typeof window !== "undefined") {
const stored = localStorage.getItem("code");
return stored || '"typescript"';
}
return '"typescript"';
});
useEffect(() => {
const onMintlifyStorage = event => {
const key = event.detail?.key;
if (key === "code") {
setLang(event.detail.value);
}
};
const pollInterval = setInterval(() => {
const current = localStorage.getItem("code");
if (current && current !== lang) {
setLang(current);
}
}, 500);
document.addEventListener("mintlify-localstorage", onMintlifyStorage);
return () => {
document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
clearInterval(pollInterval);
};
}, [lang]);
const resolvedBody = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(body) : body;
} catch {
return body;
}
}, [body, lang]);
const resolvedPath = useMemo(() => {
try {
const value = JSON.parse(lang);
const useCamelCase = value === "typescript";
return useCamelCase ? convertToCamelCase(path) : path;
} catch {
return path;
}
}, [path, lang]);
return
{children}
;
};
### Body Parameters
The ID of the customer to attach the plans to.
The ID of the entity to attach the plans to.
The list of plans to attach to the customer.
The ID of the plan to attach.
Customize the plan to attach. Can override the price, items, or licenses.
Base price configuration for a plan.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Base price amounts in additional currencies. The base 'amount' is in the org's default currency.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Price amount in this currency. Set explicitly per currency, not converted from the base amount.
Override the items in the plan.
The ID of the feature to configure.
Number of free units included. Balance resets to this each interval for consumable features.
If true, customer has unlimited access to this feature.
Reset configuration for consumable features. Omit for non-consumable features like seats.
Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
Number of intervals between resets. Defaults to 1.
Pricing for usage beyond included units. Omit for free features.
Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.
Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Price amount in this currency. Set explicitly per currency, not converted from the base amount.
Tiered pricing. Either 'amount' or 'tiers' is required.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
Billing interval. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).
'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.
Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Billing behavior when quantity increases mid-cycle.
Credit behavior when quantity decreases mid-cycle.
Rollover config for unused units. If set, unused included units carry over.
Max rollover units. Omit for unlimited rollover.
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
When rolled over units expire.
Number of periods before expiry.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
Free trial configuration for a plan.
Number of duration\_type periods the trial lasts.
Unit of time for the trial ('day', 'month', 'year').
If true, payment method required to start trial. Customer is charged after trial ends.
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
Currency to bill this multi-attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and every plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
URL to redirect to after successful checkout.
Additional parameters to pass into the creation of the Stripe checkout session.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.
Customer details to set when creating a customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
Billing controls for the customer (auto top-ups, etc.)
List of auto top-up configurations per feature.
The ID of the feature (credit balance) to auto top-up.
Whether auto top-up is enabled.
When the balance drops below this threshold, an auto top-up will be purchased.
Amount of credits to add per auto top-up.
Optional rate limit to cap how often auto top-ups occur.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
List of overage spend limits per feature (caps overage spend).
Optional feature ID this spend limit applies to.
Whether the overage spend limit is enabled.
How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
List of hard usage caps per feature (max units per interval).
The feature this usage limit applies to.
Whether this usage limit is enabled.
Maximum units allowed per interval.
Interval for the cap, aligned to the customer's billing cycle.
When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
List of usage alert configurations per feature.
The feature ID this alert applies to.
Whether this usage alert is enabled.
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage\_percentage or remaining\_percentage, this is a percentage (0-100).
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
Optional user-defined label to distinguish multiple alerts on the same feature.
List of overage allowed controls per feature. When enabled, usage can exceed balance.
The feature ID this overage allowed control applies to.
Whether overage is allowed for this feature.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
The feature ID that this entity is associated with
Name of the entity
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
Optional feature ID this spend limit applies to.
Whether the overage spend limit is enabled.
How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
The feature this usage limit applies to.
Whether this usage limit is enabled.
Maximum units allowed per interval.
Interval for the cap, aligned to the customer's billing cycle.
When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
List of usage alert configurations per feature.
The feature ID this alert applies to.
Whether this usage alert is enabled.
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage\_percentage or remaining\_percentage, this is a percentage (0-100).
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
Optional user-defined label to distinguish multiple alerts on the same feature.
List of overage allowed controls per feature. When enabled, usage can exceed balance.
The feature ID this overage allowed control applies to.
Whether overage is allowed for this feature.
### Response
The ID of the customer.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"invoice": {
"status": "paid",
"stripe_id": "in_1234",
"total": 4900,
"currency": "usd",
"hosted_invoice_url": "https://invoice.stripe.com/..."
},
"payment_url": null
}
```
## OpenAPI
````yaml openapi POST /v1/billing.multi_attach
openapi: 3.1.0
info:
title: Autumn API
version: 2.3.0
servers:
- url: https://api.useautumn.com
description: Production server
security:
- secretKey: []
paths:
/v1/billing.multi_attach:
post:
tags:
- billing
description: >-
Attaches multiple plans to a customer in a single request. Creates a
single Stripe subscription with all plans consolidated.
Use this endpoint when you need to subscribe a customer to multiple
plans at once, such as a base plan plus add-ons, or to create a bundle
of products.
operationId: multiAttach
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
default: 2.3.0
x-speakeasy-globals-hidden: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The ID of the customer to attach the plans to.
entity_id:
type: string
description: The ID of the entity to attach the plans to.
plans:
type: array
minItems: 1
items:
type: object
properties:
plan_id:
type: string
description: The ID of the plan to attach.
customize:
type: object
properties:
price:
anyOf:
- type: object
properties:
amount:
type: number
description: Base price amount for the plan.
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: Billing interval (e.g. 'month', 'year').
interval_count:
type: number
description: >-
Number of intervals per billing cycle.
Defaults to 1.
additional_currencies:
type: array
items:
type: object
properties:
currency:
type: string
description: >-
Three-letter Stripe-supported currency
code (e.g. 'eur', 'gbp').
amount:
type: number
description: >-
Price amount in this currency. Set
explicitly per currency, not converted
from the base amount.
required:
- currency
- amount
description: >-
Base price amounts in additional
currencies. The base 'amount' is in the
org's default currency.
required:
- amount
- interval
title: BasePrice
description: Base price configuration for a plan.
- type: 'null'
description: >-
Override the base price of the plan. Pass null to
remove the base price.
items:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The ID of the feature to configure.
included:
type: number
description: >-
Number of free units included. Balance
resets to this each interval for consumable
features.
unlimited:
type: boolean
description: >-
If true, customer has unlimited access to
this feature.
reset:
type: object
properties:
interval:
enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Interval at which balance resets (e.g.
'month', 'year'). For consumable
features only.
interval_count:
type: number
description: >-
Number of intervals between resets.
Defaults to 1.
required:
- interval
description: >-
Reset configuration for consumable features.
Omit for non-consumable features like seats.
price:
type: object
properties:
amount:
type: number
description: >-
Price per billing_units after included
usage. Either 'amount' or 'tiers' is
required.
additional_currencies:
type: array
items:
type: object
properties:
currency:
type: string
description: >-
Three-letter Stripe-supported currency
code (e.g. 'eur', 'gbp').
amount:
type: number
description: >-
Price amount in this currency. Set
explicitly per currency, not converted
from the base amount.
required:
- currency
- amount
description: >-
Amounts in additional currencies for
this flat price. The base 'amount' is in
the org's default currency. Only valid
with 'amount', not 'tiers'.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
additional_currencies:
type: array
items:
type: object
properties:
currency: {}
amount: {}
flat_amount: {}
description: >-
Per-currency amounts for this tier. Tier
boundaries ('to') are shared across all
currencies.
required:
- to
description: >-
Tiered pricing. Either 'amount' or
'tiers' is required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 1.
billing_units:
type: number
default: 1
description: >-
Units per price increment. Usage is
rounded UP when billed (e.g.
billing_units=100 means 101 rounds to
200).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: >-
'prepaid' for upfront payment (seats),
'usage_based' for pay-as-you-go.
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Max units purchasable beyond included.
E.g. included=100, max_purchase=300
allows 400 total. Null for no limit.
required:
- interval
- billing_method
description: >-
Pricing for usage beyond included units.
Omit for free features.
proration:
type: object
properties:
on_increase:
enum:
- bill_immediately
- prorate_immediately
- prorate_next_cycle
- bill_next_cycle
type: string
description: >-
Billing behavior when quantity increases
mid-cycle.
on_decrease:
enum:
- prorate
- prorate_immediately
- prorate_next_cycle
- none
- no_prorations
type: string
description: >-
Credit behavior when quantity decreases
mid-cycle.
required:
- on_increase
- on_decrease
description: >-
Proration settings for prepaid features.
Controls mid-cycle quantity change billing.
rollover:
type: object
properties:
max:
type: number
description: >-
Max rollover units. Omit for unlimited
rollover.
max_percentage:
type: number
description: >-
Maximum rollover as a percentage (0-100)
of included + prepaid grant. Mutually
exclusive with max.
expiry_duration_type:
enum:
- month
- forever
type: string
description: When rolled over units expire.
expiry_duration_length:
type: number
description: Number of periods before expiry.
required:
- expiry_duration_type
description: >-
Rollover config for unused units. If set,
unused included units carry over.
required:
- feature_id
title: PlanItem
description: >-
Configuration for a feature item in a plan,
including usage limits, pricing, and rollover
settings.
description: Override the items in the plan.
description: >-
Customize the plan to attach. Can override the price,
items, or licenses.
feature_quantities:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The ID of the feature to set quantity for.
quantity:
type: number
minimum: 0
description: The quantity of the feature.
adjustable:
type: boolean
description: Whether the customer can adjust the quantity.
required:
- feature_id
title: FeatureQuantity
description: Quantity configuration for a prepaid feature.
description: >-
If this plan contains prepaid features, use this field
to specify the quantity of each prepaid feature.
version:
type: number
description: The version of the plan to attach.
subscription_id:
type: string
description: >-
A unique ID to identify this subscription. Useful when
attaching the same plan multiple times.
required:
- plan_id
description: The list of plans to attach to the customer.
free_trial:
anyOf:
- type: object
properties:
duration_length:
type: number
description: Number of duration_type periods the trial lasts.
duration_type:
enum:
- day
- month
- year
type: string
default: month
description: Unit of time for the trial ('day', 'month', 'year').
card_required:
type: boolean
default: true
description: >-
If true, payment method required to start trial.
Customer is charged after trial ends.
on_end:
enum:
- bill
- revert
type: string
description: >-
Behavior when the trial ends. 'bill' charges the
customer (default). 'revert' expires the trial and
restores the customer's previous plan.
required:
- duration_length
title: FreeTrialParams
description: Free trial configuration for a plan.
- type: 'null'
description: >-
Free trial configuration applied to all plans. Pass an
object to set a custom trial, or null to remove any trial.
currency:
type: string
description: >-
Currency to bill this multi-attach in (e.g. usd, eur). Must
match the customer's currency if they are already locked to
one, and every plan must offer a paid price in it. Defaults
to the customer's currency, then the org default.
invoice_mode:
type: object
properties:
enabled:
type: boolean
description: >-
When true, creates an invoice and sends it to the
customer instead of charging their card immediately.
Uses Stripe's send_invoice collection method.
enable_plan_immediately:
type: boolean
default: false
description: >-
If true, enables the plan immediately even though the
invoice is not paid yet.
finalize:
type: boolean
default: true
description: >-
If true, finalizes the invoice so it can be sent to the
customer. If false, keeps it as a draft for manual
review.
invoice_template_id:
type: string
description: >-
ID of an invoice template (configured in billing
settings) whose footer (e.g. bank details) is applied to
the invoice.
net_terms_days:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
exclusiveMinimum: 0
description: >-
Number of days the customer has to pay the invoice
before it is due (Stripe days_until_due).
required:
- enabled
description: >-
Invoice mode creates a draft or open invoice and sends it to
the customer, instead of charging their card immediately.
discounts:
type: array
items:
type: object
properties:
reward_id:
type: string
description: The ID of the reward to apply as a discount.
promotion_code:
type: string
description: The promotion code to apply as a discount.
title: AttachDiscount
description: >-
A discount to apply. Can be either a reward ID or a
promotion code.
description: >-
List of discounts to apply. Each discount can be an Autumn
reward ID, Stripe coupon ID, or Stripe promotion code.
success_url:
type: string
description: URL to redirect to after successful checkout.
checkout_session_params:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Additional parameters to pass into the creation of the
Stripe checkout session.
redirect_mode:
enum:
- always
- if_required
- never
type: string
description: >-
Controls when to return a checkout URL. 'always' returns a
URL even if payment succeeds, 'if_required' only when
payment action is needed, 'never' disables redirects.
default: if_required
new_billing_subscription:
type: boolean
description: >-
Only applicable when the customer has an existing Stripe
subscription. If true, creates a new separate subscription
instead of merging into the existing one.
enable_plan_immediately:
type: boolean
description: >-
If true, the cusProducts are activated immediately even when
payment is pending via Stripe checkout.
customer_data:
$ref: '#/components/schemas/CustomerData'
entity_data:
type: object
properties:
feature_id:
type: string
description: The feature ID that this entity is associated with
name:
type: string
description: Name of the entity
billing_controls:
type: object
properties:
spend_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
Optional feature ID this spend limit applies
to.
enabled:
type: boolean
default: false
description: Whether the overage spend limit is enabled.
limit_type:
enum:
- absolute
- usage_percentage
type: string
description: >-
How overage_limit is interpreted: an absolute
overage cap (default) or a percentage of the
main-plan allowance.
overage_limit:
type: number
minimum: 0
description: >-
Overage cap for the feature: absolute units,
or a percent (e.g. 120) when limit_type is
usage_percentage.
skip_overage_billing:
type: boolean
description: >-
When true, overage for this feature is not
posted to Stripe. Usage tracking and balance
resets still behave normally.
description: >-
List of spend limits per feature. Each entry caps
overage (overage_limit) and/or per-interval usage
(usage_limit).
usage_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature this usage limit applies to.
enabled:
type: boolean
default: true
description: Whether this usage limit is enabled.
limit:
type: number
minimum: 0
description: Maximum units allowed per interval.
interval:
enum:
- day
- week
- month
- year
type: string
description: >-
Interval for the cap, aligned to the
customer's billing cycle.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: string
minLength: 1
maxLength: 128
- type: number
- type: boolean
required:
- properties
description: >-
When set, only usage from events whose
properties match counts toward this cap. Omit
to count all usage of the feature.
required:
- feature_id
- limit
- interval
description: >-
List of hard usage caps per feature for this entity.
An entity entry overrides the customer's for that
feature.
usage_alerts:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature ID this alert applies to.
enabled:
type: boolean
default: true
description: Whether this usage alert is enabled.
threshold:
type: number
minimum: 0
description: >-
The threshold value that triggers the alert.
For usage or remaining, this is an absolute
count. For usage_percentage or
remaining_percentage, this is a percentage
(0-100).
threshold_type:
enum:
- usage
- usage_percentage
- remaining
- remaining_percentage
type: string
description: >-
Whether the threshold is an absolute count or
a percentage of the usage allowance or
remaining balance.
name:
type: string
description: >-
Optional user-defined label to distinguish
multiple alerts on the same feature.
required:
- threshold
- threshold_type
description: List of usage alert configurations per feature.
overage_allowed:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The feature ID this overage allowed control
applies to.
enabled:
type: boolean
default: false
description: Whether overage is allowed for this feature.
required:
- feature_id
description: >-
List of overage allowed controls per feature. When
enabled, usage can exceed balance.
description: Billing controls for the entity.
required:
- feature_id
required:
- customer_id
- plans
title: MultiAttachParams
examples:
- customer_id: cus_123
plans:
- plan_id: pro_plan
- plan_id: addon_seats
feature_quantities:
- feature_id: seats
quantity: 5
example:
customer_id: cus_123
plans:
- plan_id: pro_plan
- plan_id: addon_seats
feature_quantities:
- feature_id: seats
quantity: 5
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The ID of the customer.
entity_id:
type: string
description: >-
The ID of the entity, if the plan was attached to an
entity.
invoice:
type: object
properties:
status:
anyOf:
- type: string
- type: 'null'
description: >-
The status of the invoice (e.g., 'paid', 'open',
'draft').
stripe_id:
type: string
description: The Stripe invoice ID.
total:
type: number
description: The total amount of the invoice in cents.
currency:
type: string
description: The three-letter ISO currency code (e.g., 'usd').
hosted_invoice_url:
anyOf:
- type: string
- type: 'null'
description: >-
URL to the hosted invoice page where the customer can
view and pay the invoice.
required:
- status
- stripe_id
- total
- currency
- hosted_invoice_url
description: >-
Invoice details if an invoice was created. Only present
when a charge was made.
payment_url:
anyOf:
- type: string
- type: 'null'
description: >-
URL to redirect the customer to complete payment. Null if
no payment action is required.
required_action:
type: object
properties:
code:
enum:
- 3ds_required
- payment_method_required
- payment_failed
- payment_processing
type: string
description: The type of action required to complete the payment.
reason:
type: string
description: >-
A human-readable explanation of why this action is
required.
required:
- code
- reason
description: >-
Details about any action required to complete the payment.
Present when the payment could not be processed
automatically.
required:
- customer_id
- payment_url
examples:
- customer_id: cus_123
invoice:
status: paid
stripe_id: in_1234
total: 4900
currency: usd
hosted_invoice_url: https://invoice.stripe.com/...
payment_url: null
example:
customer_id: cus_123
invoice:
status: paid
stripe_id: in_1234
total: 4900
currency: usd
hosted_invoice_url: https://invoice.stripe.com/...
payment_url: null
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.multiAttach({
customerId: "cus_123",
plans: [
{
planId: "pro_plan",
},
{
planId: "addon_seats",
featureQuantities: [
{
featureId: "seats",
quantity: 5,
},
],
},
],
});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.multi_attach(
customer_id="cus_123",
plans=[
{
"plan_id": "pro_plan",
},
{
"plan_id": "addon_seats",
"feature_quantities": [
{
"feature_id": "seats",
"quantity": 5,
},
],
},
],
redirect_mode="if_required",
)
components:
schemas:
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
currency:
anyOf:
- type: string
- type: 'null'
description: >-
Currency to bill this customer in (e.g. usd, eur). Defaults to the
organization's default currency.
billing_controls:
type: object
properties:
auto_topups:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The ID of the feature (credit balance) to auto top-up.
enabled:
type: boolean
default: false
description: Whether auto top-up is enabled.
threshold:
type: number
minimum: 0
description: >-
When the balance drops below this threshold, an auto
top-up will be purchased.
quantity:
type: number
minimum: 1
description: Amount of credits to add per auto top-up.
purchase_limit:
type: object
properties:
interval:
enum:
- hour
- day
- week
- month
type: string
description: The time interval for the purchase limit window.
interval_count:
type: number
minimum: 1
default: 1
description: Number of intervals in the purchase limit window.
limit:
type: number
minimum: 1
description: >-
Maximum number of auto top-ups allowed within the
interval.
required:
- interval
- limit
description: Optional rate limit to cap how often auto top-ups occur.
invoice_mode:
type: boolean
description: >-
When true, auto top-up creates a send_invoice invoice
instead of auto-charging.
required:
- feature_id
- threshold
- quantity
description: List of auto top-up configurations per feature.
spend_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: Optional feature ID this spend limit applies to.
enabled:
type: boolean
default: false
description: Whether the overage spend limit is enabled.
limit_type:
enum:
- absolute
- usage_percentage
type: string
description: >-
How overage_limit is interpreted: an absolute overage cap
(default) or a percentage of the main-plan allowance.
overage_limit:
type: number
minimum: 0
description: >-
Overage cap for the feature: absolute units, or a percent
(e.g. 120) when limit_type is usage_percentage.
skip_overage_billing:
type: boolean
description: >-
When true, overage for this feature is not posted to
Stripe. Usage tracking and balance resets still behave
normally.
description: List of overage spend limits per feature (caps overage spend).
usage_limits:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature this usage limit applies to.
enabled:
type: boolean
default: true
description: Whether this usage limit is enabled.
limit:
type: number
minimum: 0
description: Maximum units allowed per interval.
interval:
enum:
- day
- week
- month
- year
type: string
description: >-
Interval for the cap, aligned to the customer's billing
cycle.
filter:
type: object
properties:
properties:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: string
minLength: 1
maxLength: 128
- type: number
- type: boolean
required:
- properties
description: >-
When set, only usage from events whose properties match
counts toward this cap. Omit to count all usage of the
feature.
required:
- feature_id
- limit
- interval
description: List of hard usage caps per feature (max units per interval).
usage_alerts:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature ID this alert applies to.
enabled:
type: boolean
default: true
description: Whether this usage alert is enabled.
threshold:
type: number
minimum: 0
description: >-
The threshold value that triggers the alert. For usage or
remaining, this is an absolute count. For usage_percentage
or remaining_percentage, this is a percentage (0-100).
threshold_type:
enum:
- usage
- usage_percentage
- remaining
- remaining_percentage
type: string
description: >-
Whether the threshold is an absolute count or a percentage
of the usage allowance or remaining balance.
name:
type: string
description: >-
Optional user-defined label to distinguish multiple alerts
on the same feature.
required:
- threshold
- threshold_type
description: List of usage alert configurations per feature.
overage_allowed:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature ID this overage allowed control applies to.
enabled:
type: boolean
default: false
description: Whether overage is allowed for this feature.
required:
- feature_id
description: >-
List of overage allowed controls per feature. When enabled,
usage can exceed balance.
description: Billing controls for the customer (auto top-ups, etc.)
config:
type: object
properties:
disable_pooled_balance:
type: boolean
description: Whether to disable the shared customer-level pool for entities.
disable_overage_billing:
type: boolean
description: >-
Stops Autumn from posting usage-overage line items to Stripe for
this customer. Check/track and balance resets still behave
normally. When set, this overrides the organization-level
disable_overage_billing setting.
description: Miscellaneous configurations for the customer.
title: CustomerData
description: Customer details to set when creating a customer
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````