API reference
Subscription Schedules
A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes. Related guide: Subscription schedules
Create a schedule
POST/v1/subscription_schedules
Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.
Body parameters
billing_modeobjectControls how prorations and invoices for subscriptions are calculated and orchestrated.
Show 2 child parameters
typestringRequiredPossible valuesclassicflexible
flexibleobjectShow 1 child parameter
proration_discountsstringPossible valuesincludeditemized
customerstringThe identifier of the customer to create the subscription schedule for.
customer_accountstringThe identifier of the account to create the subscription schedule for.
default_settingsobjectObject representing the subscription schedule's default settings.
Show 10 child parameters
application_fee_percentnumberautomatic_taxobjectShow 2 child parameters
enabledbooleanRequiredliabilityobjectChild parameters are listed in the OpenAPI document.
billing_cycle_anchorstringPossible valuesautomaticphase_start
billing_thresholdsobjectShow 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
collection_methodstringPossible valuescharge_automaticallysend_invoice
default_payment_methodstringdescriptionstringinvoice_settingsobjectShow 6 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsChild parameters are listed in the OpenAPI document.
days_until_dueintegerdescriptionstringfooterstringissuerobjectChild parameters are listed in the OpenAPI document.
on_behalf_ofstringtransfer_dataobjectShow 2 child parameters
destinationstringRequiredamount_percentnumber
end_behaviorstringBehavior of the subscription schedule and underlying subscription when it ends. Possible values are
releaseorcancelwith the default beingrelease.releasewill end the subscription schedule and keep the underlying subscription running.cancelwill end the subscription schedule and cancel the underlying subscription.Possible valuescancelnonereleaserenew
expandarray of stringsSpecifies which fields in the response should be expanded.
from_subscriptionstringMigrate 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.
metadataobjectSet 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.phasesarray of objectsList 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_dateof one phase will always equal thestart_dateof the next phase.Show 21 child parameters
itemsarray of objectsRequiredShow 7 child parameters
billing_thresholdsobjectChild parameters are listed in the OpenAPI document.
discountsarray of objectsChild parameters are listed in the OpenAPI document.
metadataobjectpricestringprice_dataobjectChild parameters are listed in the OpenAPI document.
quantityintegertax_ratesarray of strings
add_invoice_itemsarray of objectsShow 8 child parameters
discountablebooleandiscountsarray of objectsChild parameters are listed in the OpenAPI document.
metadataobjectperiodobjectChild parameters are listed in the OpenAPI document.
pricestringprice_dataobjectChild parameters are listed in the OpenAPI document.
quantityintegertax_ratesarray of strings
application_fee_percentnumberautomatic_taxobjectShow 2 child parameters
enabledbooleanRequiredliabilityobjectChild parameters are listed in the OpenAPI document.
billing_cycle_anchorstringPossible valuesautomaticphase_start
billing_thresholdsobjectShow 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
collection_methodstringPossible valuescharge_automaticallysend_invoice
currencystringdefault_payment_methodstringdefault_tax_ratesarray of stringsdescriptionstringdiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
durationobjectShow 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
end_dateintegerinvoice_settingsobjectShow 6 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsChild parameters are listed in the OpenAPI document.
days_until_dueintegerdescriptionstringfooterstringissuerobjectChild parameters are listed in the OpenAPI document.
metadataobjecton_behalf_ofstringproration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
transfer_dataobjectShow 2 child parameters
destinationstringRequiredamount_percentnumber
trialbooleantrial_endinteger
start_dateinteger | stringWhen the subscription schedule starts. We recommend using
nowso 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.Possible valuesnow
Returns
The subscription_schedule object.
curl -X POST https://api.knoxapi.com/v1/subscription_schedules \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionSchedule = await stripe.subscriptionSchedules.create();import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_schedule = client.v1.subscription_schedules.create()require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_schedule = Stripe::SubscriptionSchedule.create(){
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}List all schedules
GET/v1/subscription_schedules
Retrieves the list of your subscription schedules.
Query parameters
canceled_atobject | integerOnly return subscription schedules that were created canceled the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
completed_atobject | integerOnly return subscription schedules that completed during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
createdobject | integerOnly return subscription schedules that were created during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
customerstringOnly 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_accountstringOnly return subscription schedules for the given account.
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
released_atobject | integerOnly return subscription schedules that were released during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
scheduledbooleanOnly return subscription schedules that have not started yet.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of subscription_schedule objects.
curl -G https://api.knoxapi.com/v1/subscription_schedules \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.subscriptionSchedules.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.subscription_schedules.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::SubscriptionSchedule.list({
limit: 3,
}){
"object": "list",
"url": "/v1/subscription_schedules",
"has_more": false,
"data": [
{
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}
]
}Update a schedule
POST/v1/subscription_schedules/{schedule}
Updates an existing subscription schedule.
Path parameters
schedulestringRequired
Body parameters
default_settingsobjectObject representing the subscription schedule's default settings.
Show 10 child parameters
application_fee_percentnumberautomatic_taxobjectShow 2 child parameters
enabledbooleanRequiredliabilityobjectChild parameters are listed in the OpenAPI document.
billing_cycle_anchorstringPossible valuesautomaticphase_start
billing_thresholdsobjectShow 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
collection_methodstringPossible valuescharge_automaticallysend_invoice
default_payment_methodstringdescriptionstringinvoice_settingsobjectShow 6 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsChild parameters are listed in the OpenAPI document.
days_until_dueintegerdescriptionstringfooterstringissuerobjectChild parameters are listed in the OpenAPI document.
on_behalf_ofstringtransfer_dataobjectShow 2 child parameters
destinationstringRequiredamount_percentnumber
end_behaviorstringBehavior of the subscription schedule and underlying subscription when it ends. Possible values are
releaseorcancelwith the default beingrelease.releasewill end the subscription schedule and keep the underlying subscription running.cancelwill end the subscription schedule and cancel the underlying subscription.Possible valuescancelnonereleaserenew
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet 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.phasesarray of objectsList 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_dateof one phase will always equal thestart_dateof the next phase. Note that past phases can be omitted.Show 21 child parameters
itemsarray of objectsRequiredShow 7 child parameters
billing_thresholdsobjectChild parameters are listed in the OpenAPI document.
discountsarray of objectsChild parameters are listed in the OpenAPI document.
metadataobjectpricestringprice_dataobjectChild parameters are listed in the OpenAPI document.
quantityintegertax_ratesarray of strings
add_invoice_itemsarray of objectsShow 8 child parameters
discountablebooleandiscountsarray of objectsChild parameters are listed in the OpenAPI document.
metadataobjectperiodobjectChild parameters are listed in the OpenAPI document.
pricestringprice_dataobjectChild parameters are listed in the OpenAPI document.
quantityintegertax_ratesarray of strings
application_fee_percentnumberautomatic_taxobjectShow 2 child parameters
enabledbooleanRequiredliabilityobjectChild parameters are listed in the OpenAPI document.
billing_cycle_anchorstringPossible valuesautomaticphase_start
billing_thresholdsobjectShow 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
collection_methodstringPossible valuescharge_automaticallysend_invoice
default_payment_methodstringdefault_tax_ratesarray of stringsdescriptionstringdiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
durationobjectShow 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
end_dateinteger | stringPossible valuesnow
invoice_settingsobjectShow 6 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsChild parameters are listed in the OpenAPI document.
days_until_dueintegerdescriptionstringfooterstringissuerobjectChild parameters are listed in the OpenAPI document.
metadataobjecton_behalf_ofstringproration_behaviorstringPossible valuesalways_invoicecreate_prorationsnone
start_dateinteger | stringPossible valuesnow
transfer_dataobjectShow 2 child parameters
destinationstringRequiredamount_percentnumber
trialbooleantrial_endinteger | stringPossible valuesnow
proration_behaviorstringIf 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 valuesalways_invoicecreate_prorationsnone
Returns
The subscription_schedule object.
curl https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionSchedule = await stripe.subscriptionSchedules.update('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_schedule = client.v1.subscription_schedules.update("sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_schedule = Stripe::SubscriptionSchedule.update('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC', {
metadata: {
order_id: '6735',
},
}){
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}Retrieve a schedule
GET/v1/subscription_schedules/{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.
Path parameters
schedulestringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The subscription_schedule object.
curl https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionSchedule = await stripe.subscriptionSchedules.retrieve('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_schedule = client.v1.subscription_schedules.retrieve("sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_schedule = Stripe::SubscriptionSchedule.retrieve('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC'){
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}Cancel a schedule
POST/v1/subscription_schedules/{schedule}/cancel
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.
Path parameters
schedulestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
invoice_nowbooleanIf 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.proratebooleanIf the subscription schedule is
active, indicates if the cancellation should be prorated. Defaults totrue.
Returns
The subscription_schedule object.
curl -X POST https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC/cancel \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionSchedule = await stripe.subscriptionSchedules.cancel('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_schedule = client.v1.subscription_schedules.cancel("sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_schedule = Stripe::SubscriptionSchedule.cancel('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC'){
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}Release a schedule
POST/v1/subscription_schedules/{schedule}/release
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.
Path parameters
schedulestringRequired
Body parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
preserve_cancel_datebooleanKeep any cancellation on the subscription that the schedule has set
Returns
The subscription_schedule object.
curl -X POST https://api.knoxapi.com/v1/subscription_schedules/sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC/release \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionSchedule = await stripe.subscriptionSchedules.release('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_schedule = client.v1.subscription_schedules.release("sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_schedule = Stripe::SubscriptionSchedule.release('sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC'){
"application": null,
"canceled_at": 1234567890,
"completed_at": 1234567890,
"created": 1234567890,
"current_phase": {
"end_date": 1725067410,
"start_date": 1573629589
},
"customer": "cus_QXg1o8vcGmoR32",
"default_settings": {
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": "automatic",
"collection_method": "charge_automatically",
"default_payment_method": null,
"description": null,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"on_behalf_of": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
},
"end_behavior": "release",
"id": "sub_sched_1Pgc7AB7WZ01zgkWaeHcsbnC",
"livemode": false,
"metadata": {},
"object": "subscription_schedule",
"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": [],
"end_date": 1754008472,
"invoice_settings": {
"account_tax_ids": null,
"days_until_due": null,
"issuer": {
"type": "account"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": [
{
"discounts": [],
"metadata": {},
"price": "price_1PgafmB7WZ01zgkW6dKueIc5",
"quantity": 1,
"tax_rates": [],
"plan": {
"active": true,
"amount": null,
"amount_decimal": null,
"billing_scheme": "tiered",
"created": 1028554472,
"currency": "currency",
"id": "obj_123",
"interval": "month",
"interval_count": 797691627,
"livemode": true,
"metadata": null,
"meter": null,
"nickname": null,
"object": "plan",
"product": null,
"tiers_mode": null,
"transform_usage": {
"divide_by": 1592560163,
"round": "down"
},
"trial_period_days": null,
"usage_type": "licensed"
},
"billing_thresholds": {
"usage_gte": null
}
}
],
"metadata": {},
"on_behalf_of": null,
"proration_behavior": "create_prorations",
"start_date": 1722558872,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": null,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
}
}
],
"released_at": 1234567890,
"released_subscription": null,
"status": "not_started",
"subscription": null,
"test_clock": null,
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.