import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.createSchedule({
customerId: "cus_123",
phases: [
{
startsAt: 1735689600000,
plans: [
{
planId: "trial_plan",
},
],
},
{
startsAt: 1736899200000,
plans: [
{
planId: "pro_plan",
},
],
},
],
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.create_schedule(
customer_id="cus_123",
phases=[
{
"starts_at": 1735689600000,
"plans": [
{
"plan_id": "trial_plan",
},
],
},
{
"starts_at": 1736899200000,
"plans": [
{
"plan_id": "pro_plan",
},
],
},
],
redirect_mode="if_required",
)curl --request POST \
--url https://api.useautumn.com/v1/billing.create_schedule \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"phases": [
{
"starts_at": 1735689600000,
"plans": [
{
"plan_id": "trial_plan"
}
]
},
{
"starts_at": 1736899200000,
"plans": [
{
"plan_id": "pro_plan"
}
]
}
]
}
'{
"customer_id": "cus_123",
"entity_id": null,
"status": "created",
"schedule_id": "sch_1234",
"phases": [
{
"phase_id": "sphs_1111",
"starts_at": 1735689600000,
"customer_product_ids": [
"cus_prod_1111"
]
},
{
"phase_id": "sphs_2222",
"starts_at": 1736899200000,
"customer_product_ids": [
"cus_prod_2222"
]
}
],
"invoice": null,
"payment_url": null
}
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.
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.billing.createSchedule({
customerId: "cus_123",
phases: [
{
startsAt: 1735689600000,
plans: [
{
planId: "trial_plan",
},
],
},
{
startsAt: 1736899200000,
plans: [
{
planId: "pro_plan",
},
],
},
],
});from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.billing.create_schedule(
customer_id="cus_123",
phases=[
{
"starts_at": 1735689600000,
"plans": [
{
"plan_id": "trial_plan",
},
],
},
{
"starts_at": 1736899200000,
"plans": [
{
"plan_id": "pro_plan",
},
],
},
],
redirect_mode="if_required",
)curl --request POST \
--url https://api.useautumn.com/v1/billing.create_schedule \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-api-version: <x-api-version>' \
--data '
{
"customer_id": "cus_123",
"phases": [
{
"starts_at": 1735689600000,
"plans": [
{
"plan_id": "trial_plan"
}
]
},
{
"starts_at": 1736899200000,
"plans": [
{
"plan_id": "pro_plan"
}
]
}
]
}
'{
"customer_id": "cus_123",
"entity_id": null,
"status": "created",
"schedule_id": "sch_1234",
"phases": [
{
"phase_id": "sphs_1111",
"starts_at": 1735689600000,
"customer_product_ids": [
"cus_prod_1111"
]
},
{
"phase_id": "sphs_2222",
"starts_at": 1736899200000,
"customer_product_ids": [
"cus_prod_2222"
]
}
],
"invoice": null,
"payment_url": null
}
Body Parameters
Response
{
"customer_id": "cus_123",
"entity_id": null,
"status": "created",
"schedule_id": "sch_1234",
"phases": [
{
"phase_id": "sphs_1111",
"starts_at": 1735689600000,
"customer_product_ids": [
"cus_prod_1111"
]
},
{
"phase_id": "sphs_2222",
"starts_at": 1736899200000,
"customer_product_ids": [
"cus_prod_2222"
]
}
],
"invoice": null,
"payment_url": null
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
The ID of the customer to create the schedule for.
Ordered phase definitions for the schedule.
Show child attributes
Show child attributes
Optional entity ID for an entity-scoped schedule.
Free trial configuration applied to every plan in the immediate phase.
Show child attributes
Show child attributes
Three-letter Stripe-supported currency code used to bill the immediate phase (for example, 'usd').
3Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase.
Show child attributes
Show child attributes
List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
Show child attributes
Show child attributes
URL to redirect to after successful checkout.
Additional parameters to pass into the creation of the Stripe checkout session.
Show child attributes
Show child attributes
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.
always, if_required, never Whether to prorate the immediate phase. 'none' skips proration charges and credits, 'bill_difference' bills the larger of the full-period price difference and the prorated amount (full difference on upgrades, prorated credit on downgrades).
prorate_immediately, none, bill_difference If true, skips any billing changes for the schedule.
Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time.
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.
Deprecated and ignored. Active plans the schedule does not list keep running until a listed plan in their group replaces them or the schedule ends.
Plans billed with the immediate phase that the schedule never expires or replaces. No phase may declare a plan in the same group and scope.
Show child attributes
Show child attributes
Response
OK
The ID of the customer.
The entity ID for the schedule, or null when customer-level.
Whether the schedule is fully created or waiting for payment or confirmation to complete.
created, pending_payment The ID of the created schedule. Null when the schedule is waiting on Autumn checkout confirmation.
Persisted phases in ascending starts_at order. Empty when waiting on Autumn checkout confirmation.
Show child attributes
Show child attributes
URL to redirect the customer to complete payment. Null if no payment action is required.
Invoice details if an invoice was created. Only present when a charge was made.
Show child attributes
Show child attributes
Show child attributes
Show child attributes