Retrieves the list of your subscription schedules.
Parameters
- customerstring
Only return subscription schedules for the given customer.
More parameters
- canceled_
atobject - completed_
atobject - createdobject
- ending_
beforestring - limitinteger
- released_
atobject - scheduledboolean
- starting_
afterstring
Returns
A dictionary with a data
property that contains an array of up to limit
subscription schedules, starting after subscription schedule starting_
. Each entry in the array is a separate subscription schedule object. If no more subscription schedules are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/subscription_schedules", "has_more": false, "data": [ { "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 } ]}
Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_
or active
.
Parameters
- invoice_
nowboolean If the subscription schedule is
active
, indicates if a final invoice will be generated that contains any un-invoiced metered usage and new/pending proration invoice items. Defaults totrue
.
More parameters
- prorateboolean
Returns
The canceled subscription_
object. Its status will be canceled
and canceled_
will be the current time.
{ "id": "sub_sched_1Mr3owLkdIwHu7ix38CXMudt", "object": "subscription_schedule", "application": null, "canceled_at": 1680114847, "completed_at": null, "created": 1680114846, "current_phase": null, "customer": "cus_NcIPFRC981NmaY", "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": 1712339228, "invoice_settings": null, "items": [ { "metadata": {}, "plan": "price_1Mr3owLkdIwHu7ix0RyYpQzk", "price": "price_1Mr3owLkdIwHu7ix0RyYpQzk", "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": "canceled", "subscription": null, "test_clock": null}
Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_
or active
. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription
property and set the subscription’s ID to the released_
property.
Parameters
No parameters.
More parameters
- preserve_
cancel_ dateboolean
Returns
The released subscription_
object. Its status will be released
, released_
will be the current time, and released_
will be the ID of the subscription the subscription schedule managed prior to being released.
{ "id": "sub_sched_1Mr3hWLkdIwHu7ixA5zxZvNI", "object": "subscription_schedule", "application": null, "canceled_at": null, "completed_at": null, "created": 1680114386, "current_phase": null, "customer": "cus_NcII9GZkTPAnor", "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": 1712339228, "invoice_settings": null, "items": [ { "metadata": {}, "plan": "price_1Mr3hVLkdIwHu7ixWuJp9ew0", "price": "price_1Mr3hVLkdIwHu7ixWuJp9ew0", "quantity": 1, "tax_rates": [] } ], "metadata": {}, "on_behalf_of": null, "proration_behavior": "create_prorations", "start_date": 1680716828, "transfer_data": null, "trial_end": null } ], "released_at": 1680114386, "released_subscription": null, "renewal_interval": null, "status": "released", "subscription": null, "test_clock": null}
You can add one or multiple tax IDs to a customer or account. Customer and account tax IDs get displayed on related invoices and credit notes.
Related guides: Customer tax identification numbers, Account tax IDs
Test Clocks Test helper
A test clock enables deterministic control over objects in testmode. With a test clock, you can create objects at a frozen time in the past or future, and advance to a specific future time to observe webhooks and state changes. After the clock advances, you can either validate the current state of your scenario (and test your assumptions), change the current state of your scenario (and test more complex scenarios), or keep advancing forward in time.