Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

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.

post/v1/billing.create_schedule

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to create the schedule for.

entity_idstring

Optional entity ID for an entity-scoped schedule.

success_urlstring

URL to redirect to after successful checkout.

checkout_session_paramsobject

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_immediatelyboolean

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.

Example request

{
  "customer_id": "cus_123",
  "phases": [
    {
      "starts_at": 1735689600000,
      "plans": [
        {
          "plan_id": "trial_plan"
        }
      ]
    },
    {
      "starts_at": 1736899200000,
      "plans": [
        {
          "plan_id": "pro_plan"
        }
      ]
    }
  ]
}

Response

OK

customer_idstring required

The ID of the customer.

entity_idstring 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_idstring nullable required

The ID of the created schedule. Null when the schedule is waiting on Autumn checkout confirmation.

payment_urlstring nullable required

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

Example 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
}