---
title: "Preview Multi Attach"
openapi: "openapi POST /v1/billing.preview_multi_attach"
---
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
### 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 or items.
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.
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.
Tiered pricing. Either 'amount' or 'tiers' is required.
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.
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.
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.
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
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.
Optional feature ID this spend limit applies to.
Whether this spend limit is enabled.
Maximum allowed overage spend for the target 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.
The feature ID that this entity is associated with
Name of the entity
Billing controls for the entity.
List of overage spend limits per feature.
Optional feature ID this spend limit applies to.
Whether this spend limit is enabled.
Maximum allowed overage spend for the target 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 name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount in cents before discounts and tax for this line item.
The final amount in cents after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
The total amount in cents before discounts and tax for the current billing period.
The final amount in cents after discounts and tax for the current billing period.
The three-letter ISO currency code (e.g., 'usd').
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Unix timestamp (milliseconds) when the next billing cycle starts.
The total amount in cents before discounts and tax for the next cycle.
The final amount in cents after discounts and tax for the next cycle.
List of line items for the next billing cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount in cents before discounts and tax for this line item.
The final amount in cents after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
List of line items for usage-based features in the next cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
Expand the response with additional data.
Products or subscription changes being added or updated.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the response.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null 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.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be 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.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Miscellaneous plan-level configuration flags.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
Whether the customer's active instance of this plan is set to cancel.
Whether the customer is currently on a free trial of this plan.
The action that would occur if this plan were attached to the customer.
The feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Products or subscription changes being removed or ended.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the response.
Unique identifier for the plan.
Display name of the plan.
Optional description of the plan.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Version number of the plan. Incremented when plan configuration changes.
Whether this is an add-on plan that can be attached alongside a main plan.
If true, this plan is automatically attached when a customer is created. Used for free plans.
Base recurring price for the plan. Null for free plans or usage-only plans.
Base price amount for the plan.
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Display text for showing this price in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
The ID of the feature this item configures.
The full feature object if expanded.
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
The type of the feature
Singular and plural display names for the feature.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
The ID of the metered feature (should be a single_use feature).
The credit cost of the metered feature.
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
Number of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Display text for showing this item in pricing pages.
Main display text (e.g. '$10' or '100 messages').
Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Maximum rollover units. Null 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.
Free trial configuration. If set, new customers can try this plan before being charged.
Number of duration_type periods the trial lasts.
Unit of time for the trial duration ('day', 'month', 'year').
Whether a payment method is required to start the trial. If true, customer will be 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.
Unix timestamp (ms) when the plan was created.
Environment this plan belongs to ('sandbox' or 'live').
Whether the plan is archived. Archived plans cannot be attached to new customers.
If this is a variant, the ID of the base plan it was created from.
Miscellaneous plan-level configuration flags.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
Whether the customer's active instance of this plan is set to cancel.
Whether the customer is currently on a free trial of this plan.
The action that would occur if this plan were attached to the customer.
The feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Whether the customer will be redirected to a checkout page if attach is called.
The type of checkout that will be used if the customer is redirected to a checkout page.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Total tax amount in major currency units.
Tax included in line item subtotals.
Tax added on top of subtotals.
Three-letter currency code.
Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored).
Stripe customer invoice credits preview.
Stripe customer credit balance available, expressed as a positive number in major currency units.
Three-letter currency code.
```json 200
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
```