atmn 1.1.25 → 2.0.0

package/src/generated/plans.ts

@@ -0,0 +1,1628 @@
+// Generated by @autumn/atmn-generator from packages/openapi/openapi-internal.yml.
+// Do not edit — run `bun generate` in packages/atmn-generator instead.
+
+export type Plan = {
+	/** The ID of the plan to create or update. */
+	planId: string;
+	/** Address an existing row by its stable id. Omit when creating — the server generates one. A differing plan_id alongside it is a rename. */
+	internalId?: string;
+	/** Display name of the plan. Required when creating. */
+	name: string;
+	/** Optional description of the plan. */
+	description?: string | null;
+	/** Group identifier for mutually exclusive plans. */
+	group?: string;
+	/** Whether the plan is an add-on. Defaults to false. */
+	addOn?: boolean;
+	/** Whether the plan is automatically enabled for new customers. Defaults to false. */
+	autoEnable?: boolean;
+	/** Archive or unarchive the plan. */
+	archived?: boolean;
+	/** Take the active pointer. On `new_version`, omit to mint a draft; `true` promotes the minted row immediately. */
+	active: boolean;
+	/** Payment processors this plan is connected to. Omit to keep. */
+	processors?: {
+		stripe?: {
+			/** Stripe product ID this plan is billed under. */
+			productId: string;
+			/** Extra Stripe product IDs aliased to this plan. */
+			additionalProductIds?: Array<string>;
+		} | null;
+		revenuecat?: {
+			/** Every RevenueCat product that maps to this plan. Replaces the current set. */
+			products: Array<{
+				/** RevenueCat product ID that grants this plan when purchased. */
+				productId: string;
+				/** Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units. */
+				featureQuantities?: Array<{
+					featureId: string;
+					quantity?: number;
+				}>;
+			}>;
+		} | null;
+	};
+	/** Base recurring price. Omit to leave unchanged; null removes it. */
+	price?: {
+		/** Base price amount for the plan, in major currency units (e.g. dollars). */
+		amount: number;
+		/** Billing interval (e.g. 'month', 'year'). */
+		interval: "one_off" | "week" | "month" | "quarter" | "semi_annual" | "year";
+		/** Number of intervals per billing cycle. Defaults to 1. */
+		intervalCount?: number;
+		/** Base price amounts in additional currencies. The base 'amount' is in the org's default currency. */
+		additionalCurrencies?: Array<{
+			/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+			currency: string;
+			/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+			amount: number;
+		}>;
+		/** Adopt an existing Stripe price instead of creating one. The id must already exist in Stripe. */
+		processors?: {
+			stripe?: {
+				/** Stripe price ID. For prepaid with included > 0 this is the V2 price. */
+				priceId: string;
+			} | null;
+		};
+	} | null;
+	/** Feature configurations for this plan. */
+	items?: Array<{
+		/** Bills this many feature units when outstanding overage reaches it. */
+		thresholdBilling?: {
+			threshold: number;
+		} | null;
+		/** 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;
+		/** If true, customer has unlimited access to this feature. */
+		unlimited?: boolean;
+		/** Whether entity-level grants contribute to a shared customer balance. Defaults to false. */
+		pooled?: boolean;
+		/** Reset configuration for consumable features. Omit for non-consumable features like seats. */
+		reset?: {
+			/** Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. */
+			interval:
+				| "one_off"
+				| "minute"
+				| "hour"
+				| "day"
+				| "week"
+				| "month"
+				| "quarter"
+				| "semi_annual"
+				| "year";
+			/** Number of intervals between resets. Defaults to 1. */
+			intervalCount?: number;
+		};
+		/** Pricing for usage beyond included units. Omit for free features. */
+		price?: {
+			/** Price per billing_units after included usage. Either 'amount' or 'tiers' is required. */
+			amount?: number;
+			/** Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. */
+			additionalCurrencies?: Array<{
+				/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+				currency: string;
+				/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+				amount: number;
+			}>;
+			/** Tiered pricing. Either 'amount' or 'tiers' is required. */
+			tiers?: Array<{
+				to: number | "inf";
+				amount?: number;
+				flatAmount?: number;
+				/** Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. */
+				additionalCurrencies?: Array<{
+					/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+					currency: string;
+					/** Per-unit amount for this tier in this currency. */
+					amount?: number;
+					/** Flat amount for this tier in this currency, if the tier uses one. */
+					flatAmount?: number;
+				}>;
+			}>;
+			tierBehavior?: "graduated" | "volume";
+			/** Billing interval. For consumable features, should match reset.interval. */
+			interval:
+				| "one_off"
+				| "week"
+				| "month"
+				| "quarter"
+				| "semi_annual"
+				| "year";
+			/** Number of intervals per billing cycle. Defaults to 1. */
+			intervalCount?: number;
+			/** Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). Defaults to 1. */
+			billingUnits?: number;
+			/** 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. */
+			billingMethod: "prepaid" | "usage_based";
+			/** Only pulled as `prorated_legacy` for a price still on the legacy immediate-proration behavior, alongside its `proration` knobs. */
+			allocatedBilling?: "arrear" | "prorated_legacy";
+			/** Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. */
+			maxPurchase?: number | null;
+			/** Adopt an existing Stripe price instead of creating one. The id must already exist in Stripe. */
+			processors?: {
+				stripe?: {
+					/** Stripe price ID. For prepaid with included > 0 this is the V2 price. */
+					priceId: string;
+				} | null;
+			};
+		};
+		/** Proration settings for prepaid features. Controls mid-cycle quantity change billing. */
+		proration?: {
+			/** Billing behavior when quantity increases mid-cycle. */
+			onIncrease:
+				| "bill_immediately"
+				| "prorate_immediately"
+				| "prorate_next_cycle"
+				| "bill_next_cycle";
+			/** Credit behavior when quantity decreases mid-cycle. */
+			onDecrease:
+				| "prorate"
+				| "prorate_immediately"
+				| "prorate_next_cycle"
+				| "none"
+				| "no_prorations";
+		};
+		/** Rollover config for unused units. If set, unused included units carry over. */
+		rollover?: {
+			/** Max rollover units. Omit for unlimited rollover. */
+			max?: number;
+			/** Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. */
+			maxPercentage?: number;
+			/** When rolled over units expire. */
+			expiryDurationType: "month" | "forever";
+			/** Number of periods before expiry. */
+			expiryDurationLength?: number;
+		};
+		/** Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit_schema). */
+		featureOverride?: {
+			/** For credit system features: replaces the feature's credit_schema entirely for customers on this plan. */
+			creditSchema?: Array<
+				| {
+						/** ID of the metered feature that draws from this credit system. */
+						meteredFeatureId: string;
+						/** Number of metered-feature units priced together. Defaults to one when omitted. */
+						billingUnits?: number;
+						/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+						dimensions?: Record<
+							string,
+							| {
+									/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+									match: Record<string, string | number | boolean>;
+									/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+									priority?: number;
+									tierBehavior: "graduated";
+									tiers: Array<{
+										/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+										to: number | "inf";
+										/** Credits consumed per billing-unit group within this tier. */
+										creditCost: number;
+									}>;
+							  }
+							| {
+									/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+									match: Record<string, string | number | boolean>;
+									/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+									priority?: number;
+									/** Credits consumed per billing-unit group when this dimension matches. */
+									creditCost: number;
+							  }
+						>;
+						/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+						multipliers?: Record<
+							string,
+							{
+								/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+								match: Record<string, string | number | boolean>;
+								/** Multiplies the matched rate. All matching multipliers stack. */
+								factor?: number;
+								/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+								add?: number;
+							}
+						>;
+						tierBehavior: "graduated";
+						tiers: Array<{
+							/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+							to: number | "inf";
+							/** Credits consumed per billing-unit group within this tier. */
+							creditCost: number;
+						}>;
+				  }
+				| {
+						/** ID of the metered feature that draws from this credit system. */
+						meteredFeatureId: string;
+						/** Number of metered-feature units priced together. Defaults to one when omitted. */
+						billingUnits?: number;
+						/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+						dimensions?: Record<
+							string,
+							| {
+									/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+									match: Record<string, string | number | boolean>;
+									/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+									priority?: number;
+									tierBehavior: "graduated";
+									tiers: Array<{
+										/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+										to: number | "inf";
+										/** Credits consumed per billing-unit group within this tier. */
+										creditCost: number;
+									}>;
+							  }
+							| {
+									/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+									match: Record<string, string | number | boolean>;
+									/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+									priority?: number;
+									/** Credits consumed per billing-unit group when this dimension matches. */
+									creditCost: number;
+							  }
+						>;
+						/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+						multipliers?: Record<
+							string,
+							{
+								/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+								match: Record<string, string | number | boolean>;
+								/** Multiplies the matched rate. All matching multipliers stack. */
+								factor?: number;
+								/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+								add?: number;
+							}
+						>;
+						/** Credits consumed per billing-unit group. */
+						creditCost: number;
+				  }
+			>;
+			/** For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's. */
+			markups?: {
+				/** Default percentage markup for customers on this plan. Use -100 to make usage free. */
+				defaultMarkup?: number;
+				/** Per-provider markup percentages for customers on this plan. */
+				providerMarkups?: Record<
+					string,
+					{
+						markup: number;
+					}
+				> | null;
+				/** Per-model markup overrides for customers on this plan. */
+				modelMarkups?: Record<
+					string,
+					{
+						markup?: number;
+						inputCost?: number;
+						outputCost?: number;
+					}
+				> | null;
+			};
+		};
+		/** @deprecated Per-entity items are deprecated but existing catalogs carry them, so a config must keep round-tripping the field. */
+		entityFeatureId?: string;
+	}>;
+	/** Free trial. Omit to leave unchanged; null removes it. */
+	freeTrial?: {
+		/** Number of duration_type periods the trial lasts. */
+		durationLength: number;
+		/** Unit of time for the trial ('day', 'month', 'year'). Defaults to "month". */
+		durationType?: "day" | "month" | "year";
+		/** If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false. */
+		cardRequired?: boolean;
+		/** Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. */
+		onEnd?: "bill" | "revert";
+	} | null;
+	/** Miscellaneous plan-level configuration flags. */
+	config?: {
+		/** If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state. Defaults to false. */
+		ignorePastDue?: boolean;
+	};
+	/** Plan-level billing controls used as customer defaults. */
+	billingControls?: {
+		/** List of auto top-up configurations per feature. Defaults to []. */
+		autoTopups?: Array<{
+			/** The ID of the feature (credit balance) to auto top-up. */
+			featureId: string;
+			/** Whether auto top-up is enabled. Defaults to false. */
+			enabled?: boolean;
+			/** 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. Pass count to set the current window's consumed top-ups. */
+			purchaseLimit?: {
+				/** The time interval for the purchase limit window. */
+				interval: "hour" | "day" | "week" | "month";
+				/** Number of intervals in the purchase limit window. Defaults to 1. */
+				intervalCount?: number;
+				/** Maximum number of auto top-ups allowed within the interval. */
+				limit: number;
+				/** Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged. */
+				count?: number;
+			};
+			/** When true, auto top-up creates a send_invoice invoice instead of auto-charging. */
+			invoiceMode?: boolean;
+		}>;
+		/** List of overage spend limits per feature (caps overage spend). Defaults to []. */
+		spendLimits?: Array<{
+			/** Optional feature ID this spend limit applies to. */
+			featureId?: string;
+			/** Whether the overage spend limit is enabled. Defaults to false. */
+			enabled?: boolean;
+			/** How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. */
+			limitType?: "absolute" | "usage_percentage";
+			/** Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. */
+			overageLimit?: number;
+			/** When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. */
+			skipOverageBilling?: boolean;
+		}>;
+		/** List of hard usage caps per feature (max units per interval). Defaults to []. */
+		usageLimits?: Array<{
+			/** The feature this usage limit applies to. */
+			featureId: string;
+			/** Whether this usage limit is enabled. Defaults to true. */
+			enabled?: boolean;
+			/** Maximum units allowed per interval. */
+			limit: number;
+			/** Interval for the cap, aligned to the customer's billing cycle. */
+			interval: "day" | "week" | "month" | "year";
+			/** Window alignment. 'billing_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar. */
+			anchor?: "billing_cycle" | "utc";
+			/** When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. */
+			filter?: {
+				properties: Record<string, string | number | boolean>;
+			};
+		}>;
+		/** List of usage alert configurations per feature. Defaults to []. */
+		usageAlerts?: Array<{
+			/** The feature ID this alert applies to. */
+			featureId?: string;
+			/** Whether this usage alert is enabled. Defaults to true. */
+			enabled?: boolean;
+			/** 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:
+				| "usage"
+				| "usage_percentage"
+				| "remaining"
+				| "remaining_percentage";
+			/** What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage_limit: the cap of the usage limit with the same feature and filter. Defaults to "balance". */
+			basis?: "balance" | "included" | "recurring" | "usage_limit";
+			/** Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter. */
+			filter?: {
+				properties: Record<string, string | number | boolean>;
+			};
+			/** Optional user-defined label to distinguish multiple alerts on the same feature. */
+			name?: string;
+		}>;
+		/** List of overage allowed controls per feature. When enabled, usage can exceed balance. Defaults to []. */
+		overageAllowed?: Array<{
+			/** The feature ID this overage allowed control applies to. */
+			featureId: string;
+			/** Whether overage is allowed for this feature. Defaults to false. */
+			enabled?: boolean;
+		}>;
+	};
+	/** Arbitrary key-value metadata shared across all versions. Defaults to {}. */
+	metadata?: Record<string, unknown>;
+	/** Target this version row by slug. At most one of `version` / `version_slug`; omit both to target the active row. Defaults to "vN", N being the server's version number, which counts in creation order; state it explicitly on every history row so a nuke-and-repush or a sandbox-to-prod push keeps the same names even though the numbers may differ. */
+	versionSlug?: string;
+	/** When false, skip Stripe product/price creation on create. */
+	createInStripe?: boolean;
+	/** Declared overlays on variants of this plan. Omit to leave them unchanged. Follow is `propagate.variants`, not presence here. */
+	variants?: Array<{
+		/** The variant plan this overlay applies to. */
+		variantPlanId: string;
+		/** Address an existing variant row by its stable id, instead of by plan id and version. */
+		internalId?: string;
+		/** Which version of the variant this overlay targets. At most one of `version` / `version_slug`; omit both to target latest. */
+		version?: number;
+		/** Which version of the variant this overlay targets, by slug. Same pin as `version`; omit both to target latest. Defaults to "vN", N being the server's version number; state it explicitly on every variant history row. */
+		versionSlug?: string;
+		/** Display name when creating the variant if it does not exist. */
+		name: string;
+		/** Archive or unarchive this variant. Omit to leave archived state unchanged. */
+		archived?: boolean;
+		/** Slug for the row this variant mints. Omit to inherit the base's `new_version_slug`, then `v{n}`. Ignored when this entry resolves to an existing row. */
+		newVersionSlug?: string;
+		/** Overrides the base plan's processors for this variant. Omit to inherit when the base processors change. */
+		processors?: {
+			stripe?: {
+				/** Stripe product ID this plan is billed under. */
+				productId: string;
+				/** Extra Stripe product IDs aliased to this plan. */
+				additionalProductIds?: Array<string>;
+			} | null;
+			revenuecat?: {
+				/** Every RevenueCat product that maps to this plan. Replaces the current set. */
+				products: Array<{
+					/** RevenueCat product ID that grants this plan when purchased. */
+					productId: string;
+					/** Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units. */
+					featureQuantities?: Array<{
+						featureId: string;
+						quantity?: number;
+					}>;
+				}>;
+			} | null;
+		};
+		/** Pointer write for this nested variant. Omit to link it to this base; `null` detaches it. A string must be this plan's id. */
+		baseVariantId?: string | null;
+		/** Declared overlay on this variant. `items` is PUT (replaces the list); `add_items` / `remove_items` are PATCH. Independent of `propagate`. Blocked on an archived variant unless `archived` is false in the same entry. */
+		customize?: {
+			/** Override the base price of the plan. Pass null to remove the base price. */
+			price?: {
+				/** Base price amount for the plan, in major currency units (e.g. dollars). */
+				amount: number;
+				/** Billing interval (e.g. 'month', 'year'). */
+				interval:
+					| "one_off"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year";
+				/** Number of intervals per billing cycle. Defaults to 1. */
+				intervalCount?: number;
+				/** Base price amounts in additional currencies. The base 'amount' is in the org's default currency. */
+				additionalCurrencies?: Array<{
+					/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+					currency: string;
+					/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+					amount: number;
+				}>;
+			} | null;
+			/** Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / deprecated update_items. */
+			items?: Array<{
+				/** Bills this many feature units when outstanding overage reaches it. */
+				thresholdBilling?: {
+					threshold: number;
+				} | null;
+				/** 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;
+				/** If true, customer has unlimited access to this feature. */
+				unlimited?: boolean;
+				/** Whether entity-level grants contribute to a shared customer balance. Defaults to false. */
+				pooled?: boolean;
+				/** Reset configuration for consumable features. Omit for non-consumable features like seats. */
+				reset?: {
+					/** Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. */
+					interval:
+						| "one_off"
+						| "minute"
+						| "hour"
+						| "day"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals between resets. Defaults to 1. */
+					intervalCount?: number;
+				};
+				/** Pricing for usage beyond included units. Omit for free features. */
+				price?: {
+					/** Price per billing_units after included usage. Either 'amount' or 'tiers' is required. */
+					amount?: number;
+					/** Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. */
+					additionalCurrencies?: Array<{
+						/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+						currency: string;
+						/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+						amount: number;
+					}>;
+					/** Tiered pricing. Either 'amount' or 'tiers' is required. */
+					tiers?: Array<{
+						to: number | "inf";
+						amount?: number;
+						flatAmount?: number;
+						/** Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. */
+						additionalCurrencies?: Array<{
+							/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+							currency: string;
+							/** Per-unit amount for this tier in this currency. */
+							amount?: number;
+							/** Flat amount for this tier in this currency, if the tier uses one. */
+							flatAmount?: number;
+						}>;
+					}>;
+					tierBehavior?: "graduated" | "volume";
+					/** Billing interval. For consumable features, should match reset.interval. */
+					interval:
+						| "one_off"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals per billing cycle. Defaults to 1. */
+					intervalCount?: number;
+					/** Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). Defaults to 1. */
+					billingUnits?: number;
+					/** 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. */
+					billingMethod: "prepaid" | "usage_based";
+					allocatedBilling?: "arrear" | "prorated_legacy";
+					/** Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. */
+					maxPurchase?: number | null;
+				};
+				/** Proration settings for prepaid features. Controls mid-cycle quantity change billing. */
+				proration?: {
+					/** Billing behavior when quantity increases mid-cycle. */
+					onIncrease:
+						| "bill_immediately"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "bill_next_cycle";
+					/** Credit behavior when quantity decreases mid-cycle. */
+					onDecrease:
+						| "prorate"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "none"
+						| "no_prorations";
+				};
+				/** Rollover config for unused units. If set, unused included units carry over. */
+				rollover?: {
+					/** Max rollover units. Omit for unlimited rollover. */
+					max?: number;
+					/** Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. */
+					maxPercentage?: number;
+					/** When rolled over units expire. */
+					expiryDurationType: "month" | "forever";
+					/** Number of periods before expiry. */
+					expiryDurationLength?: number;
+				};
+				/** Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit_schema). */
+				featureOverride?: {
+					/** For credit system features: replaces the feature's credit_schema entirely for customers on this plan. */
+					creditSchema?: Array<
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								tierBehavior: "graduated";
+								tiers: Array<{
+									/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+									to: number | "inf";
+									/** Credits consumed per billing-unit group within this tier. */
+									creditCost: number;
+								}>;
+						  }
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								/** Credits consumed per billing-unit group. */
+								creditCost: number;
+						  }
+					>;
+					/** For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's. */
+					markups?: {
+						/** Default percentage markup for customers on this plan. Use -100 to make usage free. */
+						defaultMarkup?: number;
+						/** Per-provider markup percentages for customers on this plan. */
+						providerMarkups?: Record<
+							string,
+							{
+								markup: number;
+							}
+						> | null;
+						/** Per-model markup overrides for customers on this plan. */
+						modelMarkups?: Record<
+							string,
+							{
+								markup?: number;
+								inputCost?: number;
+								outputCost?: number;
+							}
+						> | null;
+					};
+				};
+				entityFeatureId?: string;
+			}>;
+			/** Items to add to the plan. */
+			addItems?: Array<{
+				/** Bills this many feature units when outstanding overage reaches it. */
+				thresholdBilling?: {
+					threshold: number;
+				} | null;
+				/** 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;
+				/** If true, customer has unlimited access to this feature. */
+				unlimited?: boolean;
+				/** Whether entity-level grants contribute to a shared customer balance. Defaults to false. */
+				pooled?: boolean;
+				/** Reset configuration for consumable features. Omit for non-consumable features like seats. */
+				reset?: {
+					/** Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. */
+					interval:
+						| "one_off"
+						| "minute"
+						| "hour"
+						| "day"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals between resets. Defaults to 1. */
+					intervalCount?: number;
+				};
+				/** Pricing for usage beyond included units. Omit for free features. */
+				price?: {
+					/** Price per billing_units after included usage. Either 'amount' or 'tiers' is required. */
+					amount?: number;
+					/** Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. */
+					additionalCurrencies?: Array<{
+						/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+						currency: string;
+						/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+						amount: number;
+					}>;
+					/** Tiered pricing. Either 'amount' or 'tiers' is required. */
+					tiers?: Array<{
+						to: number | "inf";
+						amount?: number;
+						flatAmount?: number;
+						/** Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. */
+						additionalCurrencies?: Array<{
+							/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+							currency: string;
+							/** Per-unit amount for this tier in this currency. */
+							amount?: number;
+							/** Flat amount for this tier in this currency, if the tier uses one. */
+							flatAmount?: number;
+						}>;
+					}>;
+					tierBehavior?: "graduated" | "volume";
+					/** Billing interval. For consumable features, should match reset.interval. */
+					interval:
+						| "one_off"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals per billing cycle. Defaults to 1. */
+					intervalCount?: number;
+					/** Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). Defaults to 1. */
+					billingUnits?: number;
+					/** 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. */
+					billingMethod: "prepaid" | "usage_based";
+					allocatedBilling?: "arrear" | "prorated_legacy";
+					/** Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. */
+					maxPurchase?: number | null;
+				};
+				/** Proration settings for prepaid features. Controls mid-cycle quantity change billing. */
+				proration?: {
+					/** Billing behavior when quantity increases mid-cycle. */
+					onIncrease:
+						| "bill_immediately"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "bill_next_cycle";
+					/** Credit behavior when quantity decreases mid-cycle. */
+					onDecrease:
+						| "prorate"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "none"
+						| "no_prorations";
+				};
+				/** Rollover config for unused units. If set, unused included units carry over. */
+				rollover?: {
+					/** Max rollover units. Omit for unlimited rollover. */
+					max?: number;
+					/** Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. */
+					maxPercentage?: number;
+					/** When rolled over units expire. */
+					expiryDurationType: "month" | "forever";
+					/** Number of periods before expiry. */
+					expiryDurationLength?: number;
+				};
+				/** Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit_schema). */
+				featureOverride?: {
+					/** For credit system features: replaces the feature's credit_schema entirely for customers on this plan. */
+					creditSchema?: Array<
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								tierBehavior: "graduated";
+								tiers: Array<{
+									/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+									to: number | "inf";
+									/** Credits consumed per billing-unit group within this tier. */
+									creditCost: number;
+								}>;
+						  }
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								/** Credits consumed per billing-unit group. */
+								creditCost: number;
+						  }
+					>;
+					/** For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's. */
+					markups?: {
+						/** Default percentage markup for customers on this plan. Use -100 to make usage free. */
+						defaultMarkup?: number;
+						/** Per-provider markup percentages for customers on this plan. */
+						providerMarkups?: Record<
+							string,
+							{
+								markup: number;
+							}
+						> | null;
+						/** Per-model markup overrides for customers on this plan. */
+						modelMarkups?: Record<
+							string,
+							{
+								markup?: number;
+								inputCost?: number;
+								outputCost?: number;
+							}
+						> | null;
+					};
+				};
+				entityFeatureId?: string;
+			}>;
+			/** Filters selecting items to remove from the plan. */
+			removeItems?: Array<{
+				/** Match items linked to this feature. */
+				featureId?: string;
+				/** Match items with this billing method (prepaid or usage_based). */
+				billingMethod?: "prepaid" | "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. */
+				interval?:
+					| "one_off"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year"
+					| "one_off"
+					| "minute"
+					| "hour"
+					| "day"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year";
+				/** Match items with this interval_count. Disambiguates between items that share an interval but differ in count. */
+				intervalCount?: number;
+				/** Match items whose grant equals this included usage. Omitted is a wildcard. */
+				included?: number;
+			}>;
+			/** Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely. */
+			freeTrial?: {
+				/** Number of duration_type periods the trial lasts. */
+				durationLength: number;
+				/** Unit of time for the trial ('day', 'month', 'year'). Defaults to "month". */
+				durationType?: "day" | "month" | "year";
+				/** If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false. */
+				cardRequired?: boolean;
+				/** Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan. */
+				onEnd?: "bill" | "revert";
+			} | null;
+			/** Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer. */
+			billingControls?: {
+				/** List of auto top-up configurations per feature. Defaults to []. */
+				autoTopups?: Array<{
+					/** The ID of the feature (credit balance) to auto top-up. */
+					featureId: string;
+					/** Whether auto top-up is enabled. Defaults to false. */
+					enabled?: boolean;
+					/** 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. Pass count to set the current window's consumed top-ups. */
+					purchaseLimit?: {
+						/** The time interval for the purchase limit window. */
+						interval: "hour" | "day" | "week" | "month";
+						/** Number of intervals in the purchase limit window. Defaults to 1. */
+						intervalCount?: number;
+						/** Maximum number of auto top-ups allowed within the interval. */
+						limit: number;
+						/** Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged. */
+						count?: number;
+					};
+					/** When true, auto top-up creates a send_invoice invoice instead of auto-charging. */
+					invoiceMode?: boolean;
+				}>;
+				/** List of overage spend limits per feature (caps overage spend). Defaults to []. */
+				spendLimits?: Array<{
+					/** Optional feature ID this spend limit applies to. */
+					featureId?: string;
+					/** Whether the overage spend limit is enabled. Defaults to false. */
+					enabled?: boolean;
+					/** How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. */
+					limitType?: "absolute" | "usage_percentage";
+					/** Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. */
+					overageLimit?: number;
+					/** When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. */
+					skipOverageBilling?: boolean;
+				}>;
+				/** List of hard usage caps per feature (max units per interval). Defaults to []. */
+				usageLimits?: Array<{
+					/** The feature this usage limit applies to. */
+					featureId: string;
+					/** Whether this usage limit is enabled. Defaults to true. */
+					enabled?: boolean;
+					/** Maximum units allowed per interval. */
+					limit: number;
+					/** Interval for the cap, aligned to the customer's billing cycle. */
+					interval: "day" | "week" | "month" | "year";
+					/** Window alignment. 'billing_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar. */
+					anchor?: "billing_cycle" | "utc";
+					/** When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. */
+					filter?: {
+						properties: Record<string, string | number | boolean>;
+					};
+				}>;
+				/** List of usage alert configurations per feature. Defaults to []. */
+				usageAlerts?: Array<{
+					/** The feature ID this alert applies to. */
+					featureId?: string;
+					/** Whether this usage alert is enabled. Defaults to true. */
+					enabled?: boolean;
+					/** 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:
+						| "usage"
+						| "usage_percentage"
+						| "remaining"
+						| "remaining_percentage";
+					/** What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage_limit: the cap of the usage limit with the same feature and filter. Defaults to "balance". */
+					basis?: "balance" | "included" | "recurring" | "usage_limit";
+					/** Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter. */
+					filter?: {
+						properties: Record<string, string | number | boolean>;
+					};
+					/** Optional user-defined label to distinguish multiple alerts on the same feature. */
+					name?: string;
+				}>;
+				/** List of overage allowed controls per feature. When enabled, usage can exceed balance. Defaults to []. */
+				overageAllowed?: Array<{
+					/** The feature ID this overage allowed control applies to. */
+					featureId: string;
+					/** Whether overage is allowed for this feature. Defaults to false. */
+					enabled?: boolean;
+				}>;
+			};
+			/** License links to add or override for this customer, keyed by license_plan_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance. */
+			upsertLicenses?: Array<{
+				licensePlanId: string;
+				versionSlug?: string;
+				included?: number;
+				prepaidOnly?: boolean;
+				customize?: {
+					price?: {
+						/** Base price amount for the plan, in major currency units (e.g. dollars). */
+						amount: number;
+						/** Billing interval (e.g. 'month', 'year'). */
+						interval:
+							| "one_off"
+							| "week"
+							| "month"
+							| "quarter"
+							| "semi_annual"
+							| "year";
+						/** Number of intervals per billing cycle. Defaults to 1. */
+						intervalCount?: number;
+						/** Base price amounts in additional currencies. The base 'amount' is in the org's default currency. */
+						additionalCurrencies?: Array<{
+							/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+							currency: string;
+							/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+							amount: number;
+						}>;
+					} | null;
+					addItems?: Array<{
+						/** Bills this many feature units when outstanding overage reaches it. */
+						thresholdBilling?: {
+							threshold: number;
+						} | null;
+						/** 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;
+						/** If true, customer has unlimited access to this feature. */
+						unlimited?: boolean;
+						/** Whether entity-level grants contribute to a shared customer balance. Defaults to false. */
+						pooled?: boolean;
+						/** Reset configuration for consumable features. Omit for non-consumable features like seats. */
+						reset?: {
+							/** Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. */
+							interval:
+								| "one_off"
+								| "minute"
+								| "hour"
+								| "day"
+								| "week"
+								| "month"
+								| "quarter"
+								| "semi_annual"
+								| "year";
+							/** Number of intervals between resets. Defaults to 1. */
+							intervalCount?: number;
+						};
+						/** Pricing for usage beyond included units. Omit for free features. */
+						price?: {
+							/** Price per billing_units after included usage. Either 'amount' or 'tiers' is required. */
+							amount?: number;
+							/** Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. */
+							additionalCurrencies?: Array<{
+								/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+								currency: string;
+								/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+								amount: number;
+							}>;
+							/** Tiered pricing. Either 'amount' or 'tiers' is required. */
+							tiers?: Array<{
+								to: number | "inf";
+								amount?: number;
+								flatAmount?: number;
+								/** Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. */
+								additionalCurrencies?: Array<{
+									/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+									currency: string;
+									/** Per-unit amount for this tier in this currency. */
+									amount?: number;
+									/** Flat amount for this tier in this currency, if the tier uses one. */
+									flatAmount?: number;
+								}>;
+							}>;
+							tierBehavior?: "graduated" | "volume";
+							/** Billing interval. For consumable features, should match reset.interval. */
+							interval:
+								| "one_off"
+								| "week"
+								| "month"
+								| "quarter"
+								| "semi_annual"
+								| "year";
+							/** Number of intervals per billing cycle. Defaults to 1. */
+							intervalCount?: number;
+							/** Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). Defaults to 1. */
+							billingUnits?: number;
+							/** 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. */
+							billingMethod: "prepaid" | "usage_based";
+							allocatedBilling?: "arrear" | "prorated_legacy";
+							/** Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. */
+							maxPurchase?: number | null;
+						};
+						/** Proration settings for prepaid features. Controls mid-cycle quantity change billing. */
+						proration?: {
+							/** Billing behavior when quantity increases mid-cycle. */
+							onIncrease:
+								| "bill_immediately"
+								| "prorate_immediately"
+								| "prorate_next_cycle"
+								| "bill_next_cycle";
+							/** Credit behavior when quantity decreases mid-cycle. */
+							onDecrease:
+								| "prorate"
+								| "prorate_immediately"
+								| "prorate_next_cycle"
+								| "none"
+								| "no_prorations";
+						};
+						/** Rollover config for unused units. If set, unused included units carry over. */
+						rollover?: {
+							/** Max rollover units. Omit for unlimited rollover. */
+							max?: number;
+							/** Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. */
+							maxPercentage?: number;
+							/** When rolled over units expire. */
+							expiryDurationType: "month" | "forever";
+							/** Number of periods before expiry. */
+							expiryDurationLength?: number;
+						};
+						/** Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit_schema). */
+						featureOverride?: {
+							/** For credit system features: replaces the feature's credit_schema entirely for customers on this plan. */
+							creditSchema?: Array<
+								| {
+										/** ID of the metered feature that draws from this credit system. */
+										meteredFeatureId: string;
+										/** Number of metered-feature units priced together. Defaults to one when omitted. */
+										billingUnits?: number;
+										/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+										dimensions?: Record<
+											string,
+											| {
+													/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+													match: Record<string, string | number | boolean>;
+													/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+													priority?: number;
+													tierBehavior: "graduated";
+													tiers: Array<{
+														/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+														to?: unknown;
+														/** Credits consumed per billing-unit group within this tier. */
+														creditCost: number;
+													}>;
+											  }
+											| {
+													/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+													match: Record<string, string | number | boolean>;
+													/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+													priority?: number;
+													/** Credits consumed per billing-unit group when this dimension matches. */
+													creditCost: number;
+											  }
+										>;
+										/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+										multipliers?: Record<
+											string,
+											{
+												/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+												match: Record<string, string | number | boolean>;
+												/** Multiplies the matched rate. All matching multipliers stack. */
+												factor?: number;
+												/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+												add?: number;
+											}
+										>;
+										tierBehavior: "graduated";
+										tiers: Array<{
+											/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+											to: number | "inf";
+											/** Credits consumed per billing-unit group within this tier. */
+											creditCost: number;
+										}>;
+								  }
+								| {
+										/** ID of the metered feature that draws from this credit system. */
+										meteredFeatureId: string;
+										/** Number of metered-feature units priced together. Defaults to one when omitted. */
+										billingUnits?: number;
+										/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+										dimensions?: Record<
+											string,
+											| {
+													/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+													match: Record<string, string | number | boolean>;
+													/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+													priority?: number;
+													tierBehavior: "graduated";
+													tiers: Array<{
+														/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+														to?: unknown;
+														/** Credits consumed per billing-unit group within this tier. */
+														creditCost: number;
+													}>;
+											  }
+											| {
+													/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+													match: Record<string, string | number | boolean>;
+													/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+													priority?: number;
+													/** Credits consumed per billing-unit group when this dimension matches. */
+													creditCost: number;
+											  }
+										>;
+										/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+										multipliers?: Record<
+											string,
+											{
+												/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+												match: Record<string, string | number | boolean>;
+												/** Multiplies the matched rate. All matching multipliers stack. */
+												factor?: number;
+												/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+												add?: number;
+											}
+										>;
+										/** Credits consumed per billing-unit group. */
+										creditCost: number;
+								  }
+							>;
+							/** For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's. */
+							markups?: {
+								/** Default percentage markup for customers on this plan. Use -100 to make usage free. */
+								defaultMarkup?: number;
+								/** Per-provider markup percentages for customers on this plan. */
+								providerMarkups?: Record<
+									string,
+									{
+										markup: number;
+									}
+								> | null;
+								/** Per-model markup overrides for customers on this plan. */
+								modelMarkups?: Record<
+									string,
+									{
+										markup?: number;
+										inputCost?: number;
+										outputCost?: number;
+									}
+								> | null;
+							};
+						};
+						entityFeatureId?: string;
+					}>;
+					removeItems?: Array<{
+						/** Match items linked to this feature. */
+						featureId?: string;
+						/** Match items with this billing method (prepaid or usage_based). */
+						billingMethod?: "prepaid" | "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. */
+						interval?:
+							| "one_off"
+							| "week"
+							| "month"
+							| "quarter"
+							| "semi_annual"
+							| "year"
+							| "one_off"
+							| "minute"
+							| "hour"
+							| "day"
+							| "week"
+							| "month"
+							| "quarter"
+							| "semi_annual"
+							| "year";
+						/** Match items with this interval_count. Disambiguates between items that share an interval but differ in count. */
+						intervalCount?: number;
+						/** Match items whose grant equals this included usage. Omitted is a wildcard. */
+						included?: number;
+					}>;
+				} | null;
+				metadata?: Record<string, unknown>;
+			}>;
+			/** License links to drop, keyed by license_plan_id. Parallel to remove_items. */
+			removeLicenses?: Array<{
+				licensePlanId: string;
+			}>;
+		} | null;
+	}>;
+	/** Plans offered as assignable licenses under this plan. Omit to leave them unchanged. */
+	licenses?: Array<{
+		licensePlanId: string;
+		versionSlug?: string;
+		included?: number;
+		prepaidOnly?: boolean;
+		customize?: {
+			price?: {
+				/** Base price amount for the plan, in major currency units (e.g. dollars). */
+				amount: number;
+				/** Billing interval (e.g. 'month', 'year'). */
+				interval:
+					| "one_off"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year";
+				/** Number of intervals per billing cycle. Defaults to 1. */
+				intervalCount?: number;
+				/** Base price amounts in additional currencies. The base 'amount' is in the org's default currency. */
+				additionalCurrencies?: Array<{
+					/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+					currency: string;
+					/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+					amount: number;
+				}>;
+			} | null;
+			addItems?: Array<{
+				/** Bills this many feature units when outstanding overage reaches it. */
+				thresholdBilling?: {
+					threshold: number;
+				} | null;
+				/** 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;
+				/** If true, customer has unlimited access to this feature. */
+				unlimited?: boolean;
+				/** Whether entity-level grants contribute to a shared customer balance. Defaults to false. */
+				pooled?: boolean;
+				/** Reset configuration for consumable features. Omit for non-consumable features like seats. */
+				reset?: {
+					/** Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. */
+					interval:
+						| "one_off"
+						| "minute"
+						| "hour"
+						| "day"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals between resets. Defaults to 1. */
+					intervalCount?: number;
+				};
+				/** Pricing for usage beyond included units. Omit for free features. */
+				price?: {
+					/** Price per billing_units after included usage. Either 'amount' or 'tiers' is required. */
+					amount?: number;
+					/** Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. */
+					additionalCurrencies?: Array<{
+						/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+						currency: string;
+						/** Price amount in this currency. Set explicitly per currency, not converted from the base amount. */
+						amount: number;
+					}>;
+					/** Tiered pricing. Either 'amount' or 'tiers' is required. */
+					tiers?: Array<{
+						to: number | "inf";
+						amount?: number;
+						flatAmount?: number;
+						/** Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. */
+						additionalCurrencies?: Array<{
+							/** Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). */
+							currency: string;
+							/** Per-unit amount for this tier in this currency. */
+							amount?: number;
+							/** Flat amount for this tier in this currency, if the tier uses one. */
+							flatAmount?: number;
+						}>;
+					}>;
+					tierBehavior?: "graduated" | "volume";
+					/** Billing interval. For consumable features, should match reset.interval. */
+					interval:
+						| "one_off"
+						| "week"
+						| "month"
+						| "quarter"
+						| "semi_annual"
+						| "year";
+					/** Number of intervals per billing cycle. Defaults to 1. */
+					intervalCount?: number;
+					/** Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). Defaults to 1. */
+					billingUnits?: number;
+					/** 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. */
+					billingMethod: "prepaid" | "usage_based";
+					allocatedBilling?: "arrear" | "prorated_legacy";
+					/** Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. */
+					maxPurchase?: number | null;
+				};
+				/** Proration settings for prepaid features. Controls mid-cycle quantity change billing. */
+				proration?: {
+					/** Billing behavior when quantity increases mid-cycle. */
+					onIncrease:
+						| "bill_immediately"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "bill_next_cycle";
+					/** Credit behavior when quantity decreases mid-cycle. */
+					onDecrease:
+						| "prorate"
+						| "prorate_immediately"
+						| "prorate_next_cycle"
+						| "none"
+						| "no_prorations";
+				};
+				/** Rollover config for unused units. If set, unused included units carry over. */
+				rollover?: {
+					/** Max rollover units. Omit for unlimited rollover. */
+					max?: number;
+					/** Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. */
+					maxPercentage?: number;
+					/** When rolled over units expire. */
+					expiryDurationType: "month" | "forever";
+					/** Number of periods before expiry. */
+					expiryDurationLength?: number;
+				};
+				/** Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit_schema). */
+				featureOverride?: {
+					/** For credit system features: replaces the feature's credit_schema entirely for customers on this plan. */
+					creditSchema?: Array<
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								tierBehavior: "graduated";
+								tiers: Array<{
+									/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+									to: number | "inf";
+									/** Credits consumed per billing-unit group within this tier. */
+									creditCost: number;
+								}>;
+						  }
+						| {
+								/** ID of the metered feature that draws from this credit system. */
+								meteredFeatureId: string;
+								/** Number of metered-feature units priced together. Defaults to one when omitted. */
+								billingUnits?: number;
+								/** Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies. */
+								dimensions?: Record<
+									string,
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											tierBehavior: "graduated";
+											tiers: Array<{
+												/** Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'. */
+												to: number | "inf";
+												/** Credits consumed per billing-unit group within this tier. */
+												creditCost: number;
+											}>;
+									  }
+									| {
+											/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+											match: Record<string, string | number | boolean>;
+											/** Breaks ties between dimensions that match the same number of keys. Higher wins. */
+											priority?: number;
+											/** Credits consumed per billing-unit group when this dimension matches. */
+											creditCost: number;
+									  }
+								>;
+								/** Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed. */
+								multipliers?: Record<
+									string,
+									{
+										/** Event properties this entry applies to. Every key must equal the tracked property, compared as strings. */
+										match: Record<string, string | number | boolean>;
+										/** Multiplies the matched rate. All matching multipliers stack. */
+										factor?: number;
+										/** Added to the rate after every factor is applied, in credits per billing-unit group. */
+										add?: number;
+									}
+								>;
+								/** Credits consumed per billing-unit group. */
+								creditCost: number;
+						  }
+					>;
+					/** For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's. */
+					markups?: {
+						/** Default percentage markup for customers on this plan. Use -100 to make usage free. */
+						defaultMarkup?: number;
+						/** Per-provider markup percentages for customers on this plan. */
+						providerMarkups?: Record<
+							string,
+							{
+								markup: number;
+							}
+						> | null;
+						/** Per-model markup overrides for customers on this plan. */
+						modelMarkups?: Record<
+							string,
+							{
+								markup?: number;
+								inputCost?: number;
+								outputCost?: number;
+							}
+						> | null;
+					};
+				};
+				entityFeatureId?: string;
+			}>;
+			removeItems?: Array<{
+				/** Match items linked to this feature. */
+				featureId?: string;
+				/** Match items with this billing method (prepaid or usage_based). */
+				billingMethod?: "prepaid" | "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. */
+				interval?:
+					| "one_off"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year"
+					| "one_off"
+					| "minute"
+					| "hour"
+					| "day"
+					| "week"
+					| "month"
+					| "quarter"
+					| "semi_annual"
+					| "year";
+				/** Match items with this interval_count. Disambiguates between items that share an interval but differ in count. */
+				intervalCount?: number;
+				/** Match items whose grant equals this included usage. Omitted is a wildcard. */
+				included?: number;
+			}>;
+		} | null;
+		metadata?: Record<string, unknown>;
+	}>;
+	/** Base plan id to attach this plan to. `null` detaches it from its base. Omit to leave the pointer unchanged. Nesting under the base's variants[] also links. */
+	baseVariantId?: string | null;
+};
+
+export const plan = (input: Plan): Plan => input;