API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/subscription_schedules
List all schedules
Retrieves the list of your subscription schedules.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
canceled_at | query | one of multiple schemas | Only return subscription schedules that were created canceled the given date interval. |
completed_at | query | one of multiple schemas | Only return subscription schedules that completed during the given date interval. |
created | query | one of multiple schemas | Only return subscription schedules that were created during the given date interval. |
customer | query | string | Only return subscription schedules for the given customer. The response will not include subscription schedules for customers with a test clock attached if this parameter is not set. |
customer_account | query | string | Only return subscription schedules for the given account. |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
released_at | query | one of multiple schemas | Only return subscription schedules that were released during the given date interval. |
scheduled | query | boolean | Only return subscription schedules that have not started yet. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of subscription_schedule | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/subscription_schedules
Create a schedule
Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.
Request parameters
| Field | Type | Description |
|---|---|---|
billing_mode | object | Controls how prorations and invoices for subscriptions are calculated and orchestrated. |
customer | string | The identifier of the customer to create the subscription schedule for. |
customer_account | string | The identifier of the account to create the subscription schedule for. |
default_settings | object | Object representing the subscription schedule's default settings. |
end_behavior | string | 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. |
expand | array of string | Specifies which fields in the response should be expanded. |
from_subscription | string | Migrate an existing subscription to be managed by a subscription schedule. If this parameter is set, a subscription schedule will be created using the subscription's item(s), set to auto-renew using the subscription's interval. When using this parameter, other parameters (such as phase values) cannot be set. To create a subscription schedule with other modifications, we recommend making two separate API calls. |
metadata | one of multiple schemas | 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. 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 object | 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 | one of multiple schemas | 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. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
application | one of multiple schemas | ID of the Connect Application that created the schedule. |
billing_mode required | subscriptions_resource_billing_mode | |
canceled_at | integer | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. |
completed_at | integer | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
current_phase | one of multiple schemas | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
customer required | one of multiple schemas | ID of the customer who owns the subscription schedule. |
customer_account | string | ID of the account who owns the subscription schedule. |
default_settings required | subscription_schedules_resource_default_settings | |
end_behavior required | string | 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. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phases required | array of subscription_schedule_phase_configuration | Configuration for the subscription schedule's phases. |
released_at | integer | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. |
released_subscription | string | ID of the subscription once managed by the subscription schedule (if it is released). |
status required | string | 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). |
subscription | one of multiple schemas | ID of the subscription managed by the subscription schedule. |
test_clock | one of multiple schemas | ID of the test clock this subscription schedule belongs to. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/subscription_schedules/{schedule}
Retrieve a schedule
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.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
expand | query | array of string | Specifies which fields in the response should be expanded. |
schedule | path | string |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
application | one of multiple schemas | ID of the Connect Application that created the schedule. |
billing_mode required | subscriptions_resource_billing_mode | |
canceled_at | integer | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. |
completed_at | integer | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
current_phase | one of multiple schemas | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
customer required | one of multiple schemas | ID of the customer who owns the subscription schedule. |
customer_account | string | ID of the account who owns the subscription schedule. |
default_settings required | subscription_schedules_resource_default_settings | |
end_behavior required | string | 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. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phases required | array of subscription_schedule_phase_configuration | Configuration for the subscription schedule's phases. |
released_at | integer | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. |
released_subscription | string | ID of the subscription once managed by the subscription schedule (if it is released). |
status required | string | 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). |
subscription | one of multiple schemas | ID of the subscription managed by the subscription schedule. |
test_clock | one of multiple schemas | ID of the test clock this subscription schedule belongs to. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/subscription_schedules/{schedule}
Update a schedule
Updates an existing subscription schedule.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
schedule | path | string |
| Field | Type | Description |
|---|---|---|
default_settings | object | Object representing the subscription schedule's default settings. |
end_behavior | string | 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. |
expand | array of string | Specifies which fields in the response should be expanded. |
metadata | one of multiple schemas | 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. 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 object | 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 | string | 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`. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
application | one of multiple schemas | ID of the Connect Application that created the schedule. |
billing_mode required | subscriptions_resource_billing_mode | |
canceled_at | integer | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. |
completed_at | integer | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
current_phase | one of multiple schemas | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
customer required | one of multiple schemas | ID of the customer who owns the subscription schedule. |
customer_account | string | ID of the account who owns the subscription schedule. |
default_settings required | subscription_schedules_resource_default_settings | |
end_behavior required | string | 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. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phases required | array of subscription_schedule_phase_configuration | Configuration for the subscription schedule's phases. |
released_at | integer | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. |
released_subscription | string | ID of the subscription once managed by the subscription schedule (if it is released). |
status required | string | 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). |
subscription | one of multiple schemas | ID of the subscription managed by the subscription schedule. |
test_clock | one of multiple schemas | ID of the test clock this subscription schedule belongs to. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/subscription_schedules/{schedule}/cancel
Cancel a schedule
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_started or active.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
schedule | path | string |
| Field | Type | Description |
|---|---|---|
expand | array of string | Specifies which fields in the response should be expanded. |
invoice_now | boolean | 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 to `true`. |
prorate | boolean | If the subscription schedule is `active`, indicates if the cancellation should be prorated. Defaults to `true`. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
application | one of multiple schemas | ID of the Connect Application that created the schedule. |
billing_mode required | subscriptions_resource_billing_mode | |
canceled_at | integer | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. |
completed_at | integer | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
current_phase | one of multiple schemas | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
customer required | one of multiple schemas | ID of the customer who owns the subscription schedule. |
customer_account | string | ID of the account who owns the subscription schedule. |
default_settings required | subscription_schedules_resource_default_settings | |
end_behavior required | string | 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. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phases required | array of subscription_schedule_phase_configuration | Configuration for the subscription schedule's phases. |
released_at | integer | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. |
released_subscription | string | ID of the subscription once managed by the subscription schedule (if it is released). |
status required | string | 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). |
subscription | one of multiple schemas | ID of the subscription managed by the subscription schedule. |
test_clock | one of multiple schemas | ID of the test clock this subscription schedule belongs to. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/subscription_schedules/{schedule}/release
Release a schedule
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_started 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_subscription property.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
schedule | path | string |
| Field | Type | Description |
|---|---|---|
expand | array of string | Specifies which fields in the response should be expanded. |
preserve_cancel_date | boolean | Keep any cancellation on the subscription that the schedule has set |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
application | one of multiple schemas | ID of the Connect Application that created the schedule. |
billing_mode required | subscriptions_resource_billing_mode | |
canceled_at | integer | Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch. |
completed_at | integer | Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
current_phase | one of multiple schemas | Object representing the start and end dates for the current phase of the subscription schedule, if it is `active`. |
customer required | one of multiple schemas | ID of the customer who owns the subscription schedule. |
customer_account | string | ID of the account who owns the subscription schedule. |
default_settings required | subscription_schedules_resource_default_settings | |
end_behavior required | string | 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. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phases required | array of subscription_schedule_phase_configuration | Configuration for the subscription schedule's phases. |
released_at | integer | Time at which the subscription schedule was released. Measured in seconds since the Unix epoch. |
released_subscription | string | ID of the subscription once managed by the subscription schedule (if it is released). |
status required | string | 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). |
subscription | one of multiple schemas | ID of the subscription managed by the subscription schedule. |
test_clock | one of multiple schemas | ID of the test clock this subscription schedule belongs to. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |