Stripe: Subscription schedules schemas
29 Stripe schemas with complete fields and constraints.
← Subscription schedules operations · All schemas
Cancel a schedule — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes. Related guide: [Subscription schedules](https://docs.stripe.com/billing/subscriptions/subscription-schedules) |
application | JSON | Optional | |
application (anyOf 1) | JSON | Alternative | ID of the Connect Application that created the schedule. |
application (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
application (anyOf 1) (anyOf 2) | Model | Alternative | Expand PostApplicationFeesIdRefund — response body — application / object: application |
application (anyOf 1) (anyOf 3) | Model | Alternative | Expand Accept a quote — response body — application / value / deleted: True, object: application |
application (anyOf 2) | null | Alternative | |
billing_mode | Model | Required within parent | Expand Cancel a schedule — response body — billing mode |
canceled_at | JSON | Optional | |
canceled_at (anyOf 1) | JSON | Alternative | |
canceled_at (anyOf 1) (anyOf 1) | integer | Alternative | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. Format: unix-time |
canceled_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
canceled_at (anyOf 2) | null | Alternative | |
completed_at | JSON | Optional | |
completed_at (anyOf 1) | JSON | Alternative | |
completed_at (anyOf 1) (anyOf 1) | integer | Alternative | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. Format: unix-time |
completed_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
completed_at (anyOf 2) | null | Alternative | |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
current_phase | JSON | Optional | |
current_phase (anyOf 1) | JSON | Alternative | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
current_phase (anyOf 1) (anyOf 1) | Model | Alternative | Expand Cancel a schedule — response body — current phase value end date, start date |
current_phase (anyOf 2) | null | Alternative | |
customer | JSON | Required within parent | ID of the customer who owns the subscription schedule. |
customer (anyOf 1) | string | Alternative | Maximum length: 5000 |
customer (anyOf 2) | Model | Alternative | Expand Create a customer — response body |
customer (anyOf 3) | Model | Alternative | Expand Delete a customer — response body |
customer_account | JSON | Optional | |
customer_account (anyOf 1) | string | Alternative | ID of the account who owns the subscription schedule. Maximum length: 5000 |
customer_account (anyOf 2) | null | Alternative | |
default_settings | Model | Required within parent | Expand Cancel a schedule — response body — default settings |
end_behavior | string | Required within parent | Behavior of the subscription schedule and underlying subscription when it ends. Possible values are `release` or `cancel` with the default being `release`. `release` will end the subscription schedule and keep the underlying subscription running. `cancel` will end the subscription schedule and cancel the underlying subscription. Known values: cancel, none, release, renew |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | JSON | Optional | |
metadata (anyOf 1) | object | Alternative | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field |
metadata (anyOf 1).* | string | Additional keys | Maximum length: 500 |
metadata (anyOf 2) | null | Alternative | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: subscription_schedule |
pause_schedules | array | Optional | The pause schedules for this subscription schedule. |
pause_schedules[] | Model | Each item | Expand Cancel a schedule — response body — pause schedules item |
phases | array | Required within parent | Configuration for the subscription schedule's phases. |
phases[] | Model | Each item | Expand Cancel a schedule — response body — phases item |
released_at | JSON | Optional | |
released_at (anyOf 1) | JSON | Alternative | |
released_at (anyOf 1) (anyOf 1) | integer | Alternative | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. Format: unix-time |
released_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
released_at (anyOf 2) | null | Alternative | |
released_subscription | JSON | Optional | |
released_subscription (anyOf 1) | string | Alternative | ID of the subscription once managed by the subscription schedule (if it is released). Maximum length: 5000 |
released_subscription (anyOf 2) | null | Alternative | |
status | string | Required within parent | 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules). Known values: active, canceled, completed, not_started, released |
subscription | JSON | Optional | |
subscription (anyOf 1) | JSON | Alternative | ID of the subscription managed by the subscription schedule. |
subscription (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
subscription (anyOf 1) (anyOf 2) | Model | Alternative | Expand Pause a subscription — response body |
subscription (anyOf 2) | null | Alternative | |
test_clock | JSON | Optional | |
test_clock (anyOf 1) | JSON | Alternative | ID of the test clock this subscription schedule belongs to. |
test_clock (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
test_clock (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a test clock — response body |
test_clock (anyOf 2) | null | Alternative |
Referenced models: PostApplicationFeesIdRefund — response body — application / object: application, Create a customer — response body, Accept a quote — response body — application / value / deleted: True, object: application, Delete a customer — response body, Pause a subscription — response body, Cancel a schedule — response body — current phase value end date, start date, Cancel a schedule — response body — phases item, Cancel a schedule — response body — default settings, Cancel a schedule — response body — pause schedules item, Cancel a schedule — response body — billing mode, Create a test clock — response body
Cancel a schedule — response body — billing mode
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The billing mode of the subscription. |
flexible | JSON | Optional | |
flexible (anyOf 1) | JSON | Alternative | Configure behavior for flexible billing mode |
flexible (anyOf 1) (anyOf 1) | Model | Alternative | Expand Accept a quote — response body — subscription data billing mode flexible |
flexible (anyOf 2) | null | Alternative | |
type | string | Required within parent | Controls how prorations and invoices for subscriptions are calculated and orchestrated. Known values: classic, flexible |
updated_at | JSON | Optional | |
updated_at (anyOf 1) | integer | Alternative | Details on when the current billing_mode was adopted. Format: unix-time |
updated_at (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Accept a quote — response body — subscription data billing mode flexible
Cancel a schedule — response body — current phase value end date, start date
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
end_date | JSON | Required within parent | |
end_date (anyOf 1) | integer | Alternative | The end of this phase of the subscription schedule. Format: unix-time |
end_date (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
start_date | JSON | Required within parent | |
start_date (anyOf 1) | integer | Alternative | The start of this phase of the subscription schedule. Format: unix-time |
start_date (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Cancel a schedule — response body — default settings
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
application_fee_percent | JSON | Optional | |
application_fee_percent (anyOf 1) | JSON | Alternative | |
application_fee_percent (anyOf 1) (anyOf 1) | number | Alternative | A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account during this phase of the schedule. |
application_fee_percent (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
application_fee_percent (anyOf 2) | null | Alternative | |
automatic_tax | Model | Optional | Expand Cancel a schedule — response body — default settings automatic tax |
billing_cycle_anchor | string | Required within parent | Possible values are `phase_start` or `automatic`. If `phase_start` then billing cycle anchor of the subscription is set to the start of the phase when entering the phase. If `automatic` then the billing cycle anchor is automatically modified as needed when entering the phase. For more information, see the billing cycle [documentation](https://docs.stripe.com/billing/subscriptions/billing-cycle). Known values: automatic, phase_start |
billing_thresholds | JSON | Optional | |
billing_thresholds (anyOf 1) | JSON | Alternative | Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period |
billing_thresholds (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pause a subscription — response body — billing thresholds value amount gte, reset billing cycle anchor |
billing_thresholds (anyOf 2) | null | Alternative | |
collection_method | JSON | Optional | |
collection_method (anyOf 1) | string | Alternative | Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Known values: charge_automatically, send_invoice |
collection_method (anyOf 2) | null | Alternative | |
default_payment_method | JSON | Optional | |
default_payment_method (anyOf 1) | JSON | Alternative | ID of the default payment method for the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. |
default_payment_method (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
default_payment_method (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a Payment Method — response body |
default_payment_method (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
invoice_settings | Model | Required within parent | Expand Cancel a schedule — response body — default settings invoice settings |
on_behalf_of | JSON | Optional | |
on_behalf_of (anyOf 1) | JSON | Alternative | The account (if any) the charge was made on behalf of for charges associated with the schedule's subscription. See the Connect documentation for details. |
on_behalf_of (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
on_behalf_of (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create an account — response body |
on_behalf_of (anyOf 2) | null | Alternative | |
transfer_data | JSON | Optional | |
transfer_data (anyOf 1) | JSON | Alternative | The account (if any) the associated subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices. |
transfer_data (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pause a subscription — response body — transfer data value amount percent, destination |
transfer_data (anyOf 2) | null | Alternative |
Referenced models: Create an account — response body, Cancel a schedule — response body — default settings invoice settings, Create a Payment Method — response body, Cancel a schedule — response body — default settings automatic tax, Pause a subscription — response body — billing thresholds value amount gte, reset billing cycle anchor, Pause a subscription — response body — transfer data value amount percent, destination
Cancel a schedule — response body — default settings automatic tax
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
disabled_reason | JSON | Optional | |
disabled_reason (anyOf 1) | string | Alternative | If Stripe disabled automatic tax, this enum describes why. Known values: requires_location_inputs |
disabled_reason (anyOf 2) | null | Alternative | |
enabled | boolean | Required within parent | Whether Stripe automatically computes tax on invoices created during this phase. |
liability | JSON | Optional | |
liability (anyOf 1) | JSON | Alternative | The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account. |
liability (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pay an invoice — response body — issuer |
liability (anyOf 2) | null | Alternative |
Referenced models: Pay an invoice — response body — issuer
Cancel a schedule — response body — default settings invoice settings
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
account_tax_ids | JSON | Optional | |
account_tax_ids (anyOf 1) | array | Alternative | The account tax IDs associated with the subscription schedule. Will be set on invoices generated by the subscription schedule. |
account_tax_ids (anyOf 1)[] | JSON | Each item | |
account_tax_ids (anyOf 1)[] (anyOf 1) | string | Alternative | Maximum length: 5000 |
account_tax_ids (anyOf 1)[] (anyOf 2) | Model | Alternative | Expand Create a tax ID — response body |
account_tax_ids (anyOf 1)[] (anyOf 3) | Model | Alternative | Expand Delete a tax ID — response body |
account_tax_ids (anyOf 2) | null | Alternative | |
custom_fields | JSON | Optional | |
custom_fields (anyOf 1) | array | Alternative | A list of up to 4 custom fields to be displayed on the invoice. |
custom_fields (anyOf 1)[] | Model | Each item | Expand Pay an invoice — response body — custom fields Custom fields displayed on the invoice item |
custom_fields (anyOf 2) | null | Alternative | |
days_until_due | JSON | Optional | |
days_until_due (anyOf 1) | JSON | Alternative | |
days_until_due (anyOf 1) (anyOf 1) | integer | Alternative | Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. |
days_until_due (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
days_until_due (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
footer | JSON | Optional | |
footer (anyOf 1) | string | Alternative | Footer to be displayed on the invoice. Maximum length: 5000 |
footer (anyOf 2) | null | Alternative | |
issuer | Model | Required within parent | Expand Pay an invoice — response body — issuer |
Referenced models: Pay an invoice — response body — issuer, Delete a tax ID — response body, Pay an invoice — response body — custom fields Custom fields displayed on the invoice item, Create a tax ID — response body
Cancel a schedule — response body — pause schedules item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
key | string | Required within parent | A unique identifier for this pause schedule. Maximum length: 5000 |
pause | Model | Required within parent | Expand Cancel a schedule — response body — pause schedules item pause |
resume | JSON | Optional | |
resume (anyOf 1) | JSON | Alternative | Details about when and how the subscription resumes. |
resume (anyOf 1) (anyOf 1) | Model | Alternative | Expand Cancel a schedule — response body — pause schedules item resume value resume at, settings, status |
resume (anyOf 2) | null | Alternative |
Referenced models: Cancel a schedule — response body — pause schedules item pause, Cancel a schedule — response body — pause schedules item resume value resume at, settings, status
Cancel a schedule — response body — pause schedules item pause
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
pause_at | JSON | Required within parent | |
pause_at (anyOf 1) | integer | Alternative | Time at which the subscription pauses. Format: unix-time |
pause_at (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
settings | JSON | Optional | |
settings (anyOf 1) | JSON | Alternative | Settings controlling billing behavior during the pause. |
settings (anyOf 1) (anyOf 1) | Model | Alternative | Expand Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription |
settings (anyOf 2) | null | Alternative | |
status | Model | Required within parent | Expand Cancel a schedule — response body — pause schedules item pause status |
Referenced models: Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription, Cancel a schedule — response body — pause schedules item pause status
Cancel a schedule — response body — pause schedules item pause status
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
error | Model | Optional | Expand Cancel a schedule — response body — pause schedules item pause status error |
type | string | Required within parent | The lifecycle state of the pause operation. Known values: error, scheduled, succeeded |
Referenced models: Cancel a schedule — response body — pause schedules item pause status error
Cancel a schedule — response body — pause schedules item pause status error
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
code | string | Optional | A machine-readable error code. Maximum length: 5000 |
message | string | Required within parent | A description of the error. Maximum length: 5000 |
Cancel a schedule — response body — pause schedules item resume value resume at, settings, status
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
resume_at | JSON | Required within parent | |
resume_at (anyOf 1) | integer | Alternative | Time at which the subscription resumes. Format: unix-time |
resume_at (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
settings | Model | Required within parent | Expand Cancel a schedule — response body — pause schedules item resume value resume at, settings, status settings |
status | Model | Required within parent | Expand Cancel a schedule — response body — pause schedules item resume value resume at, settings, status status |
Referenced models: Cancel a schedule — response body — pause schedules item resume value resume at, settings, status settings, Cancel a schedule — response body — pause schedules item resume value resume at, settings, status status
Cancel a schedule — response body — pause schedules item resume value resume at, settings, status settings
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
billing_cycle_anchor | string | Required within parent | The billing cycle anchor that applies when the subscription is resumed. Known values: resume_at, unchanged |
payment_behavior | string | Required within parent | Controls whether Stripe attempts payment on the resumption invoice and how that affects the subscription's status. Known values: resume_on_payment_attempt, resume_on_payment_success |
proration_behavior | string | Required within parent | Determines how to handle prorations resulting from the billing_cycle_anchor change on resume. Known values: always_invoice, create_prorations, none |
Cancel a schedule — response body — pause schedules item resume value resume at, settings, status status
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
error | Model | Optional | Expand Cancel a schedule — response body — pause schedules item pause status error |
type | string | Required within parent | The lifecycle state of the resume operation. Known values: error, pending, requires_action, scheduled, succeeded |
Referenced models: Cancel a schedule — response body — pause schedules item pause status error
Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
bill_for | Model | Required within parent | Expand Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for |
invoicing_behavior | string | Required within parent | Determines how to handle debits and credits when pausing. Known values: invoice, pending_invoice_item |
type | string | Required within parent | The type of pause settings. Known values: subscription |
Referenced models: Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for
Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
outstanding_usage_through | Model | Required within parent | Expand Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for outstanding usage through |
unused_time_from | Model | Required within parent | Expand Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for unused time from |
Referenced models: Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for outstanding usage through, Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for unused time from
Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for outstanding usage through
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
type | string | Required within parent | The type of outstanding usage billing behavior. Known values: none, pause_at |
Cancel a schedule — response body — pause_schedules / item / pause / settings / value / invoicing_behavior: invoice, pending invoice item, type: subscription bill for unused time from
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
type | string | Required within parent | The type of unused time credit behavior. Known values: item_current_period_start, none, pause_at |
Cancel a schedule — response body — phases item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A phase describes the plans, coupon, and trialing status of a subscription for a predefined time period. |
add_invoice_items | array | Required within parent | A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. |
add_invoice_items[] | Model | Each item | Expand Cancel a schedule — response body — phases item add invoice items item |
application_fee_percent | JSON | Optional | |
application_fee_percent (anyOf 1) | JSON | Alternative | |
application_fee_percent (anyOf 1) (anyOf 1) | number | Alternative | A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account during this phase of the schedule. |
application_fee_percent (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
application_fee_percent (anyOf 2) | null | Alternative | |
automatic_tax | Model | Optional | Expand Cancel a schedule — response body — default settings automatic tax |
billing_cycle_anchor | JSON | Optional | |
billing_cycle_anchor (anyOf 1) | string | Alternative | Possible values are `phase_start` or `automatic`. If `phase_start` then billing cycle anchor of the subscription is set to the start of the phase when entering the phase. If `automatic` then the billing cycle anchor is automatically modified as needed when entering the phase. For more information, see the billing cycle [documentation](https://docs.stripe.com/billing/subscriptions/billing-cycle). Known values: automatic, phase_start |
billing_cycle_anchor (anyOf 2) | null | Alternative | |
billing_thresholds | JSON | Optional | |
billing_thresholds (anyOf 1) | JSON | Alternative | Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period |
billing_thresholds (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pause a subscription — response body — billing thresholds value amount gte, reset billing cycle anchor |
billing_thresholds (anyOf 2) | null | Alternative | |
collection_method | JSON | Optional | |
collection_method (anyOf 1) | string | Alternative | Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as `active`. Known values: charge_automatically, send_invoice |
collection_method (anyOf 2) | null | Alternative | |
currency | string | Required within parent | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency |
default_payment_method | JSON | Optional | |
default_payment_method (anyOf 1) | JSON | Alternative | ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer's invoice settings. |
default_payment_method (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
default_payment_method (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a Payment Method — response body |
default_payment_method (anyOf 2) | null | Alternative | |
default_tax_rates | JSON | Optional | |
default_tax_rates (anyOf 1) | array | Alternative | The default tax rates to apply to the subscription during this phase of the subscription schedule. |
default_tax_rates (anyOf 1)[] | Model | Each item | Expand Create a tax rate — response body |
default_tax_rates (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
discounts | array | Required within parent | The stackable discounts that will be applied to the subscription on this phase. Subscription item discounts are applied before subscription discounts. |
discounts[] | Model | Each item | Expand Cancel a schedule — response body — phases item discounts item |
end_date | JSON | Required within parent | |
end_date (anyOf 1) | integer | Alternative | The end of this phase of the subscription schedule. Format: unix-time |
end_date (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
invoice_settings | JSON | Optional | |
invoice_settings (anyOf 1) | JSON | Alternative | The invoice settings applicable during this phase. |
invoice_settings (anyOf 1) (anyOf 1) | Model | Alternative | Expand Cancel a schedule — response body — phases item invoice settings The invoice settings applicable during this phase account tax ids, custom fields, days until due, description, footer, issuer |
invoice_settings (anyOf 2) | null | Alternative | |
items | array | Required within parent | Subscription items to configure the subscription to during this phase of the subscription schedule. |
items[] | Model | Each item | Expand Cancel a schedule — response body — phases item items item |
metadata | JSON | Optional | |
metadata (anyOf 1) | object | Alternative | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to a phase. Metadata on a schedule's phase will update the underlying subscription's `metadata` when the phase is entered. Updating the underlying subscription's `metadata` directly will not affect the current phase's `metadata`. Additional keys: see wildcard field |
metadata (anyOf 1).* | string | Additional keys | Maximum length: 500 |
metadata (anyOf 2) | null | Alternative | |
on_behalf_of | JSON | Optional | |
on_behalf_of (anyOf 1) | JSON | Alternative | The account (if any) the charge was made on behalf of for charges associated with the schedule's subscription. See the Connect documentation for details. |
on_behalf_of (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
on_behalf_of (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create an account — response body |
on_behalf_of (anyOf 2) | null | Alternative | |
proration_behavior | string | Required within parent | When transitioning phases, controls how prorations are handled (if any). Possible values are `create_prorations`, `none`, and `always_invoice`. Known values: always_invoice, create_prorations, none |
start_date | JSON | Required within parent | |
start_date (anyOf 1) | integer | Alternative | The start of this phase of the subscription schedule. Format: unix-time |
start_date (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
transfer_data | JSON | Optional | |
transfer_data (anyOf 1) | JSON | Alternative | The account (if any) the associated subscription's payments will be attributed to for tax reporting, and where funds from each payment will be transferred to for each of the subscription's invoices. |
transfer_data (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pause a subscription — response body — transfer data value amount percent, destination |
transfer_data (anyOf 2) | null | Alternative | |
trial | boolean | Optional | If set to true the entire phase is counted as a trial and the customer will not be charged for any fees. |
trial_end | JSON | Optional | |
trial_end (anyOf 1) | JSON | Alternative | |
trial_end (anyOf 1) (anyOf 1) | integer | Alternative | When the trial ends within the phase. Format: unix-time |
trial_end (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
trial_end (anyOf 2) | null | Alternative |
Referenced models: Create an account — response body, Cancel a schedule — response body — phases item discounts item, Cancel a schedule — response body — phases item invoice settings The invoice settings applicable during this phase account tax ids, custom fields, days until due, description, footer, issuer, Create a Payment Method — response body, Cancel a schedule — response body — default settings automatic tax, Pause a subscription — response body — billing thresholds value amount gte, reset billing cycle anchor, Cancel a schedule — response body — phases item add invoice items item, Cancel a schedule — response body — phases item items item, Pause a subscription — response body — transfer data value amount percent, destination, Create a tax rate — response body
Cancel a schedule — response body — phases item add invoice items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | An Add Invoice Item describes the prices and quantities that will be added as pending invoice items when entering a phase. |
discountable | JSON | Optional | |
discountable (anyOf 1) | boolean | Alternative | Controls whether discounts apply to this invoice item. Defaults to true if no value is provided. |
discountable (anyOf 2) | null | Alternative | |
discounts | array | Required within parent | The stackable discounts that will be applied to the item. |
discounts[] | Model | Each item | Expand Cancel a schedule — response body — phases item discounts item |
metadata | JSON | Optional | |
metadata (anyOf 1) | object | Alternative | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field |
metadata (anyOf 1).* | string | Additional keys | Maximum length: 500 |
metadata (anyOf 2) | null | Alternative | |
period | Model | Required within parent | Expand Cancel a schedule — response body — phases item add invoice items item period |
price | JSON | Required within parent | ID of the price used to generate the invoice item. |
price (anyOf 1) | string | Alternative | Maximum length: 5000 |
price (anyOf 2) | Model | Alternative | Expand Create a price — response body |
price (anyOf 3) | Model | Alternative | Expand Create a trial offer — response body — price / deleted: True, object: price |
quantity | JSON | Optional | |
quantity (anyOf 1) | JSON | Alternative | |
quantity (anyOf 1) (anyOf 1) | integer | Alternative | The quantity of the invoice item. |
quantity (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
quantity (anyOf 2) | null | Alternative | |
tax_rates | JSON | Optional | |
tax_rates (anyOf 1) | array | Alternative | The tax rates which apply to the item. When set, the `default_tax_rates` do not apply to this item. |
tax_rates (anyOf 1)[] | Model | Each item | Expand Create a tax rate — response body |
tax_rates (anyOf 2) | null | Alternative |
Referenced models: Create a trial offer — response body — price / deleted: True, object: price, Cancel a schedule — response body — phases item discounts item, Create a price — response body, Cancel a schedule — response body — phases item add invoice items item period, Create a tax rate — response body
Cancel a schedule — response body — phases item add invoice items item period
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
end | Model | Required within parent | Expand Cancel a schedule — response body — phases item add invoice items item period end |
start | Model | Required within parent | Expand Cancel a schedule — response body — phases item add invoice items item period start |
Referenced models: Cancel a schedule — response body — phases item add invoice items item period end, Cancel a schedule — response body — phases item add invoice items item period start
Cancel a schedule — response body — phases item add invoice items item period end
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
timestamp | JSON | Optional | |
timestamp (anyOf 1) | integer | Alternative | A precise Unix timestamp for the end of the invoice item period. Must be greater than or equal to `period.start`. Format: unix-time |
timestamp (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
type | string | Required within parent | Select how to calculate the end of the invoice item period. Known values: min_item_period_end, phase_end, timestamp |
Cancel a schedule — response body — phases item add invoice items item period start
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
timestamp | JSON | Optional | |
timestamp (anyOf 1) | integer | Alternative | A precise Unix timestamp for the start of the invoice item period. Must be less than or equal to `period.end`. Format: unix-time |
timestamp (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
type | string | Required within parent | Select how to calculate the start of the invoice item period. Known values: max_item_period_start, phase_start, timestamp |
Cancel a schedule — response body — phases item discounts item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
coupon | JSON | Optional | |
coupon (anyOf 1) | JSON | Alternative | ID of the coupon to create a new discount for. |
coupon (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
coupon (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a coupon — response body |
coupon (anyOf 2) | null | Alternative | |
discount | JSON | Optional | |
discount (anyOf 1) | JSON | Alternative | ID of an existing discount on the object (or one of its ancestors) to reuse. |
discount (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
discount (anyOf 1) (anyOf 2) | Model | Alternative | Expand Get Customers Customer Discount — response body |
discount (anyOf 2) | null | Alternative | |
promotion_code | JSON | Optional | |
promotion_code (anyOf 1) | JSON | Alternative | ID of the promotion code to create a new discount for. |
promotion_code (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
promotion_code (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a promotion code — response body |
promotion_code (anyOf 2) | null | Alternative |
Referenced models: Create a coupon — response body, Get Customers Customer Discount — response body, Create a promotion code — response body
Cancel a schedule — response body — phases item invoice settings The invoice settings applicable during this phase account tax ids, custom fields, days until due, description, footer, issuer
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
account_tax_ids | JSON | Optional | |
account_tax_ids (anyOf 1) | array | Alternative | The account tax IDs associated with this phase of the subscription schedule. Will be set on invoices generated by this phase of the subscription schedule. |
account_tax_ids (anyOf 1)[] | JSON | Each item | |
account_tax_ids (anyOf 1)[] (anyOf 1) | string | Alternative | Maximum length: 5000 |
account_tax_ids (anyOf 1)[] (anyOf 2) | Model | Alternative | Expand Create a tax ID — response body |
account_tax_ids (anyOf 1)[] (anyOf 3) | Model | Alternative | Expand Delete a tax ID — response body |
account_tax_ids (anyOf 2) | null | Alternative | |
custom_fields | JSON | Optional | |
custom_fields (anyOf 1) | array | Alternative | A list of up to 4 custom fields to be displayed on the invoice. |
custom_fields (anyOf 1)[] | Model | Each item | Expand Pay an invoice — response body — custom fields Custom fields displayed on the invoice item |
custom_fields (anyOf 2) | null | Alternative | |
days_until_due | JSON | Optional | |
days_until_due (anyOf 1) | JSON | Alternative | |
days_until_due (anyOf 1) (anyOf 1) | integer | Alternative | Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be `null` for subscription schedules where `billing=charge_automatically`. |
days_until_due (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
days_until_due (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000 |
description (anyOf 2) | null | Alternative | |
footer | JSON | Optional | |
footer (anyOf 1) | string | Alternative | Footer to be displayed on the invoice. Maximum length: 5000 |
footer (anyOf 2) | null | Alternative | |
issuer | JSON | Optional | |
issuer (anyOf 1) | JSON | Alternative | The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. |
issuer (anyOf 1) (anyOf 1) | Model | Alternative | Expand Pay an invoice — response body — issuer |
issuer (anyOf 2) | null | Alternative |
Referenced models: Pay an invoice — response body — issuer, Delete a tax ID — response body, Pay an invoice — response body — custom fields Custom fields displayed on the invoice item, Create a tax ID — response body
Cancel a schedule — response body — phases item items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A phase item describes the price and quantity of a phase. |
billing_thresholds | JSON | Optional | |
billing_thresholds (anyOf 1) | JSON | Alternative | Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period |
billing_thresholds (anyOf 1) (anyOf 1) | Model | Alternative | Expand Create a subscription item — response body — billing thresholds value usage gte |
billing_thresholds (anyOf 2) | null | Alternative | |
discounts | array | Required within parent | The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount. |
discounts[] | Model | Each item | Expand Cancel a schedule — response body — phases item discounts item |
metadata | JSON | Optional | |
metadata (anyOf 1) | object | Alternative | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an item. Metadata on this item will update the underlying subscription item's `metadata` when the phase is entered. Additional keys: see wildcard field |
metadata (anyOf 1).* | string | Additional keys | Maximum length: 500 |
metadata (anyOf 2) | null | Alternative | |
price | JSON | Required within parent | ID of the price to which the customer should be subscribed. |
price (anyOf 1) | string | Alternative | Maximum length: 5000 |
price (anyOf 2) | Model | Alternative | Expand Create a price — response body |
price (anyOf 3) | Model | Alternative | Expand Create a trial offer — response body — price / deleted: True, object: price |
quantity | JSON | Optional | |
quantity (anyOf 1) | integer | Alternative | Quantity of the plan to which the customer should be subscribed. |
quantity (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
tax_rates | JSON | Optional | |
tax_rates (anyOf 1) | array | Alternative | The tax rates which apply to this `phase_item`. When set, the `default_tax_rates` on the phase do not apply to this `phase_item`. |
tax_rates (anyOf 1)[] | Model | Each item | Expand Create a tax rate — response body |
tax_rates (anyOf 2) | null | Alternative |
Referenced models: Create a trial offer — response body — price / deleted: True, object: price, Cancel a schedule — response body — phases item discounts item, Create a price — response body, Create a subscription item — response body — billing thresholds value usage gte, Create a tax rate — response body
Create a schedule — request body — body default settings
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Object representing the subscription schedule's default settings. |
application_fee_percent | number | Optional | |
automatic_tax | object | Optional | |
automatic_tax.enabled | boolean | Required within parent | |
automatic_tax.liability | object | Optional | |
automatic_tax.liability.account | string | Optional | |
automatic_tax.liability.type | string | Required within parent | One of: account, self |
billing_cycle_anchor | string | Optional | One of: automatic, phase_start |
billing_thresholds | JSON | Optional | |
billing_thresholds (anyOf 1) | object | Alternative | |
billing_thresholds (anyOf 1).amount_gte | integer | Optional | |
billing_thresholds (anyOf 1).reset_billing_cycle_anchor | boolean | Optional | |
billing_thresholds (anyOf 2) | string | Alternative | One of: |
collection_method | string | Optional | One of: charge_automatically, send_invoice |
default_payment_method | string | Optional | Maximum length: 5000 |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Maximum length: 500 |
description (anyOf 2) | string | Alternative | One of: |
invoice_settings | Model | Optional | Expand Create a schedule — request body — body default settings invoice settings |
on_behalf_of | JSON | Optional | |
on_behalf_of (anyOf 1) | string | Alternative | |
on_behalf_of (anyOf 2) | string | Alternative | One of: |
transfer_data | JSON | Optional | |
transfer_data (anyOf 1) | object | Alternative | |
transfer_data (anyOf 1).amount_percent | number | Optional | |
transfer_data (anyOf 1).destination | string | Required within parent | |
transfer_data (anyOf 2) | string | Alternative | One of: |
Referenced models: Create a schedule — request body — body default settings invoice settings
Create a schedule — request body — body default settings invoice settings
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
account_tax_ids | JSON | Optional | |
account_tax_ids (anyOf 1) | array | Alternative | |
account_tax_ids (anyOf 1)[] | string | Each item | Maximum length: 5000 |
account_tax_ids (anyOf 2) | string | Alternative | One of: |
custom_fields | JSON | Optional | |
custom_fields (anyOf 1) | array | Alternative | |
custom_fields (anyOf 1)[] | object | Each item | |
custom_fields (anyOf 1)[].name | string | Required within parent | Maximum length: 40 |
custom_fields (anyOf 1)[].value | string | Required within parent | Maximum length: 140 |
custom_fields (anyOf 2) | string | Alternative | One of: |
days_until_due | integer | Optional | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Maximum length: 1500 |
description (anyOf 2) | string | Alternative | One of: |
footer | JSON | Optional | |
footer (anyOf 1) | string | Alternative | Maximum length: 5000 |
footer (anyOf 2) | string | Alternative | One of: |
issuer | object | Optional | |
issuer.account | string | Optional | |
issuer.type | string | Required within parent | One of: account, self |
Create a schedule — request body — body phases item add invoice items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
discountable | boolean | Optional | |
discounts | array | Optional | |
discounts[] | object | Each item | |
discounts[].coupon | string | Optional | Maximum length: 5000 |
discounts[].discount | string | Optional | Maximum length: 5000 |
discounts[].promotion_code | string | Optional | Maximum length: 5000 |
metadata | object | Optional | Additional keys: see wildcard field |
metadata.* | string | Additional keys | |
period | object | Optional | |
period.end | object | Required within parent | |
period.end.timestamp | integer | Optional | Format: unix-time |
period.end.type | string | Required within parent | One of: min_item_period_end, phase_end, timestamp |
period.start | object | Required within parent | |
period.start.timestamp | integer | Optional | Format: unix-time |
period.start.type | string | Required within parent | One of: max_item_period_start, phase_start, timestamp |
price | string | Optional | Maximum length: 5000 |
price_data | object | Optional | |
price_data.currency | string | Required within parent | Format: currency |
price_data.product | string | Required within parent | Maximum length: 5000 |
price_data.tax_behavior | string | Optional | One of: exclusive, inclusive, unspecified |
price_data.unit_amount | integer | Optional | |
price_data.unit_amount_decimal | string | Optional | Format: decimal |
quantity | integer | Optional | |
tax_rates | JSON | Optional | |
tax_rates (anyOf 1) | array | Alternative | |
tax_rates (anyOf 1)[] | string | Each item | Maximum length: 5000 |
tax_rates (anyOf 2) | string | Alternative | One of: |
Create a schedule — request body — body phases item items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
billing_thresholds | JSON | Optional | |
billing_thresholds (anyOf 1) | object | Alternative | |
billing_thresholds (anyOf 1).usage_gte | integer | Required within parent | |
billing_thresholds (anyOf 2) | string | Alternative | One of: |
discounts | JSON | Optional | |
discounts (anyOf 1) | array | Alternative | |
discounts (anyOf 1)[] | object | Each item | |
discounts (anyOf 1)[].coupon | string | Optional | Maximum length: 5000 |
discounts (anyOf 1)[].discount | string | Optional | Maximum length: 5000 |
discounts (anyOf 1)[].promotion_code | string | Optional | Maximum length: 5000 |
discounts (anyOf 2) | string | Alternative | One of: |
metadata | object | Optional | Additional keys: see wildcard field |
metadata.* | string | Additional keys | |
price | string | Optional | Maximum length: 5000 |
price_data | Model | Optional | Expand Update a subscription — request body — body items item price data |
quantity | integer | Optional | |
tax_rates | JSON | Optional | |
tax_rates (anyOf 1) | array | Alternative | |
tax_rates (anyOf 1)[] | string | Each item | Maximum length: 5000 |
tax_rates (anyOf 2) | string | Alternative | One of: |
Referenced models: Update a subscription — request body — body items item price data