Skip to main content
POST
/
v1
/
billing.create_schedule
Typescript (SDK)
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",
        },
      ],
    },
  ],
});
{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.2.0
required

Body

application/json
​
customer_id
string
required

The ID of the customer to create the schedule for.

​
phases
tuple
required

Ordered phase definitions for the schedule.

​
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.

​
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
enum<string>
default:if_required

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.

Available options:
always,
if_required,
never
​
billing_behavior
enum<string>

Whether to prorate the immediate phase. 'none' skips proration charges and credits.

Available options:
prorate_immediately,
none
​
billing_cycle_anchor
any

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.

Response

200 - application/json

OK

​
customer_id
string
required

The ID of the customer.

​
entity_id
string | null
required

The entity ID for the schedule, or null when customer-level.

​
status
enum<string>
required

Whether the schedule is fully created or waiting for payment or confirmation to complete.

Available options:
created,
pending_payment
​
schedule_id
string | null
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.

​
payment_url
string | null
required

URL to redirect the customer to complete payment. Null if no payment action is required.

​
invoice
object

Invoice details if an invoice was created. Only present when a charge was made.

​
required_action
object