Subscription Schedules

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.

Related guide: Subscription schedules

Was this section helpful? Yes No

Create a schedule

POST / v1 / subscription_schedules

Update a schedule

POST / v1 / subscription_schedules /:id

Retrieve a schedule

GET / v1 / subscription_schedules /:id

List all schedules

GET / v1 / subscription_schedules

Cancel a schedule

POST / v1 / subscription_schedules /:id / cancel

Release a schedule

POST / v1 / subscription_schedules /:id / release

The Subscription Schedule object

Attributes

id string Unique identifier for the object.
current _ phase nullable object Object representing the start and end dates for the current phase of the subscription schedule, if it is active.
customer string Expandable ID of the customer who owns the subscription schedule.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
phases array of objects Configuration for the subscription schedule’s phases.
status enum The present status of the subscription schedule. Possible values are not_started, active, completed, released, and canceled. You can read more about the different states in our behavior guide. Possible enum values active canceled completed not_started released
subscription nullable string Expandable ID of the subscription managed by the subscription schedule.

More attributes

object string, value is "subscription_schedule"
application nullable string Expandable Connect only
billing _ mode object
canceled _ at nullable timestamp
completed _ at nullable timestamp
created timestamp
customer _ account nullable string
default _ settings object
end _ behavior enum
livemode boolean
released _ at nullable timestamp
released _ subscription nullable string
test _ clock nullable string Expandable

Create a schedule

POST / v1 / subscription_schedules

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

Parameters

customer string The identifier of the customer to create the subscription schedule for.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
phases array of objects List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the end_date of one phase will always equal the start_date of the next phase.
start _ date timestamp | string, value is "now" When the subscription schedule starts. We recommend using now so that it starts the subscription immediately, and to avoid unexpected behavior due to request delays or clock skew resulting in a slightly backdated or postdated start. You can also use a Unix timestamp to backdate the subscription so that it starts on a past date, or set a future date for the subscription to start on.

More parameters

billing _ mode object
customer _ account string
default _ settings object
end _ behavior enum
from _ subscription string

Returns

Returns a subscription schedule object if the call succeeded.

Response

{ "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff", "object": "subscription_schedule", "application": null, "canceled_at": null, "completed_at": null, "created": 1724058651, "current_phase": null, "customer": "cus_NcI8FsMbh0OeFs", "default_settings": { "application_fee_percent": null, "automatic_tax": { "enabled": false, "liability": null }, "billing_cycle_anchor": "automatic", "collection_method": "charge_automatically", "default_payment_method": null, "default_source": null, "description": null, "invoice_settings": { "issuer": { "type": "self" } }, "on_behalf_of": null, "transfer_data": null }, "end_behavior": "release", "livemode": false, "metadata": {}, "phases": [ { "add_invoice_items": [], "application_fee_percent": null, "billing_cycle_anchor": null, "collection_method": null, "currency": "usd", "default_payment_method": null, "default_tax_rates": [], "description": null, "discounts": null, "end_date": 1818666418, "invoice_settings": null, "items": [ { "discounts": null, "metadata": {}, "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb", "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb", "quantity": 1, "tax_rates": [] } ], "metadata": {}, "on_behalf_of": null, "proration_behavior": "create_prorations", "start_date": 1787130418, "transfer_data": null, "trial_end": null } ], "released_at": null, "released_subscription": null, "renewal_interval": null, "status": "not_started", "subscription": null, "test_clock": null}