autumn-js
Version:
Autumn JS Library
1,540 lines (1,537 loc) • 327 kB
text/typescript
import { C as ClosedEnum, O as OpenEnum, a as Balance, P as Plan } from './plan-CUExbmy9.mjs';
/**
* Time range to aggregate events for. Either range or custom_range must be provided
*/
declare const Range: {
readonly TwentyFourh: "24h";
readonly Sevend: "7d";
readonly Thirtyd: "30d";
readonly Ninetyd: "90d";
readonly LastCycle: "last_cycle";
readonly Onebc: "1bc";
readonly Threebc: "3bc";
};
/**
* Time range to aggregate events for. Either range or custom_range must be provided
*/
type Range = ClosedEnum<typeof Range>;
/**
* Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
*/
declare const BinSize: {
readonly Day: "day";
readonly Hour: "hour";
readonly Week: "week";
readonly Month: "month";
};
/**
* Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
*/
type BinSize = ClosedEnum<typeof BinSize>;
/**
* Custom time range to aggregate events for. If provided, range must not be provided
*/
type AggregateEventsCustomRange = {
start: number;
end: number;
};
type EventsAggregateParams = {
/**
* Customer ID to aggregate events for
*/
customerId?: string | undefined;
/**
* Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits)
*/
entityId?: string | undefined;
/**
* Feature ID(s) to aggregate events for
*/
featureId: string | Array<string>;
/**
* Property to group events by (e.g. "properties.region"), or "$customer_id" / "$entity_id" / "$plan_id" to group by those columns
*/
groupBy?: string | undefined;
/**
* Time range to aggregate events for. Either range or custom_range must be provided
*/
range?: Range | undefined;
/**
* Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
*/
binSize?: BinSize | undefined;
/**
* Custom time range to aggregate events for. If provided, range must not be provided
*/
customRange?: AggregateEventsCustomRange | undefined;
/**
* Filter events by property values, e.g. {"model": "gpt-4", "region": "us"}. Maximum 5 filters.
*/
filterBy?: {
[k: string]: string;
} | undefined;
/**
* Maximum number of distinct group values to return per time bin when using group_by. Remaining values are bundled into an 'Other' bucket. Defaults to 9
*/
maxGroups?: number | undefined;
};
type AggregateEventsList = {
/**
* Unix timestamp (epoch ms) for this time period
*/
period: number;
/**
* Aggregated values per feature: { [featureId]: number }
*/
values: {
[k: string]: number;
};
/**
* Values broken down by group (only present when group_by is used): { [featureId]: { [groupValue]: number } }
*/
groupedValues?: {
[k: string]: {
[k: string]: number;
};
} | undefined;
};
type Total = {
/**
* Number of events for this feature
*/
count: number;
/**
* Sum of event values for this feature
*/
sum: number;
};
/**
* OK
*/
type AggregateEventsResponse = {
/**
* Array of time periods with aggregated values
*/
list: Array<AggregateEventsList>;
/**
* Total aggregations per feature. Keys are feature IDs, values contain count and sum.
*/
total: {
[k: string]: Total;
};
};
/**
* Quantity configuration for a prepaid feature.
*/
type AttachFeatureQuantity = {
/**
* The ID of the feature to set quantity for.
*/
featureId: string;
/**
* The quantity of the feature.
*/
quantity?: number | undefined;
/**
* Whether the customer can adjust the quantity.
*/
adjustable?: boolean | undefined;
};
/**
* Billing interval (e.g. 'month', 'year').
*/
declare const AttachPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval (e.g. 'month', 'year').
*/
type AttachPriceInterval = ClosedEnum<typeof AttachPriceInterval>;
/**
* Base price configuration for a plan.
*/
type AttachBasePrice = {
/**
* Base price amount for the plan.
*/
amount: number;
/**
* Billing interval (e.g. 'month', 'year').
*/
interval: AttachPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
declare const AttachItemResetInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
type AttachItemResetInterval = ClosedEnum<typeof AttachItemResetInterval>;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
type AttachItemReset = {
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
interval: AttachItemResetInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type AttachItemTier = {
to: number | string;
amount?: number | undefined;
flatAmount?: number | undefined;
};
declare const AttachItemTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type AttachItemTierBehavior = ClosedEnum<typeof AttachItemTierBehavior>;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
declare const AttachItemPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval. For consumable features, should match reset.interval.
*/
type AttachItemPriceInterval = ClosedEnum<typeof AttachItemPriceInterval>;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
declare const AttachItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
type AttachItemBillingMethod = ClosedEnum<typeof AttachItemBillingMethod>;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
type AttachItemPrice = {
/**
* Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
*/
amount?: number | undefined;
/**
* Tiered pricing. Either 'amount' or 'tiers' is required.
*/
tiers?: Array<AttachItemTier> | undefined;
tierBehavior?: AttachItemTierBehavior | undefined;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
interval: AttachItemPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
/**
* Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
*/
billingUnits?: number | undefined;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
billingMethod: AttachItemBillingMethod;
/**
* Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
*/
maxPurchase?: number | null | undefined;
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
declare const AttachItemOnIncrease: {
readonly BillImmediately: "bill_immediately";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly BillNextCycle: "bill_next_cycle";
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
type AttachItemOnIncrease = ClosedEnum<typeof AttachItemOnIncrease>;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
declare const AttachItemOnDecrease: {
readonly Prorate: "prorate";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly None: "none";
readonly NoProrations: "no_prorations";
};
/**
* Credit behavior when quantity decreases mid-cycle.
*/
type AttachItemOnDecrease = ClosedEnum<typeof AttachItemOnDecrease>;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
type AttachItemProration = {
/**
* Billing behavior when quantity increases mid-cycle.
*/
onIncrease: AttachItemOnIncrease;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
onDecrease: AttachItemOnDecrease;
};
/**
* When rolled over units expire.
*/
declare const AttachItemExpiryDurationType: {
readonly Month: "month";
readonly Forever: "forever";
};
/**
* When rolled over units expire.
*/
type AttachItemExpiryDurationType = ClosedEnum<typeof AttachItemExpiryDurationType>;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
type AttachItemRollover = {
/**
* Max rollover units. Omit for unlimited rollover.
*/
max?: number | undefined;
/**
* Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
*/
maxPercentage?: number | undefined;
/**
* When rolled over units expire.
*/
expiryDurationType: AttachItemExpiryDurationType;
/**
* Number of periods before expiry.
*/
expiryDurationLength?: number | undefined;
};
/**
* Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings.
*/
type AttachItemPlanItem = {
/**
* The ID of the feature to configure.
*/
featureId: string;
/**
* Number of free units included. Balance resets to this each interval for consumable features.
*/
included?: number | undefined;
/**
* If true, customer has unlimited access to this feature.
*/
unlimited?: boolean | undefined;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
reset?: AttachItemReset | undefined;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
price?: AttachItemPrice | undefined;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
proration?: AttachItemProration | undefined;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
rollover?: AttachItemRollover | undefined;
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
declare const AttachAddItemResetInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
type AttachAddItemResetInterval = ClosedEnum<typeof AttachAddItemResetInterval>;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
type AttachAddItemReset = {
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
interval: AttachAddItemResetInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type AttachAddItemTier = {
to: number | string;
amount?: number | undefined;
flatAmount?: number | undefined;
};
declare const AttachAddItemTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type AttachAddItemTierBehavior = ClosedEnum<typeof AttachAddItemTierBehavior>;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
declare const AttachAddItemPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval. For consumable features, should match reset.interval.
*/
type AttachAddItemPriceInterval = ClosedEnum<typeof AttachAddItemPriceInterval>;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
declare const AttachAddItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
type AttachAddItemBillingMethod = ClosedEnum<typeof AttachAddItemBillingMethod>;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
type AttachAddItemPrice = {
/**
* Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
*/
amount?: number | undefined;
/**
* Tiered pricing. Either 'amount' or 'tiers' is required.
*/
tiers?: Array<AttachAddItemTier> | undefined;
tierBehavior?: AttachAddItemTierBehavior | undefined;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
interval: AttachAddItemPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
/**
* Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
*/
billingUnits?: number | undefined;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
billingMethod: AttachAddItemBillingMethod;
/**
* Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
*/
maxPurchase?: number | null | undefined;
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
declare const AttachAddItemOnIncrease: {
readonly BillImmediately: "bill_immediately";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly BillNextCycle: "bill_next_cycle";
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
type AttachAddItemOnIncrease = ClosedEnum<typeof AttachAddItemOnIncrease>;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
declare const AttachAddItemOnDecrease: {
readonly Prorate: "prorate";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly None: "none";
readonly NoProrations: "no_prorations";
};
/**
* Credit behavior when quantity decreases mid-cycle.
*/
type AttachAddItemOnDecrease = ClosedEnum<typeof AttachAddItemOnDecrease>;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
type AttachAddItemProration = {
/**
* Billing behavior when quantity increases mid-cycle.
*/
onIncrease: AttachAddItemOnIncrease;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
onDecrease: AttachAddItemOnDecrease;
};
/**
* When rolled over units expire.
*/
declare const AttachAddItemExpiryDurationType: {
readonly Month: "month";
readonly Forever: "forever";
};
/**
* When rolled over units expire.
*/
type AttachAddItemExpiryDurationType = ClosedEnum<typeof AttachAddItemExpiryDurationType>;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
type AttachAddItemRollover = {
/**
* Max rollover units. Omit for unlimited rollover.
*/
max?: number | undefined;
/**
* Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
*/
maxPercentage?: number | undefined;
/**
* When rolled over units expire.
*/
expiryDurationType: AttachAddItemExpiryDurationType;
/**
* Number of periods before expiry.
*/
expiryDurationLength?: number | undefined;
};
/**
* Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings.
*/
type AttachAddItemPlanItem = {
/**
* The ID of the feature to configure.
*/
featureId: string;
/**
* Number of free units included. Balance resets to this each interval for consumable features.
*/
included?: number | undefined;
/**
* If true, customer has unlimited access to this feature.
*/
unlimited?: boolean | undefined;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
reset?: AttachAddItemReset | undefined;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
price?: AttachAddItemPrice | undefined;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
proration?: AttachAddItemProration | undefined;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
rollover?: AttachAddItemRollover | undefined;
};
/**
* Match items with this billing method (prepaid or usage_based).
*/
declare const AttachRemoveItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* Match items with this billing method (prepaid or usage_based).
*/
type AttachRemoveItemBillingMethod = ClosedEnum<typeof AttachRemoveItemBillingMethod>;
declare const AttachIntervalRemoveItemEnum2: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
type AttachIntervalRemoveItemEnum2 = ClosedEnum<typeof AttachIntervalRemoveItemEnum2>;
declare const AttachIntervalRemoveItemEnum1: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
type AttachIntervalRemoveItemEnum1 = ClosedEnum<typeof AttachIntervalRemoveItemEnum1>;
/**
* Filter for matching plan items. All provided fields must match (AND).
*/
type AttachPlanItemFilter = {
/**
* Match items linked to this feature.
*/
featureId?: string | undefined;
/**
* Match items with this billing method (prepaid or usage_based).
*/
billingMethod?: AttachRemoveItemBillingMethod | undefined;
/**
* 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?: AttachIntervalRemoveItemEnum1 | AttachIntervalRemoveItemEnum2 | undefined;
/**
* Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
*/
intervalCount?: number | undefined;
};
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
declare const AttachDurationType: {
readonly Day: "day";
readonly Month: "month";
readonly Year: "year";
};
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
type AttachDurationType = ClosedEnum<typeof AttachDurationType>;
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
declare const AttachOnEnd: {
readonly Bill: "bill";
readonly Revert: "revert";
};
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
type AttachOnEnd = ClosedEnum<typeof AttachOnEnd>;
/**
* Free trial configuration for a plan.
*/
type AttachFreeTrialParams = {
/**
* Number of duration_type periods the trial lasts.
*/
durationLength: number;
/**
* Unit of time for the trial ('day', 'month', 'year').
*/
durationType?: AttachDurationType | undefined;
/**
* If true, payment method required to start trial. Customer is charged after trial ends.
*/
cardRequired?: boolean | undefined;
/**
* Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
*/
onEnd?: AttachOnEnd | undefined;
};
/**
* The time interval for the purchase limit window.
*/
declare const AttachPurchaseLimitInterval: {
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
};
/**
* The time interval for the purchase limit window.
*/
type AttachPurchaseLimitInterval = ClosedEnum<typeof AttachPurchaseLimitInterval>;
/**
* Optional rate limit to cap how often auto top-ups occur.
*/
type AttachPurchaseLimit = {
/**
* The time interval for the purchase limit window.
*/
interval: AttachPurchaseLimitInterval;
/**
* Number of intervals in the purchase limit window.
*/
intervalCount?: number | undefined;
/**
* Maximum number of auto top-ups allowed within the interval.
*/
limit: number;
};
type AttachAutoTopup = {
/**
* The ID of the feature (credit balance) to auto top-up.
*/
featureId: string;
/**
* Whether auto top-up is enabled.
*/
enabled?: boolean | undefined;
/**
* When the balance drops below this threshold, an auto top-up will be purchased.
*/
threshold: number;
/**
* Amount of credits to add per auto top-up.
*/
quantity: number;
/**
* Optional rate limit to cap how often auto top-ups occur.
*/
purchaseLimit?: AttachPurchaseLimit | undefined;
/**
* When true, auto top-up creates a send_invoice invoice instead of auto-charging.
*/
invoiceMode?: boolean | undefined;
};
/**
* How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
*/
declare const AttachLimitType: {
readonly Absolute: "absolute";
readonly UsagePercentage: "usage_percentage";
};
/**
* How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
*/
type AttachLimitType = ClosedEnum<typeof AttachLimitType>;
type AttachSpendLimit = {
/**
* Optional feature ID this spend limit applies to.
*/
featureId?: string | undefined;
/**
* Whether the overage spend limit is enabled.
*/
enabled?: boolean | undefined;
/**
* How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
*/
limitType?: AttachLimitType | undefined;
/**
* Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
*/
overageLimit?: number | undefined;
/**
* When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
*/
skipOverageBilling?: boolean | undefined;
};
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
declare const AttachUsageLimitInterval: {
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Year: "year";
};
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
type AttachUsageLimitInterval = ClosedEnum<typeof AttachUsageLimitInterval>;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
type AttachFilter = {
properties: {
[k: string]: string | number | boolean;
};
};
type AttachUsageLimit = {
/**
* The feature this usage limit applies to.
*/
featureId: string;
/**
* Whether this usage limit is enabled.
*/
enabled?: boolean | undefined;
/**
* Maximum units allowed per interval.
*/
limit: number;
/**
* Interval for the cap, aligned to the customer's billing cycle.
*/
interval: AttachUsageLimitInterval;
/**
* When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
*/
filter?: AttachFilter | undefined;
};
/**
* Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
*/
declare const AttachThresholdType: {
readonly Usage: "usage";
readonly UsagePercentage: "usage_percentage";
readonly Remaining: "remaining";
readonly RemainingPercentage: "remaining_percentage";
};
/**
* Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
*/
type AttachThresholdType = ClosedEnum<typeof AttachThresholdType>;
type AttachUsageAlert = {
/**
* The feature ID this alert applies to.
*/
featureId?: string | undefined;
/**
* Whether this usage alert is enabled.
*/
enabled?: boolean | undefined;
/**
* 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: number;
/**
* Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
*/
thresholdType: AttachThresholdType;
/**
* Optional user-defined label to distinguish multiple alerts on the same feature.
*/
name?: string | undefined;
};
type AttachOverageAllowed = {
/**
* The feature ID this overage allowed control applies to.
*/
featureId: string;
/**
* Whether overage is allowed for this feature.
*/
enabled?: boolean | undefined;
};
/**
* Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
*/
type AttachBillingControls = {
/**
* List of auto top-up configurations per feature.
*/
autoTopups?: Array<AttachAutoTopup> | undefined;
/**
* List of overage spend limits per feature (caps overage spend).
*/
spendLimits?: Array<AttachSpendLimit> | undefined;
/**
* List of hard usage caps per feature (max units per interval).
*/
usageLimits?: Array<AttachUsageLimit> | undefined;
/**
* List of usage alert configurations per feature.
*/
usageAlerts?: Array<AttachUsageAlert> | undefined;
/**
* List of overage allowed controls per feature. When enabled, usage can exceed balance.
*/
overageAllowed?: Array<AttachOverageAllowed> | undefined;
};
/**
* Customize the plan to attach. Can override the price, items, free trial, or a combination.
*/
type AttachCustomize = {
/**
* Override the base price of the plan. Pass null to remove the base price.
*/
price?: AttachBasePrice | null | undefined;
/**
* Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / deprecated update_items.
*/
items?: Array<AttachItemPlanItem> | undefined;
/**
* Items to add to the plan.
*/
addItems?: Array<AttachAddItemPlanItem> | undefined;
/**
* Filters selecting items to remove from the plan.
*/
removeItems?: Array<AttachPlanItemFilter> | undefined;
/**
* Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
*/
freeTrial?: AttachFreeTrialParams | null | undefined;
/**
* Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
*/
billingControls?: AttachBillingControls | undefined;
};
/**
* Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
*/
type AttachInvoiceMode = {
/**
* When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
*/
enabled: boolean;
/**
* If true, enables the plan immediately even though the invoice is not paid yet.
*/
enablePlanImmediately?: boolean | undefined;
/**
* If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
*/
finalize?: boolean | undefined;
/**
* ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
*/
invoiceTemplateId?: string | undefined;
/**
* Number of days the customer has to pay the invoice before it is due (Stripe days_until_due).
*/
netTermsDays?: number | undefined;
};
/**
* How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
*/
declare const AttachProrationBehavior: {
readonly ProrateImmediately: "prorate_immediately";
readonly None: "none";
};
/**
* How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
*/
type AttachProrationBehavior = ClosedEnum<typeof AttachProrationBehavior>;
/**
* Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
*/
declare const AttachRedirectMode: {
readonly Always: "always";
readonly IfRequired: "if_required";
readonly Never: "never";
};
/**
* Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
*/
type AttachRedirectMode = ClosedEnum<typeof AttachRedirectMode>;
/**
* A discount to apply. Can be either a reward ID or a promotion code.
*/
type AttachAttachDiscount = {
/**
* The ID of the reward to apply as a discount.
*/
rewardId?: string | undefined;
/**
* The promotion code to apply as a discount.
*/
promotionCode?: string | undefined;
};
/**
* When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
*/
declare const AttachPlanSchedule: {
readonly Immediate: "immediate";
readonly EndOfCycle: "end_of_cycle";
};
/**
* When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
*/
type AttachPlanSchedule = ClosedEnum<typeof AttachPlanSchedule>;
type AttachCustomLineItem = {
/**
* Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
*/
amount: number;
/**
* Description for the line item.
*/
description: string;
};
/**
* Whether to carry over balances from the previous plan.
*/
type AttachCarryOverBalances = {
/**
* Whether to carry over balances from the previous plan.
*/
enabled: boolean;
/**
* The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
*/
featureIds?: Array<string> | undefined;
};
/**
* Whether to carry over usages from the previous plan.
*/
type AttachCarryOverUsages = {
/**
* Whether to carry over usages from the previous plan.
*/
enabled: boolean;
/**
* The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
*/
featureIds?: Array<string> | undefined;
};
type AttachParams = {
/**
* The ID of the customer to attach the plan to.
*/
customerId: string;
/**
* The ID of the entity to attach the plan to.
*/
entityId?: string | undefined;
/**
* The ID of the plan.
*/
planId: string;
/**
* If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
*/
featureQuantities?: Array<AttachFeatureQuantity> | undefined;
/**
* The version of the plan to attach.
*/
version?: number | undefined;
/**
* Customize the plan to attach. Can override the price, items, free trial, or a combination.
*/
customize?: AttachCustomize | undefined;
/**
* Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
*/
invoiceMode?: AttachInvoiceMode | undefined;
/**
* How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
*/
prorationBehavior?: AttachProrationBehavior | undefined;
/**
* Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
*/
redirectMode?: AttachRedirectMode | undefined;
/**
* A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
*/
subscriptionId?: string | undefined;
/**
* List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
*/
discounts?: Array<AttachAttachDiscount> | undefined;
/**
* URL to redirect to after successful checkout.
*/
successUrl?: string | undefined;
/**
* Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
*/
newBillingSubscription?: boolean | undefined;
/**
* Reset the billing cycle anchor immediately with 'now'.
*/
billingCycleAnchor?: "now" | undefined;
/**
* When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
*/
planSchedule?: AttachPlanSchedule | undefined;
/**
* Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
*/
startsAt?: number | undefined;
/**
* Unix timestamp in milliseconds for when the attached plan should end.
*/
endsAt?: number | undefined;
/**
* Additional parameters to pass into the creation of the Stripe checkout session.
*/
checkoutSessionParams?: {
[k: string]: any;
} | undefined;
/**
* If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.
*/
longLivedCheckout?: boolean | undefined;
/**
* Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
*/
customLineItems?: Array<AttachCustomLineItem> | undefined;
/**
* The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
*/
processorSubscriptionId?: string | undefined;
/**
* Whether to carry over balances from the previous plan.
*/
carryOverBalances?: AttachCarryOverBalances | undefined;
/**
* Whether to carry over usages from the previous plan.
*/
carryOverUsages?: AttachCarryOverUsages | undefined;
/**
* Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped.
*/
metadata?: {
[k: string]: string;
} | undefined;
/**
* If true, skips any billing changes for the attach operation.
*/
noBillingChanges?: boolean | undefined;
/**
* If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form.
*/
enablePlanImmediately?: boolean | undefined;
/**
* Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
*/
taxRateId?: string | undefined;
};
/**
* Invoice details if an invoice was created. Only present when a charge was made.
*/
type AttachInvoice = {
/**
* The status of the invoice (e.g., 'paid', 'open', 'draft').
*/
status: string | null;
/**
* The Stripe invoice ID.
*/
stripeId: string;
/**
* The total amount of the invoice in cents.
*/
total: number;
/**
* The three-letter ISO currency code (e.g., 'usd').
*/
currency: string;
/**
* URL to the hosted invoice page where the customer can view and pay the invoice.
*/
hostedInvoiceUrl: string | null;
};
/**
* The type of action required to complete the payment.
*/
declare const AttachCode: {
readonly ThreedsRequired: "3ds_required";
readonly PaymentMethodRequired: "payment_method_required";
readonly PaymentFailed: "payment_failed";
readonly PaymentProcessing: "payment_processing";
};
/**
* The type of action required to complete the payment.
*/
type AttachCode = OpenEnum<typeof AttachCode>;
/**
* Details about any action required to complete the payment. Present when the payment could not be processed automatically.
*/
type AttachRequiredAction = {
/**
* The type of action required to complete the payment.
*/
code: AttachCode;
/**
* A human-readable explanation of why this action is required.
*/
reason: string;
};
/**
* OK
*/
type AttachResponse = {
/**
* The ID of the customer.
*/
customerId: string;
/**
* The ID of the entity, if the plan was attached to an entity.
*/
entityId?: string | undefined;
/**
* Invoice details if an invoice was created. Only present when a charge was made.
*/
invoice?: AttachInvoice | undefined;
/**
* URL to redirect the customer to complete payment. Null if no payment action is required.
*/
paymentUrl: string | null;
/**
* Details about any action required to complete the payment. Present when the payment could not be processed automatically.
*/
requiredAction?: AttachRequiredAction | undefined;
};
/**
* Quantity configuration for a prepaid feature.
*/
type BillingUpdateFeatureQuantity = {
/**
* The ID of the feature to set quantity for.
*/
featureId: string;
/**
* The quantity of the feature.
*/
quantity?: number | undefined;
/**
* Whether the customer can adjust the quantity.
*/
adjustable?: boolean | undefined;
};
/**
* Billing interval (e.g. 'month', 'year').
*/
declare const BillingUpdatePriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval (e.g. 'month', 'year').
*/
type BillingUpdatePriceInterval = ClosedEnum<typeof BillingUpdatePriceInterval>;
/**
* Base price configuration for a plan.
*/
type BillingUpdateBasePrice = {
/**
* Base price amount for the plan.
*/
amount: number;
/**
* Billing interval (e.g. 'month', 'year').
*/
interval: BillingUpdatePriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
declare const BillingUpdateItemResetInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
type BillingUpdateItemResetInterval = ClosedEnum<typeof BillingUpdateItemResetInterval>;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
type BillingUpdateItemReset = {
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
interval: BillingUpdateItemResetInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type BillingUpdateItemTier = {
to: number | string;
amount?: number | undefined;
flatAmount?: number | undefined;
};
declare const BillingUpdateItemTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type BillingUpdateItemTierBehavior = ClosedEnum<typeof BillingUpdateItemTierBehavior>;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
declare const BillingUpdateItemPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval. For consumable features, should match reset.interval.
*/
type BillingUpdateItemPriceInterval = ClosedEnum<typeof BillingUpdateItemPriceInterval>;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
declare const BillingUpdateItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
type BillingUpdateItemBillingMethod = ClosedEnum<typeof BillingUpdateItemBillingMethod>;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
type BillingUpdateItemPrice = {
/**
* Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
*/
amount?: number | undefined;
/**
* Tiered pricing. Either 'amount' or 'tiers' is required.
*/
tiers?: Array<BillingUpdateItemTier> | undefined;
tierBehavior?: BillingUpdateItemTierBehavior | undefined;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
interval: BillingUpdateItemPriceInterval;
/**
* Number of intervals per billing cycle. Defaults to 1.
*/
intervalCount?: number | undefined;
/**
* Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
*/
billingUnits?: number | undefined;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
billingMethod: BillingUpdateItemBillingMethod;
/**
* Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
*/
maxPurchase?: number | null | undefined;
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
declare const BillingUpdateItemOnIncrease: {
readonly BillImmediately: "bill_immediately";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly BillNextCycle: "bill_next_cycle";
};
/**
* Billing behavior when quantity increases mid-cycle.
*/
type BillingUpdateItemOnIncrease = ClosedEnum<typeof BillingUpdateItemOnIncrease>;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
declare const BillingUpdateItemOnDecrease: {
readonly Prorate: "prorate";
readonly ProrateImmediately: "prorate_immediately";
readonly ProrateNextCycle: "prorate_next_cycle";
readonly None: "none";
readonly NoProrations: "no_prorations";
};
/**
* Credit behavior when quantity decreases mid-cycle.
*/
type BillingUpdateItemOnDecrease = ClosedEnum<typeof BillingUpdateItemOnDecrease>;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
type BillingUpdateItemProration = {
/**
* Billing behavior when quantity increases mid-cycle.
*/
onIncrease: BillingUpdateItemOnIncrease;
/**
* Credit behavior when quantity decreases mid-cycle.
*/
onDecrease: BillingUpdateItemOnDecrease;
};
/**
* When rolled over units expire.
*/
declare const BillingUpdateItemExpiryDurationType: {
readonly Month: "month";
readonly Forever: "forever";
};
/**
* When rolled over units expire.
*/
type BillingUpdateItemExpiryDurationType = ClosedEnum<typeof BillingUpdateItemExpiryDurationType>;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
type BillingUpdateItemRollover = {
/**
* Max rollover units. Omit for unlimited rollover.
*/
max?: number | undefined;
/**
* Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
*/
maxPercentage?: number | undefined;
/**
* When rolled over units expire.
*/
expiryDurationType: BillingUpdateItemExpiryDurationType;
/**
* Number of periods before expiry.
*/
expiryDurationLength?: number | undefined;
};
/**
* Configuration for a feature item in a plan, including usage limits, pricing, and rollover settings.
*/
type BillingUpdateItemPlanItem = {
/**
* The ID of the feature to configure.
*/
featureId: string;
/**
* Number of free units included. Balance resets to this each interval for consumable features.
*/
included?: number | undefined;
/**
* If true, customer has unlimited access to this feature.
*/
unlimited?: boolean | undefined;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
reset?: BillingUpdateItemReset | undefined;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
price?: BillingUpdateItemPrice | undefined;
/**
* Proration settings for prepaid features. Controls mid-cycle quantity change billing.
*/
proration?: BillingUpdateItemProration | undefined;
/**
* Rollover config for unused units. If set, unused included units carry over.
*/
rollover?: BillingUpdateItemRollover | undefined;
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
declare const BillingUpdateAddItemResetInterval: {
readonly OneOff: "one_off";
readonly Minute: "minute";
readonly Hour: "hour";
readonly Day: "day";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
type BillingUpdateAddItemResetInterval = ClosedEnum<typeof BillingUpdateAddItemResetInterval>;
/**
* Reset configuration for consumable features. Omit for non-consumable features like seats.
*/
type BillingUpdateAddItemReset = {
/**
* Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
*/
interval: BillingUpdateAddItemResetInterval;
/**
* Number of intervals between resets. Defaults to 1.
*/
intervalCount?: number | undefined;
};
type BillingUpdateAddItemTier = {
to: number | string;
amount?: number | undefined;
flatAmount?: number | undefined;
};
declare const BillingUpdateAddItemTierBehavior: {
readonly Graduated: "graduated";
readonly Volume: "volume";
};
type BillingUpdateAddItemTierBehavior = ClosedEnum<typeof BillingUpdateAddItemTierBehavior>;
/**
* Billing interval. For consumable features, should match reset.interval.
*/
declare const BillingUpdateAddItemPriceInterval: {
readonly OneOff: "one_off";
readonly Week: "week";
readonly Month: "month";
readonly Quarter: "quarter";
readonly SemiAnnual: "semi_annual";
readonly Year: "year";
};
/**
* Billing interval. For consumable features, should match reset.interval.
*/
type BillingUpdateAddItemPriceInterval = ClosedEnum<typeof BillingUpdateAddItemPriceInterval>;
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
declare const BillingUpdateAddItemBillingMethod: {
readonly Prepaid: "prepaid";
readonly UsageBased: "usage_based";
};
/**
* 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
*/
type BillingUpdateAddItemBillingMethod = ClosedEnum<typeof BillingUpdateAddItemBillingMethod>;
/**
* Pricing for usage beyond included units. Omit for free features.
*/
type BillingUpdateAddItemPrice = {
/**
* Price per billing_units after included usage. Either 'amount' or 'tiers' is r