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}

Update a schedule

POST / v1 / subscription_schedules /:id

Updates an existing subscription schedule.

Parameters

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. Note that past phases can be omitted.
proration _ behavior enum If the update changes the billing configuration (item price, quantity, etc.) of the current phase, indicates how prorations from this change should be handled. The default value is create_prorations. Possible enum values always_invoice Prorate changes, and force an invoice to be immediately created for any prorations. create_prorations Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice. none Does not create any prorations.

More parameters

default _ settings object
end _ behavior enum

Returns

Returns an updated subscription schedule object if the call succeeded.

Response

{ "id": "sub_sched_1Mr3YdLkdIwHu7ixjop3qtff", "object": "subscription_schedule", "application": null, "canceled_at": null, "completed_at": null, "created": 1680113835, "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, "end_date": 1712339228, "invoice_settings": null, "items": [ { "metadata": {}, "plan": "price_1Mr3YcLkdIwHu7ixYCFhXHNb", "price": "price_1Mr3YcLkdIwHu7ixYCFhXHNb", "quantity": 1, "tax_rates": [] } ], "metadata": {}, "on_behalf_of": null, "proration_behavior": "create_prorations", "start_date": 1680716828, "transfer_data": null, "trial_end": null } ], "released_at": null, "released_subscription": null, "renewal_interval": null, "status": "not_started", "subscription": null, "test_clock": null}

Retrieve a schedule

GET / v1 / subscription_schedules /:id

Retrieves the details of an existing subscription schedule. You only need to supply the unique subscription schedule identifier that was returned upon subscription schedule creation.

Parameters

No parameters.

Returns

Returns a subscription schedule object if a valid identifier was provided.

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}