> ## 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.
# Preview Multi Update
> Previews the billing changes of a multi-plan update without making any changes. Returns one core preview per affected subscription.
Use this endpoint to show customers the credits and next-cycle changes of canceling multiple plans before confirming.
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 update plans for.
The ID of the entity to update plans for. Individual updates can override this with their own entity\_id.
The list of plan updates to apply to the customer.
The ID of the plan to update. Optional if subscription\_id is provided.
A unique ID to identify the subscription to update. Useful when a customer has multiple products with the same plan.
The ID of the entity this update targets. Overrides the top-level entity\_id for this update.
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.
How to handle proration for this update. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
### Response
The ID of the customer the preview applies to.
The three-letter ISO currency code (e.g., 'usd').
The combined amount due today across all subscriptions (sum of subscriptions\[].total).
One preview per affected Stripe subscription. Updates to plans without a subscription (free plans) produce no entry.
The ID of the customer.
List of line items for the current billing period.
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.
Deprecated. Use variant\_details.base\_plan\_id instead. If this is a variant, the ID of the base plan it was created from.
Details about how this variant relates to its latest base plan.
The ID of the base plan this variant was derived from.
The customization that transforms the base plan into this variant.
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.
Items to add to 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. 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.
Filters selecting items to remove from the plan.
Match items linked to this feature.
Match items with this billing method (prepaid or usage\_based).
Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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 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.
Plan-level billing controls used as customer defaults.
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.
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
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.
Deprecated. Use variant\_details.base\_plan\_id instead. If this is a variant, the ID of the base plan it was created from.
Details about how this variant relates to its latest base plan.
The ID of the base plan this variant was derived from.
The customization that transforms the base plan into this variant.
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.
Items to add to 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. 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.
Filters selecting items to remove from the plan.
Match items linked to this feature.
Match items with this billing method (prepaid or usage\_based).
Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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 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.
Plan-level billing controls used as customer defaults.
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.
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
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.
The IDs of the plans updated on this subscription.
```json 200 theme={null}
{
"customer_id": "cus_123",
"currency": "usd",
"total": -40,
"subscriptions": [
{
"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",
"plan_ids": [
"pro_plan"
]
},
{
"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",
"plan_ids": [
"addon_seats"
]
}
]
}
```
## OpenAPI
````yaml openapi POST /v1/billing.preview_multi_update
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.preview_multi_update:
post:
tags:
- billing
description: >-
Previews the billing changes of a multi-plan update without making any
changes. Returns one core preview per affected subscription.
Use this endpoint to show customers the credits and next-cycle changes
of canceling multiple plans before confirming.
operationId: previewMultiUpdate
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 update plans for.
entity_id:
type: string
description: >-
The ID of the entity to update plans for. Individual updates
can override this with their own entity_id.
updates:
type: array
minItems: 1
items:
type: object
properties:
plan_id:
type: string
description: >-
The ID of the plan to update. Optional if
subscription_id is provided.
subscription_id:
type: string
description: >-
A unique ID to identify the subscription to update.
Useful when a customer has multiple products with the
same plan.
entity_id:
type: string
description: >-
The ID of the entity this update targets. Overrides
the top-level entity_id for this update.
cancel_action:
enum:
- cancel_immediately
- cancel_end_of_cycle
- uncancel
type: string
title: CancelAction
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.
proration_behavior:
enum:
- prorate_immediately
- none
type: string
description: >-
How to handle proration for this update.
'prorate_immediately' charges/credits prorated amounts
now, 'none' skips creating any charges.
required:
- cancel_action
description: The list of plan updates to apply to the customer.
required:
- customer_id
- updates
title: PreviewMultiUpdateParams
examples:
- customer_id: cus_123
updates:
- plan_id: pro_plan
cancel_action: cancel_immediately
- plan_id: addon_seats
cancel_action: cancel_immediately
example:
customer_id: cus_123
updates:
- plan_id: pro_plan
cancel_action: cancel_immediately
- plan_id: addon_seats
cancel_action: cancel_immediately
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The ID of the customer the preview applies to.
currency:
type: string
description: The three-letter ISO currency code (e.g., 'usd').
total:
type: number
description: >-
The combined amount due today across all subscriptions
(sum of subscriptions[].total).
subscriptions:
type: array
items:
type: object
properties:
customer_id:
type: string
description: The ID of the customer.
line_items:
type: array
items:
type: object
properties:
display_name:
type: string
description: >-
The name of the line item to display to the
customer if you're building a UI. It will
either be the plan name or the feature name.
description:
type: string
description: A detailed description of the line item.
subtotal:
type: number
description: >-
The amount in cents before discounts and tax
for this line item.
total:
type: number
description: >-
The final amount in cents after discounts and
tax for this line item.
discounts:
type: array
items:
type: object
properties:
amount_off:
type: number
percent_off:
type: number
reward_id:
type: string
reward_name:
type: string
required:
- amount_off
default: []
description: List of discounts applied to this line item.
plan_id:
type: string
description: >-
The ID of the plan that this line item belongs
to.
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the feature that this line item
belongs to.
period:
type: object
properties:
start:
type: number
description: >-
The start of the period in milliseconds
since the Unix epoch.
end:
type: number
description: >-
The end of the period in milliseconds
since the Unix epoch.
required:
- start
- end
description: >-
The period of time that this line item is
being charged for.
quantity:
type: number
description: The quantity of the line item.
required:
- display_name
- description
- subtotal
- total
- plan_id
- feature_id
- quantity
description: List of line items for the current billing period.
subtotal:
type: number
description: >-
The total amount in cents before discounts and tax
for the current billing period.
total:
type: number
description: >-
The final amount in cents after discounts and tax
for the current billing period.
currency:
type: string
description: The three-letter ISO currency code (e.g., 'usd').
next_cycle:
type: object
properties:
starts_at:
type: number
description: >-
Unix timestamp (milliseconds) when the next
billing cycle starts.
subtotal:
type: number
description: >-
The total amount in cents before discounts and
tax for the next cycle.
total:
type: number
description: >-
The final amount in cents after discounts and
tax for the next cycle.
line_items:
type: array
items:
type: object
properties:
display_name:
type: string
description: >-
The name of the line item to display to
the customer if you're building a UI. It
will either be the plan name or the
feature name.
description:
type: string
description: A detailed description of the line item.
subtotal:
type: number
description: >-
The amount in cents before discounts and
tax for this line item.
total:
type: number
description: >-
The final amount in cents after discounts
and tax for this line item.
discounts:
type: array
items:
type: object
properties:
amount_off:
type: number
percent_off:
type: number
reward_id:
type: string
reward_name:
type: string
required:
- amount_off
default: []
description: >-
List of discounts applied to this line
item.
plan_id:
type: string
description: >-
The ID of the plan that this line item
belongs to.
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the feature that this line item
belongs to.
period:
type: object
properties:
start:
type: number
description: >-
The start of the period in milliseconds
since the Unix epoch.
end:
type: number
description: >-
The end of the period in milliseconds
since the Unix epoch.
required:
- start
- end
description: >-
The period of time that this line item is
being charged for.
quantity:
type: number
description: The quantity of the line item.
required:
- display_name
- description
- subtotal
- total
- plan_id
- feature_id
- quantity
description: List of line items for the next billing cycle.
usage_line_items:
type: array
items:
type: object
properties:
display_name:
type: string
description: >-
The name of the line item to display to
the customer if you're building a UI. It
will either be the plan name or the
feature name.
plan_id:
type: string
description: >-
The ID of the plan that this line item
belongs to.
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the feature that this line item
belongs to.
period:
type: object
properties:
start:
type: number
description: >-
The start of the period in milliseconds
since the Unix epoch.
end:
type: number
description: >-
The end of the period in milliseconds
since the Unix epoch.
required:
- start
- end
description: >-
The period of time that this line item is
being charged for.
required:
- display_name
- plan_id
- feature_id
description: >-
List of line items for usage-based features in
the next cycle.
required:
- starts_at
- subtotal
- total
- line_items
- usage_line_items
description: >-
Preview of the next billing cycle, if applicable.
This shows what the customer will be charged in
subsequent cycles.
expand:
type: array
items:
type: string
description: Expand the response with additional data.
incoming:
type: array
items:
type: object
properties:
plan_id:
type: string
description: >-
The ID of the plan affected by this preview
change.
plan:
$ref: '#/components/schemas/Plan'
description: >-
The full plan object if it was expanded in the
response.
feature_quantities:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The ID of the adjustable feature
included in this change.
quantity:
type: number
description: >-
The quantity that will apply for this
feature in the change.
required:
- feature_id
- quantity
description: >-
The feature quantity selections associated
with this plan change.
effective_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this change takes effect, in milliseconds
since the Unix epoch, or null if it applies
immediately.
canceled_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this plan was canceled, in milliseconds
since the Unix epoch, or null if it is not
canceled.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this plan expires, in milliseconds since
the Unix epoch, or null if it does not expire.
required:
- plan_id
- feature_quantities
- effective_at
- canceled_at
- expires_at
description: >-
Products or subscription changes being added or
updated.
outgoing:
type: array
items:
type: object
properties:
plan_id:
type: string
description: >-
The ID of the plan affected by this preview
change.
plan:
$ref: '#/components/schemas/Plan'
description: >-
The full plan object if it was expanded in the
response.
feature_quantities:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The ID of the adjustable feature
included in this change.
quantity:
type: number
description: >-
The quantity that will apply for this
feature in the change.
required:
- feature_id
- quantity
description: >-
The feature quantity selections associated
with this plan change.
effective_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this change takes effect, in milliseconds
since the Unix epoch, or null if it applies
immediately.
canceled_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this plan was canceled, in milliseconds
since the Unix epoch, or null if it is not
canceled.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
When this plan expires, in milliseconds since
the Unix epoch, or null if it does not expire.
required:
- plan_id
- feature_quantities
- effective_at
- canceled_at
- expires_at
description: >-
Products or subscription changes being removed or
ended.
plan_ids:
type: array
items:
type: string
description: The IDs of the plans updated on this subscription.
required:
- customer_id
- line_items
- subtotal
- total
- currency
- incoming
- outgoing
- plan_ids
description: >-
One preview per affected Stripe subscription. Updates to
plans without a subscription (free plans) produce no
entry.
required:
- customer_id
- currency
- total
- subscriptions
title: MultiUpdatePreviewResponse
examples:
- customer_id: cus_123
currency: usd
total: -40
subscriptions:
- 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
plan_ids:
- pro_plan
- 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
plan_ids:
- addon_seats
example:
customer_id: cus_123
currency: usd
total: -40
subscriptions:
- 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
plan_ids:
- pro_plan
- 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
plan_ids:
- addon_seats
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.previewMultiUpdate({
customerId: "cus_123",
updates: [
{
planId: "pro_plan",
cancelAction: "cancel_immediately",
},
{
planId: "addon_seats",
cancelAction: "cancel_immediately",
},
],
});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.preview_multi_update(
customer_id="cus_123",
updates=[
{
"plan_id": "pro_plan",
"cancel_action": "cancel_immediately",
},
{
"plan_id": "addon_seats",
"cancel_action": "cancel_immediately",
},
],
)
components:
schemas:
Plan:
type: object
properties:
id:
type: string
description: Unique identifier for the plan.
name:
type: string
description: Display name of the plan.
description:
anyOf:
- type: string
- type: 'null'
description: Optional description of the plan.
group:
anyOf:
- type: string
- type: 'null'
description: >-
Group identifier for organizing related plans. Plans in the same
group are mutually exclusive.
version:
type: number
description: >-
Version number of the plan. Incremented when plan configuration
changes.
add_on:
type: boolean
description: >-
Whether this is an add-on plan that can be attached alongside a main
plan.
auto_enable:
type: boolean
description: >-
If true, this plan is automatically attached when a customer is
created. Used for free plans.
price:
anyOf:
- type: object
properties:
amount:
type: number
description: Base price amount for the plan.
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: Billing interval (e.g. 'month', 'year').
interval_count:
type: number
description: Number of intervals per billing cycle. Defaults to 1.
display:
type: object
properties:
primary_text:
type: string
description: Main display text (e.g. '$10' or '100 messages').
secondary_text:
type: string
description: >-
Secondary display text (e.g. 'per month' or 'then $0.5
per 100').
required:
- primary_text
description: Display text for showing this price in pricing pages.
required:
- amount
- interval
- type: 'null'
description: >-
Base recurring price for the plan. Null for free plans or usage-only
plans.
items:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The ID of the feature this item configures.
feature:
type: object
properties:
id:
type: string
description: >-
The ID of the feature, used to refer to it in other API
calls like /track or /check.
name:
anyOf:
- type: string
- type: 'null'
description: The name of the feature.
type:
enum:
- static
- boolean
- single_use
- continuous_use
- credit_system
- ai_credit_system
type: string
description: The type of the feature
display:
anyOf:
- type: object
properties:
singular:
type: string
description: The singular display name for the feature.
plural:
type: string
description: The plural display name for the feature.
required:
- singular
- plural
- type: 'null'
description: Singular and plural display names for the feature.
credit_schema:
anyOf:
- type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
The ID of the metered feature (should be a
single_use feature).
credit_cost:
type: number
description: The credit cost of the metered feature.
required:
- metered_feature_id
- credit_cost
- type: 'null'
description: Credit cost schema for credit system features.
archived:
anyOf:
- type: boolean
- type: 'null'
description: Whether or not the feature is archived.
required:
- id
- type
description: The full feature object if expanded.
included:
type: number
description: >-
Number of free units included. For consumable features,
balance resets to this number each interval.
unlimited:
type: boolean
description: Whether the customer has unlimited access to this feature.
reset:
anyOf:
- type: object
properties:
interval:
enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
The interval at which the feature balance resets (e.g.
'month', 'year'). For consumable features, usage
resets to 0 and included units are restored.
interval_count:
type: number
description: Number of intervals between resets. Defaults to 1.
required:
- interval
- type: 'null'
description: >-
Reset configuration for consumable features. Null for
non-consumable features like seats where usage persists across
billing cycles.
price:
anyOf:
- type: object
properties:
amount:
type: number
description: >-
Price per billing_units after included usage is
consumed. Mutually exclusive with tiers.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
required:
- to
- amount
description: >-
Tiered pricing configuration. Each tier's 'to'
INCLUDES the included amount. Either 'tiers' or
'amount' is required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval for this price. For consumable
features, should match reset.interval.
interval_count:
type: number
description: Number of intervals per billing cycle. Defaults to 1.
billing_units:
type: number
description: >-
Number of units per price increment. Usage is rounded
UP to the nearest billing_units when billed (e.g.
billing_units=100 means 101 usage rounds to 200).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: >-
'prepaid' for features like seats where customers pay
upfront, 'usage_based' for pay-as-you-go after
included usage.
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum units a customer can purchase beyond included.
E.g. if included=100 and max_purchase=300, customer
can use up to 400 total before usage is capped. Null
for no limit.
required:
- interval
- billing_units
- billing_method
- max_purchase
- type: 'null'
description: >-
Pricing configuration for usage beyond included units. Null if
feature is entirely free.
display:
type: object
properties:
primary_text:
type: string
description: Main display text (e.g. '$10' or '100 messages').
secondary_text:
type: string
description: >-
Secondary display text (e.g. 'per month' or 'then $0.5 per
100').
required:
- primary_text
description: Display text for showing this item in pricing pages.
rollover:
type: object
properties:
max:
anyOf:
- type: number
- type: 'null'
description: Maximum rollover units. Null for unlimited rollover.
max_percentage:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum rollover as a percentage (0-100) of included +
prepaid grant. Mutually exclusive with max.
expiry_duration_type:
enum:
- month
- forever
type: string
description: When rolled over units expire.
expiry_duration_length:
type: number
description: Number of periods before expiry.
required:
- max
- expiry_duration_type
description: >-
Rollover configuration for unused units. If set, unused
included units roll over to the next period.
required:
- feature_id
- included
- unlimited
- reset
- price
description: >-
Feature configurations included in this plan. Each item defines
included units, pricing, and reset behavior for a feature.
free_trial:
type: object
properties:
duration_length:
type: number
description: Number of duration_type periods the trial lasts.
duration_type:
enum:
- day
- month
- year
type: string
description: Unit of time for the trial duration ('day', 'month', 'year').
card_required:
type: boolean
description: >-
Whether a payment method is required to start the trial. If
true, customer will be charged after trial ends.
on_end:
anyOf:
- enum:
- bill
- revert
type: string
- type: 'null'
description: >-
Behavior when the trial ends. 'bill' charges the customer
(default). 'revert' expires the trial and restores the
customer's previous plan.
required:
- duration_length
- duration_type
- card_required
description: >-
Free trial configuration. If set, new customers can try this plan
before being charged.
created_at:
type: number
description: Unix timestamp (ms) when the plan was created.
env:
enum:
- sandbox
- live
type: string
description: Environment this plan belongs to ('sandbox' or 'live').
archived:
type: boolean
description: >-
Whether the plan is archived. Archived plans cannot be attached to
new customers.
base_variant_id:
anyOf:
- type: string
- type: 'null'
description: >-
Deprecated. Use variant_details.base_plan_id instead. If this is a
variant, the ID of the base plan it was created from.
variant_details:
type: object
properties:
base_plan_id:
type: string
description: The ID of the base plan this variant was derived from.
customize:
type: object
properties:
price:
anyOf:
- type: object
properties:
amount:
type: number
description: Base price amount for the plan.
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: Billing interval (e.g. 'month', 'year').
interval_count:
type: number
description: >-
Number of intervals per billing cycle. Defaults to
1.
required:
- amount
- interval
title: BasePrice
description: Base price configuration for a plan.
- type: 'null'
description: >-
Override the base price of the plan. Pass null to remove the
base price.
add_items:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The ID of the feature to configure.
included:
type: number
description: >-
Number of free units included. Balance resets to this
each interval for consumable features.
unlimited:
type: boolean
description: >-
If true, customer has unlimited access to this
feature.
reset:
type: object
properties:
interval:
enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Interval at which balance resets (e.g. 'month',
'year'). For consumable features only.
interval_count:
type: number
description: Number of intervals between resets. Defaults to 1.
required:
- interval
description: >-
Reset configuration for consumable features. Omit for
non-consumable features like seats.
price:
type: object
properties:
amount:
type: number
description: >-
Price per billing_units after included usage.
Either 'amount' or 'tiers' is required.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
required:
- to
- amount
description: >-
Tiered pricing. Either 'amount' or 'tiers' is
required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable features, should
match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle. Defaults to
1.
billing_units:
type: number
default: 1
description: >-
Units per price increment. Usage is rounded UP
when billed (e.g. billing_units=100 means 101
rounds to 200).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: >-
'prepaid' for upfront payment (seats),
'usage_based' for pay-as-you-go.
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Max units purchasable beyond included. E.g.
included=100, max_purchase=300 allows 400 total.
Null for no limit.
required:
- interval
- billing_method
description: >-
Pricing for usage beyond included units. Omit for free
features.
proration:
type: object
properties:
on_increase:
enum:
- bill_immediately
- prorate_immediately
- prorate_next_cycle
- bill_next_cycle
type: string
description: >-
Billing behavior when quantity increases
mid-cycle.
on_decrease:
enum:
- prorate
- prorate_immediately
- prorate_next_cycle
- none
- no_prorations
type: string
description: Credit behavior when quantity decreases mid-cycle.
required:
- on_increase
- on_decrease
description: >-
Proration settings for prepaid features. Controls
mid-cycle quantity change billing.
rollover:
type: object
properties:
max:
type: number
description: Max rollover units. Omit for unlimited rollover.
max_percentage:
type: number
description: >-
Maximum rollover as a percentage (0-100) of
included + prepaid grant. Mutually exclusive with
max.
expiry_duration_type:
enum:
- month
- forever
type: string
description: When rolled over units expire.
expiry_duration_length:
type: number
description: Number of periods before expiry.
required:
- expiry_duration_type
description: >-
Rollover config for unused units. If set, unused
included units carry over.
required:
- feature_id
title: PlanItem
description: >-
Configuration for a feature item in a plan, including
usage limits, pricing, and rollover settings.
description: Items to add to the plan.
remove_items:
type: array
items:
type: object
properties:
feature_id:
type: string
description: Match items linked to this feature.
billing_method:
enum:
- prepaid
- usage_based
type: string
description: >-
Match items with this billing method (prepaid or
usage_based).
interval:
anyOf:
- enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
- enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Match items with this interval. Accepts either a
BillingInterval (price-side) or a ResetInterval
(reset-side, includes day/hour/minute) so price-less
items keyed by reset.interval can be disambiguated.
interval_count:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
exclusiveMinimum: 0
description: >-
Match items with this interval_count. Disambiguates
between items that share an interval but differ in
count.
title: PlanItemFilter
description: >-
Filter for matching plan items. All provided fields must
match (AND).
description: Filters selecting items to remove from the plan.
free_trial:
anyOf:
- type: object
properties:
duration_length:
type: number
description: Number of duration_type periods the trial lasts.
duration_type:
enum:
- day
- month
- year
type: string
default: month
description: Unit of time for the trial ('day', 'month', 'year').
card_required:
type: boolean
default: true
description: >-
If true, payment method required to start trial.
Customer is charged after trial ends.
on_end:
enum:
- bill
- revert
type: string
description: >-
Behavior when the trial ends. 'bill' charges the
customer (default). 'revert' expires the trial and
restores the customer's previous plan.
required:
- duration_length
title: FreeTrialParams
description: Free trial configuration for a plan.
- type: 'null'
description: >-
Override the plan's default free trial. Pass an object to
set a custom trial, or null to remove the trial entirely.
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: {}
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: >-
Override the plan's billing controls (auto top-ups, spend
limits, usage limits, usage alerts, overage allowed) for
this customer.
description: >-
The customization that transforms the base plan into this
variant.
required:
- base_plan_id
description: Details about how this variant relates to its latest base plan.
config:
type: object
properties:
ignore_past_due:
type: boolean
default: false
description: >-
If true, entitlements attached to this plan will still reset on
schedule even when the customer's product is in a past_due
state.
description: Miscellaneous plan-level configuration flags.
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: {}
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: Plan-level billing controls used as customer defaults.
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Arbitrary key-value metadata defined by you for your own use. Shared
across all versions of the plan.
customer_eligibility:
type: object
properties:
trial_available:
type: boolean
description: >-
Whether the trial on this plan is available to this customer.
For example, if the customer used the trial in the past, this
will be false.
status:
enum:
- active
- scheduled
type: string
description: >-
The customer's current status with this plan. 'active' if
attached, 'scheduled' if pending activation.
canceling:
type: boolean
description: >-
Whether the customer's active instance of this plan is set to
cancel.
trialing:
type: boolean
description: Whether the customer is currently on a free trial of this plan.
attach_action:
enum:
- activate
- upgrade
- downgrade
- none
- purchase
type: string
description: >-
The action that would occur if this plan were attached to the
customer.
required:
- attach_action
required:
- id
- name
- description
- group
- version
- add_on
- auto_enable
- price
- items
- created_at
- env
- archived
- base_variant_id
- config
- metadata
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````