--- title: "POST /v1/billing.create_schedule" method: POST path: "/v1/billing.create_schedule" tags: ["billing"] --- # POST /v1/billing.create_schedule `POST /v1/billing.create_schedule` Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times. Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time. ## Headers - `x-api-version` string, required ## Request body - object - `customer_id` string, required — The ID of the customer to create the schedule for. - `entity_id` string — Optional entity ID for an entity-scoped schedule. - `invoice_mode` object — Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase. - `enabled` boolean, required — When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method. - `enable_plan_immediately` boolean — If true, enables the plan immediately even though the invoice is not paid yet. - `finalize` boolean — If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review. - `invoice_template_id` string — ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice. - `net_terms_days` integer — Number of days the customer has to pay the invoice before it is due (Stripe days_until_due). - `discounts` object[] — List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code. - `reward_id` string — The ID of the reward to apply as a discount. - `promotion_code` string — The promotion code to apply as a discount. - `success_url` string — URL to redirect to after successful checkout. - `checkout_session_params` object — Additional parameters to pass into the creation of the Stripe checkout session. - `redirect_mode` 'always' | 'if_required' | 'never' — Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if_required' only redirects when needed, and 'never' disables redirects. - `billing_behavior` 'prorate_immediately' | 'none' — Whether to prorate the immediate phase. 'none' skips proration charges and credits. - `billing_cycle_anchor` 'now' — Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time. - `enable_plan_immediately` boolean — If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed. - `phases` object[], required — Ordered phase definitions for the schedule. - `starts_at` union — When this phase should start, in epoch milliseconds, or 'now' for the immediate phase. - number - 'now' - `starting_after` object — Relative start offset from the previous resolved schedule phase. - `duration_type` 'month' | 'year', required — The duration unit to offset this phase from the prior phase. - `duration_count` integer, required — How many duration_type periods after the prior phase to start. - `plans` object[], required — Plans to materialize for this phase. - `plan_id` string, required — The ID of the plan to schedule in this phase. - `feature_quantities` object[] — Optional prepaid feature quantities for this phase's plan. - `feature_id` string, required — The ID of the feature to set quantity for. - `quantity` number — The quantity of the feature. - `adjustable` boolean — Whether the customer can adjust the quantity. - `version` number — Optional explicit plan version to schedule. - `customize` object — Customize the plan to schedule. Can override price, replace items, or patch items with add_items and remove_items. - `price` object, nullable — Base price configuration for a plan. - `amount` number, required — Base price amount for the plan. - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year'). - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency. - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp'). - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount. - `items` object[] — Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / deprecated update_items. - `feature_id` string, required — The ID of the feature to configure. - `included` number — Number of free units included. Balance resets to this each interval for consumable features. - `unlimited` boolean — If true, customer has unlimited access to this feature. - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats. - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. - `interval_count` number — Number of intervals between resets. Defaults to 1. - `price` object — Pricing for usage beyond included units. Omit for free features. - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required. - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. - … - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required. - … - `tier_behavior` 'graduated' | 'volume' - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval. - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing. - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle. - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle. - `rollover` object — Rollover config for unused units. If set, unused included units carry over. - `max` number — Max rollover units. Omit for unlimited rollover. - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire. - `expiry_duration_length` number — Number of periods before expiry. - `add_items` object[] — Items to add to the plan. - `feature_id` string, required — The ID of the feature to configure. - `included` number — Number of free units included. Balance resets to this each interval for consumable features. - `unlimited` boolean — If true, customer has unlimited access to this feature. - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats. - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only. - `interval_count` number — Number of intervals between resets. Defaults to 1. - `price` object — Pricing for usage beyond included units. Omit for free features. - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required. - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'. - … - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required. - … - `tier_behavior` 'graduated' | 'volume' - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval. - `interval_count` number — Number of intervals per billing cycle. Defaults to 1. - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200). - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go. - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit. - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing. - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle. - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle. - `rollover` object — Rollover config for unused units. If set, unused included units carry over. - `max` number — Max rollover units. Omit for unlimited rollover. - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max. - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire. - `expiry_duration_length` number — Number of periods before expiry. - `remove_items` object[] — Filters selecting items to remove from the plan. - `feature_id` string — Match items linked to this feature. - `billing_method` 'prepaid' | 'usage_based' — Match items with this billing method (prepaid or usage_based). - `interval` union — 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. - 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year' - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year' - `interval_count` integer — Match items with this interval_count. Disambiguates between items that share an interval but differ in count. - `billing_controls` object — Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer. - `auto_topups` object[] — List of auto top-up configurations per feature. - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up. - `enabled` boolean — Whether auto top-up is enabled. - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased. - `quantity` number, required — Amount of credits to add per auto top-up. - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window's consumed top-ups. - … - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging. - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend). - `feature_id` string — Optional feature ID this spend limit applies to. - `enabled` boolean — Whether the overage spend limit is enabled. - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance. - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage. - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally. - `usage_limits` object[] — List of hard usage caps per feature (max units per interval). - `feature_id` string, required — The feature this usage limit applies to. - `enabled` boolean — Whether this usage limit is enabled. - `limit` number, required — Maximum units allowed per interval. - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle. - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature. - … - `usage_alerts` object[] — List of usage alert configurations per feature. - `feature_id` string — The feature ID this alert applies to. - `enabled` boolean — Whether this usage alert is enabled. - `threshold` number, required — The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100). - `threshold_type` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance. - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature. - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance. - `feature_id` string, required — The feature ID this overage allowed control applies to. - `enabled` boolean — Whether overage is allowed for this feature. - `subscription_id` string — A unique ID to identify this subscription. Useful when scheduling the same plan multiple times. - `billing_cycle_anchor` 'phase_start' — Pass 'phase_start' to reset the Stripe billing cycle anchor when this phase starts. ## Response `200` OK - object - `customer_id` string, required — The ID of the customer. - `entity_id` string, nullable, required — The entity ID for the schedule, or null when customer-level. - `status` 'created' | 'pending_payment', required — Whether the schedule is fully created or waiting for payment or confirmation to complete. - `schedule_id` string, nullable, required — The ID of the created schedule. Null when the schedule is waiting on Autumn checkout confirmation. - `phases` object[], required — Persisted phases in ascending starts_at order. Empty when waiting on Autumn checkout confirmation. - `phase_id` string, required — The ID of the persisted phase row. - `starts_at` number, required — When this phase starts, in epoch milliseconds. - `customer_product_ids` string[], required — Customer products materialized for this phase. - `invoice` object — Invoice details if an invoice was created. Only present when a charge was made. - `status` string, nullable, required — The status of the invoice (e.g., 'paid', 'open', 'draft'). - `stripe_id` string, required — The Stripe invoice ID. - `total` number, required — The total amount of the invoice in cents. - `currency` string, required — The three-letter ISO currency code (e.g., 'usd'). - `hosted_invoice_url` string, nullable, required — URL to the hosted invoice page where the customer can view and pay the invoice. - `payment_url` string, nullable, required — URL to redirect the customer to complete payment. Null if no payment action is required. - `required_action` object - `code` '3ds_required' | 'payment_method_required' | 'payment_failed' | 'payment_processing', required — The type of action required to complete the payment. - `reason` string, required — A human-readable explanation of why this action is required. --- [API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/revisions/29536933c0dc/schema)