> ## 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.
# Get or Create Customer
> Creates a customer if they do not exist, or returns the existing customer by your external customer ID.
Use this as the primary entrypoint before billing operations so the customer record is always present and up to date.
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}
;
};
If the customer already exists and you try to create it again, you will simply be returned the customer object (rather than an error being thrown).
### Currency
Pass `currency` to bill this customer in a currency other than your organization's default. Their plans must offer a price in that currency via [`additional_currencies`](/documentation/concepts/plans#multiple-currencies). If omitted, the customer's currency is set by their first paid attach.
### Body Parameters
Your unique identifier for the 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. Pass count to set the current window's consumed top-ups.
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.
Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
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.
Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature.
### Response
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the 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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Current usage already consumed in the active interval. Response-only; not stored on billing controls.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if expanded.
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.
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.
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.
Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers' (tiered prices carry per-currency amounts on each tier).
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 configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Per-unit amount for this tier in this currency.
Flat amount for this tier in this currency, if the tier uses one.
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.
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.
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.
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.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Per-unit amount for this tier in this currency.
Flat amount for this tier in this currency, if the tier uses one.
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. Pass count to set the current window's consumed top-ups.
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.
Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if expanded.
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.
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.
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.
Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers' (tiered prices carry per-currency amounts on each tier).
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 configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Per-unit amount for this tier in this currency.
Flat amount for this tier in this currency, if the tier uses one.
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.
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.
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.
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.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Per-unit amount for this tier in this currency.
Flat amount for this tier in this currency, if the tier uses one.
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. Pass count to set the current window's consumed top-ups.
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.
Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit\_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For credit\_system features: maps metered features to their credit costs.
ID of the metered feature that draws from this credit system.
Credits consumed per unit of the metered feature.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Configuration 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.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
Invoices for this customer.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
Entities associated with this customer.
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
Trial usage history for this customer.
Rewards earned or applied for this customer.
Array of active discounts applied to the customer
The unique identifier for this discount
The name of the discount or coupon
The type of reward
The discount value (percentage or fixed amount)
How long the discount lasts
Number of billing periods the discount applies for repeating durations
The currency code for fixed amount discounts
Timestamp when the discount becomes active
Timestamp when the discount expires
The Stripe subscription ID this discount is applied to
Total amount saved from this discount
Referral records for this customer.
The customer's default payment method.
```json 200 theme={null}
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"licenses": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
```
## OpenAPI
````yaml openapi POST /v1/customers.get_or_create
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/customers.get_or_create:
post:
tags:
- customers
description: >-
Creates a customer if they do not exist, or returns the existing
customer by your external customer ID.
Use this as the primary entrypoint before billing operations so the
customer record is always present and up to date.
operationId: getOrCreateCustomer
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:
anyOf:
- $ref: '#/components/schemas/CustomerId'
- type: 'null'
name:
anyOf:
- type: string
- type: 'null'
description: Customer's name
email:
anyOf:
- type: string
format: email
- type: 'null'
description: Customer's email address
fingerprint:
anyOf:
- type: string
- type: 'null'
description: >-
Unique identifier (eg, serial number) to detect duplicate
customers and prevent free trial abuse
metadata:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: 'null'
description: Additional metadata for the customer
stripe_id:
anyOf:
- type: string
- type: 'null'
description: Stripe customer ID if you already have one
create_in_stripe:
type: boolean
description: Whether to create the customer in Stripe
auto_enable_plan_id:
type: string
description: The ID of the free plan to auto-enable for the customer
send_email_receipts:
type: boolean
description: Whether to send email receipts to this customer
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
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.
count:
type: number
minimum: 0
description: >-
Set the current window's consumed auto top-up
count. Omit to leave runtime state unchanged.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often auto top-ups
occur. Pass count to set the current window's
consumed top-ups.
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.
expand:
type: array
items:
$ref: '#/components/schemas/CustomerExpand'
description: >-
Fields to expand in the returned customer response, such as
subscriptions.plan, purchases.plan, balances.feature, or
flags.feature.
required:
- customer_id
title: GetOrCreateCustomerParams
examples:
- customer_id: cus_123
name: John Doe
email: john@example.com
example:
customer_id: cus_123
name: John Doe
email: john@example.com
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
example:
id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
name: Patrick
email: patrick@useautumn.com
createdAt: 1771409161016
fingerprint: null
stripeId: cus_U0BKxpq1mFhuJO
processors:
stripe:
id: cus_U0BKxpq1mFhuJO
env: sandbox
metadata: {}
sendEmailReceipts: false
billingControls:
autoTopups: []
subscriptions:
- planId: pro_plan
autoEnable: true
addOn: false
status: active
pastDue: false
canceledAt: null
expiresAt: null
trialEndsAt: null
startedAt: 1771431921437
currentPeriodStart: 1771431921437
currentPeriodEnd: 1771999921437
quantity: 1
purchases: []
licenses: []
balances:
messages:
featureId: messages
granted: 100
remaining: 0
usage: 100
unlimited: false
overageAllowed: false
maxPurchase: null
nextResetAt: 1773851121437
breakdown:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
planId: pro_plan
includedGrant: 100
prepaidGrant: 0
remaining: 0
usage: 100
unlimited: false
reset:
interval: month
resetsAt: 1773851121437
price: null
expiresAt: null
flags:
advanced_workflows:
id: cus_ent_abc123
plan_id: pro_plan
expires_at: null
feature_id: advanced_workflows
config:
disable_pooled_balance: false
disable_overage_billing: false
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.customers.getOrCreate({
customerId: "cus_123",
name: "John Doe",
email: "john@example.com",
});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.customers.get_or_create(
customer_id="cus_123",
name="John Doe",
email="john@example.com",
)
components:
schemas:
CustomerId:
type: string
title: CustomerId
description: Your unique identifier for the customer
CustomerExpand:
enum:
- invoices
- trials_used
- rewards
- entities
- referrals
- payment_method
- subscriptions.plan
- purchases.plan
- balances.feature
- flags.feature
- billing_controls.auto_topups.purchase_limit
type: string
title: CustomerExpand
Customer:
type: object
properties:
id:
anyOf:
- type: string
- type: 'null'
description: Your unique identifier for the customer.
name:
anyOf:
- type: string
- type: 'null'
description: The name of the customer.
email:
anyOf:
- type: string
- type: 'null'
description: The email address of the customer.
created_at:
type: number
description: Timestamp of customer creation in milliseconds since epoch.
fingerprint:
anyOf:
- type: string
- type: 'null'
description: >-
A unique identifier (eg. serial number) to de-duplicate customers
across devices or browsers. For example: apple device ID.
stripe_id:
anyOf:
- type: string
- type: 'null'
description: Stripe customer ID.
env:
enum:
- sandbox
- live
type: string
description: The environment this customer was created in.
metadata:
type: object
propertyNames: {}
additionalProperties: {}
description: The metadata for the customer.
send_email_receipts:
type: boolean
description: Whether to send email receipts to the customer.
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
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:
anyOf:
- type: object
properties:
interval:
anyOf:
- enum:
- hour
- day
- week
- month
type: string
- type: 'null'
description: >-
The time interval for the purchase limit window.
Null when no purchase limit is configured.
interval_count:
anyOf:
- type: number
minimum: 1
- type: 'null'
description: >-
Number of intervals in the purchase limit window.
Null when no purchase limit is configured.
limit:
anyOf:
- type: number
minimum: 1
- type: 'null'
description: >-
Maximum number of auto top-ups allowed within the
interval. Null when no purchase limit is
configured.
count:
type: number
description: >-
Number of auto top-ups already consumed in the
current window.
next_reset_at:
type: number
description: >-
Unix ms timestamp when the current purchase window
ends and the count resets.
required:
- interval
- interval_count
- limit
- count
- next_reset_at
- 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.
Expand billing_controls.auto_topups.purchase_limit for a
count of top ups and the next_reset_at.
invoice_mode:
type: boolean
description: >-
When true, auto top-up creates a send_invoice invoice
instead of auto-charging.
source:
enum:
- customer
- plan
type: string
description: >-
Response-only: whether the entry is a customer-level
override or inherited from an attached plan's defaults.
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.
source:
enum:
- customer
- plan
type: string
description: >-
Response-only: whether the entry is a customer-level
override or inherited from an attached plan's defaults.
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.
usage:
type: number
minimum: 0
description: >-
Current usage already consumed in the active interval.
Response-only; not stored on billing controls.
source:
enum:
- customer
- plan
type: string
description: >-
Response-only: whether the entry is a customer-level
override or inherited from an attached plan's defaults.
required:
- feature_id
- limit
- interval
description: >-
List of hard usage caps per feature, with current interval
usage.
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.
source:
enum:
- customer
- plan
type: string
description: >-
Response-only: whether the entry is a customer-level
override or inherited from an attached plan's defaults.
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.
source:
enum:
- customer
- plan
type: string
description: >-
Response-only: whether the entry is a customer-level
override or inherited from an attached plan's defaults.
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.)
subscriptions:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The unique identifier of this subscription. If a
subscription_id was provided at attach time, it is used;
otherwise, falls back to the internal ID.
plan:
$ref: '#/components/schemas/Plan'
description: The full plan object if expanded.
plan_id:
type: string
description: The unique identifier of the subscribed plan.
auto_enable:
type: boolean
description: Whether the plan was automatically enabled for the customer.
add_on:
type: boolean
description: >-
Whether this is an add-on plan rather than a base
subscription.
status:
enum:
- active
- scheduled
type: string
description: Current status of the subscription.
past_due:
type: boolean
description: Whether the subscription has overdue payments.
canceled_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when the subscription was canceled, or null if not
canceled.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when the subscription will expire, or null if no
expiry set.
trial_ends_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the trial period ends, or null if not on trial.
started_at:
type: number
description: Timestamp when the subscription started.
current_period_start:
anyOf:
- type: number
- type: 'null'
description: Start timestamp of the current billing period.
current_period_end:
anyOf:
- type: number
- type: 'null'
description: End timestamp of the current billing period.
quantity:
type: number
description: Number of units of this subscription (for per-seat plans).
scope:
enum:
- customer
- entity
type: string
description: >-
Whether this subscription is attached at the customer level or
entity level.
required:
- id
- plan_id
- auto_enable
- add_on
- status
- past_due
- canceled_at
- expires_at
- trial_ends_at
- started_at
- current_period_start
- current_period_end
- quantity
description: >-
Active and scheduled recurring plans that this customer has
attached.
purchases:
type: array
items:
type: object
properties:
plan:
$ref: '#/components/schemas/Plan'
description: The full plan object if expanded.
plan_id:
type: string
description: The unique identifier of the purchased plan.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when the purchase expires, or null for lifetime
access.
started_at:
type: number
description: Timestamp when the purchase was made.
quantity:
type: number
description: Number of units purchased.
scope:
enum:
- customer
- entity
type: string
description: >-
Whether this purchase is attached at the customer level or
entity level.
required:
- plan_id
- expires_at
- started_at
- quantity
description: One-time purchases made by the customer.
licenses:
type: array
items:
type: object
properties:
license_plan_id:
type: string
description: The plan offered as an assignable license.
parent_plan_id:
type: string
description: The plan that offers this license.
license_plan_name:
type: string
description: Display name of the license plan.
granted:
type: number
description: >-
Total seats the customer has for this license, included plus
paid.
usage:
type: number
description: Seats currently assigned to entities.
remaining:
type: number
description: Seats still available to assign.
paid_quantity:
type: number
description: Paid seats purchased on top of the plan's included amount.
required:
- license_plan_id
- parent_plan_id
- license_plan_name
- granted
- usage
- remaining
- paid_quantity
description: >-
License seat pools granted by the customer's plans, with seat
counts.
balances:
type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/Balance'
description: >-
Feature balances keyed by feature ID, showing usage limits and
remaining amounts.
flags:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
id:
type: string
description: The unique identifier for this flag.
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan ID this flag originates from, or null for standalone
flags.
expires_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when this flag expires, or null for no expiration.
feature_id:
type: string
description: The feature ID this flag is for.
feature:
type: object
properties:
id:
type: string
description: >-
The unique identifier for this feature, used in /check and
/track calls.
name:
type: string
description: >-
Human-readable name displayed in the dashboard and billing
UI.
type:
enum:
- boolean
- metered
- credit_system
- ai_credit_system
type: string
description: >-
Feature type: 'boolean' for on/off access, 'metered' for
usage-tracked features, 'credit_system' for unified credit
pools, 'ai_credit_system' for model-based token pricing.
consumable:
type: boolean
description: >-
For metered features: true if usage resets periodically
(API calls, credits), false if allocated persistently
(seats, storage).
event_names:
type: array
items:
type: string
description: >-
Event names that trigger this feature's balance. Allows
multiple features to respond to a single event.
credit_schema:
type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
ID of the metered feature that draws from this
credit system.
credit_cost:
type: number
description: Credits consumed per unit of the metered feature.
required:
- metered_feature_id
- credit_cost
description: >-
For credit_system features: maps metered features to their
credit costs.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
input_cost:
type: number
minimum: 0
output_cost:
type: number
minimum: 0
- type: 'null'
description: Per-model markup overrides for AI credit systems.
default_markup:
type: number
minimum: -100
description: >-
Default percentage markup for AI credit systems. Use -100
to make usage free.
provider_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
required:
- markup
- type: 'null'
description: >-
Per-provider default markup percentages for AI credit
systems.
display:
type: object
properties:
singular:
anyOf:
- type: string
- type: 'null'
description: >-
Singular form for UI display (e.g., 'API call',
'seat').
plural:
anyOf:
- type: string
- type: 'null'
description: >-
Plural form for UI display (e.g., 'API calls',
'seats').
description: >-
Display names for the feature in billing UI and
customer-facing components.
archived:
type: boolean
description: >-
Whether the feature is archived and hidden from the
dashboard.
required:
- id
- name
- type
- consumable
- archived
description: The full feature object if expanded.
required:
- id
- plan_id
- expires_at
- feature_id
examples:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
plan_id: pro_plan
expires_at: null
feature_id: dashboard
description: >-
Boolean feature flags keyed by feature ID, showing enabled access
for on/off features.
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: Configuration for the customer.
processors:
type: object
properties:
stripe:
type: object
properties:
id:
type: string
description: Stripe customer ID.
required:
- id
description: Stripe processor connection for the customer.
vercel:
type: object
properties:
installation_id:
type: string
description: Vercel marketplace installation ID for this customer.
account_id:
type: string
description: Vercel account ID associated with the installation.
required:
- installation_id
- account_id
description: >-
Vercel processor connection for the customer (public-safe
subset).
revenuecat:
type: object
properties:
id:
anyOf:
- type: string
- type: 'null'
description: >-
Customer's external ID, used as the RevenueCat app user ID.
Null if the customer has no external ID set.
required:
- id
description: RevenueCat processor connection for the customer.
description: >-
Payment processors this customer is connected to (Stripe, Vercel,
RevenueCat). Omitted entirely when the customer has not been created
in any processor.
invoices:
type: array
items:
type: object
properties:
plan_ids:
type: array
items:
type: string
description: Array of plan IDs included in this invoice
stripe_id:
type: string
description: The Stripe invoice ID
processor_type:
enum:
- stripe
- revenuecat
type: string
default: stripe
description: The billing processor that owns this invoice.
status:
type: string
description: The status of the invoice
total:
type: number
description: The total amount of the invoice
currency:
type: string
description: The currency code for the invoice
created_at:
type: number
description: Timestamp when the invoice was created
hosted_invoice_url:
anyOf:
- type: string
- type: 'null'
description: URL to the Stripe-hosted invoice page
required:
- plan_ids
- stripe_id
- status
- total
- currency
- created_at
description: Invoices for this customer.
entities:
type: array
items:
type: object
properties:
id:
anyOf:
- type: string
- type: 'null'
description: The unique identifier of the entity
name:
anyOf:
- type: string
- type: 'null'
description: The name of the entity
customer_id:
anyOf:
- type: string
- type: 'null'
description: The customer ID this entity belongs to
feature_id:
anyOf:
- type: string
- type: 'null'
description: The feature ID this entity belongs to
created_at:
type: number
description: Unix timestamp when the entity was created
env:
enum:
- sandbox
- live
type: string
description: The environment (sandbox/live)
required:
- id
- name
- created_at
- env
description: Entities associated with this customer.
trials_used:
type: array
items:
type: object
properties:
plan_id:
type: string
customer_id:
type: string
fingerprint:
anyOf:
- type: string
- type: 'null'
required:
- plan_id
- customer_id
description: Trial usage history for this customer.
rewards:
anyOf:
- type: object
properties:
discounts:
type: array
items:
type: object
properties:
id:
type: string
description: The unique identifier for this discount
name:
type: string
description: The name of the discount or coupon
type:
enum:
- percentage_discount
- fixed_discount
- free_product
- invoice_credits
- feature_grant
type: string
description: The type of reward
discount_value:
type: number
description: The discount value (percentage or fixed amount)
duration_type:
enum:
- one_off
- months
- forever
type: string
description: How long the discount lasts
duration_value:
anyOf:
- type: number
- type: 'null'
description: >-
Number of billing periods the discount applies for
repeating durations
currency:
anyOf:
- type: string
- type: 'null'
description: The currency code for fixed amount discounts
start:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the discount becomes active
end:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the discount expires
subscription_id:
anyOf:
- type: string
- type: 'null'
description: The Stripe subscription ID this discount is applied to
total_discount_amount:
anyOf:
- type: number
- type: 'null'
description: Total amount saved from this discount
required:
- id
- name
- type
- discount_value
- duration_type
description: Array of active discounts applied to the customer
required:
- discounts
- type: 'null'
description: Rewards earned or applied for this customer.
referrals:
type: array
items:
type: object
properties:
program_id:
type: string
customer:
type: object
properties:
id:
type: string
name:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
required:
- id
reward_applied:
type: boolean
created_at:
type: number
required:
- program_id
- customer
- reward_applied
- created_at
description: Referral records for this customer.
payment_method:
anyOf:
- {}
- type: 'null'
description: The customer's default payment method.
required:
- id
- name
- email
- created_at
- fingerprint
- stripe_id
- env
- metadata
- send_email_receipts
- billing_controls
- subscriptions
- purchases
- licenses
- balances
- flags
examples:
- id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
name: Patrick
email: patrick@useautumn.com
createdAt: 1771409161016
fingerprint: null
stripeId: cus_U0BKxpq1mFhuJO
processors:
stripe:
id: cus_U0BKxpq1mFhuJO
env: sandbox
metadata: {}
sendEmailReceipts: false
billingControls:
autoTopups: []
subscriptions:
- planId: pro_plan
autoEnable: true
addOn: false
status: active
pastDue: false
canceledAt: null
expiresAt: null
trialEndsAt: null
startedAt: 1771431921437
currentPeriodStart: 1771431921437
currentPeriodEnd: 1771999921437
quantity: 1
purchases: []
licenses: []
balances:
messages:
featureId: messages
granted: 100
remaining: 0
usage: 100
unlimited: false
overageAllowed: false
maxPurchase: null
nextResetAt: 1773851121437
breakdown:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
planId: pro_plan
includedGrant: 100
prepaidGrant: 0
remaining: 0
usage: 100
unlimited: false
reset:
interval: month
resetsAt: 1773851121437
price: null
expiresAt: null
flags:
advanced_workflows:
id: cus_ent_abc123
plan_id: pro_plan
expires_at: null
feature_id: advanced_workflows
config:
disable_pooled_balance: false
disable_overage_billing: false
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.
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.
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.
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' (tiered prices
carry per-currency amounts on each tier).
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:
type: string
description: >-
Three-letter Stripe-supported currency
code (e.g. 'eur', 'gbp').
amount:
type: number
description: >-
Per-unit amount for this tier in this
currency.
flat_amount:
type: number
description: >-
Flat amount for this tier in this
currency, if the tier uses one.
required:
- currency
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.
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.
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.
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:
type: string
description: >-
Three-letter Stripe-supported currency
code (e.g. 'eur', 'gbp').
amount:
type: number
description: >-
Per-unit amount for this tier in this
currency.
flat_amount:
type: number
description: >-
Flat amount for this tier in this
currency, if the tier uses one.
required:
- currency
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
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.
count:
type: number
minimum: 0
description: >-
Set the current window's consumed auto top-up
count. Omit to leave runtime state unchanged.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often auto top-ups
occur. Pass count to set the current window's
consumed top-ups.
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.
additionalProperties: false
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
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
Balance:
type: object
properties:
feature_id:
type: string
description: The feature ID this balance is for.
feature:
type: object
properties:
id:
type: string
description: >-
The unique identifier for this feature, used in /check and
/track calls.
name:
type: string
description: Human-readable name displayed in the dashboard and billing UI.
type:
enum:
- boolean
- metered
- credit_system
- ai_credit_system
type: string
description: >-
Feature type: 'boolean' for on/off access, 'metered' for
usage-tracked features, 'credit_system' for unified credit
pools, 'ai_credit_system' for model-based token pricing.
consumable:
type: boolean
description: >-
For metered features: true if usage resets periodically (API
calls, credits), false if allocated persistently (seats,
storage).
event_names:
type: array
items:
type: string
description: >-
Event names that trigger this feature's balance. Allows multiple
features to respond to a single event.
credit_schema:
type: array
items:
type: object
properties:
metered_feature_id:
type: string
description: >-
ID of the metered feature that draws from this credit
system.
credit_cost:
type: number
description: Credits consumed per unit of the metered feature.
required:
- metered_feature_id
- credit_cost
description: >-
For credit_system features: maps metered features to their
credit costs.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
input_cost:
type: number
minimum: 0
output_cost:
type: number
minimum: 0
- type: 'null'
description: Per-model markup overrides for AI credit systems.
default_markup:
type: number
minimum: -100
description: >-
Default percentage markup for AI credit systems. Use -100 to
make usage free.
provider_markups:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
markup:
type: number
minimum: -100
required:
- markup
- type: 'null'
description: Per-provider default markup percentages for AI credit systems.
display:
type: object
properties:
singular:
anyOf:
- type: string
- type: 'null'
description: Singular form for UI display (e.g., 'API call', 'seat').
plural:
anyOf:
- type: string
- type: 'null'
description: Plural form for UI display (e.g., 'API calls', 'seats').
description: >-
Display names for the feature in billing UI and customer-facing
components.
archived:
type: boolean
description: Whether the feature is archived and hidden from the dashboard.
required:
- id
- name
- type
- consumable
- archived
description: The full feature object if expanded.
granted:
type: number
description: Total balance granted (included + prepaid).
remaining:
type: number
minimum: 0
description: Remaining balance available for use.
usage:
type: number
description: Total usage consumed in the current period.
unlimited:
type: boolean
description: Whether this feature has unlimited usage.
overage_allowed:
type: boolean
description: >-
Whether usage beyond the granted balance is allowed (with overage
charges).
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum quantity that can be purchased as a top-up, or null for
unlimited.
next_reset_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the balance will reset, or null for no reset.
breakdown:
type: array
items:
type: object
properties:
id:
type: string
default: ''
description: The unique identifier for this balance breakdown.
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan ID this balance originates from, or null for
standalone balances.
included_grant:
type: number
description: Amount granted from the plan's included usage.
prepaid_grant:
type: number
description: Amount granted from prepaid purchases or top-ups.
remaining:
type: number
description: Remaining balance available for use.
usage:
type: number
description: Amount consumed in the current period.
unlimited:
type: boolean
description: Whether this balance has unlimited usage.
reset:
anyOf:
- type: object
properties:
interval:
anyOf:
- enum:
- one_off
- minute
- hour
- day
- week
- month
- quarter
- semi_annual
- year
type: string
- const: multiple
description: >-
The reset interval (hour, day, week, month, etc.) or
'multiple' if combined from different intervals.
interval_count:
type: number
description: >-
Number of intervals between resets (eg. 2 for
bi-monthly).
resets_at:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the balance will next reset.
required:
- interval
- resets_at
- type: 'null'
description: Reset configuration for this balance, or null if no reset.
price:
anyOf:
- type: object
properties:
amount:
type: number
description: The per-unit price amount.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
required:
- to
- amount
description: Tiered pricing configuration if applicable.
tier_behavior:
enum:
- graduated
- volume
type: string
description: >-
How tiers are applied: graduated (split across bands)
or volume (flat rate for the matched tier).
billing_units:
type: number
description: >-
The number of units per billing increment (eg. $9 /
250 units).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: Whether usage is prepaid or billed pay-per-use.
max_purchase:
anyOf:
- type: number
- type: 'null'
description: >-
Maximum quantity that can be purchased, or null for
unlimited.
required:
- billing_units
- billing_method
- max_purchase
- type: 'null'
description: Pricing configuration if this balance has usage-based pricing.
expires_at:
anyOf:
- type: number
- type: 'null'
description: >-
Timestamp when this balance expires, or null for no
expiration.
required:
- plan_id
- included_grant
- prepaid_grant
- remaining
- usage
- unlimited
- reset
- price
- expires_at
description: >-
Detailed breakdown of balance sources when stacking multiple plans
or grants.
rollovers:
type: array
items:
type: object
properties:
balance:
type: number
description: Amount of balance rolled over from a previous period.
expires_at:
type: number
description: Timestamp when the rollover balance expires.
required:
- balance
- expires_at
description: Rollover balances carried over from previous periods.
required:
- feature_id
- granted
- remaining
- usage
- unlimited
- overage_allowed
- max_purchase
- next_reset_at
examples:
- feature_id: messages
granted: 100
remaining: 72
usage: 28
unlimited: false
overage_allowed: false
max_purchase: null
next_reset_at: 1773851121437
breakdown:
- id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
plan_id: pro_plan
included_grant: 100
prepaid_grant: 0
remaining: 72
usage: 28
unlimited: false
reset:
interval: month
resets_at: 1773851121437
price: null
expires_at: null
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````