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.
{ "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}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