API reference
Subscription Items
Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.
https://api.knoxapi.comCreate a subscription item
POST/v1/subscription_items
Adds a new item to an existing subscription. No existing items will be changed or replaced.
Body parameters
subscriptionstringRequiredThe identifier of the subscription to modify.
billing_thresholdsobjectDefine thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
Show 1 child parameter
usage_gteintegerRequired
discountsarray of objectsThe coupons to redeem into discounts for the subscription item.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
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.payment_behaviorstringControls how Stripe handles payment when a subscription update requires payment and
collection_method=charge_automatically.Possible valuesallow_incompletedefault_incompleteerror_if_incompletepending_if_incomplete
pricestringThe ID of the price object.
price_dataobjectData used to generate a new Price object inline.
Show 6 child parameters
currencystringRequiredproductstringRequiredrecurringobjectRequiredShow 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
proration_behaviorstringDetermines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting
billing_cycle_anchor=now, or starting a trial), or if an item'squantitychanges. The default value iscreate_prorations.Possible valuesalways_invoicecreate_prorationsnone
proration_dateintegerIf set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.
quantityintegerThe quantity you'd like to apply to the subscription item you're creating.
tax_ratesarray of stringsA list of Tax Rate ids. These Tax Rates will override the
default_tax_rateson the Subscription. When updating, pass an empty string to remove previously-defined tax rates.
Returns
The subscription_item object.
curl https://api.knoxapi.com/v1/subscription_items \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d subscription=sub_1Pgc6xB7WZ01zgkWJMvZp5jaconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionItem = await stripe.subscriptionItems.create({
subscription: 'sub_1Pgc6xB7WZ01zgkWJMvZp5ja',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_item = client.v1.subscription_items.create(params={
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_item = Stripe::SubscriptionItem.create({
subscription: 'sub_1Pgc6xB7WZ01zgkWJMvZp5ja',
}){
"created": 1721954060,
"discounts": [],
"id": "si_QXhVBoJ7NQdNXh",
"metadata": {},
"object": "subscription_item",
"price": {
"active": true,
"billing_scheme": "per_unit",
"created": 1721948530,
"currency": "usd",
"custom_unit_amount": {
"maximum": null,
"minimum": null,
"preset": null
},
"id": "price_1PgafmB7WZ01zgkW6dKueIc5",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"object": "price",
"product": "prod_QXg1hqf4jFNsqG",
"recurring": {
"interval": "month",
"interval_count": 1,
"meter": null,
"usage_type": "licensed",
"trial_period_days": null
},
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": {
"divide_by": 1592560163,
"round": "down"
},
"type": "recurring",
"unit_amount": 2000,
"unit_amount_decimal": "2000"
},
"quantity": 1,
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
"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"
},
"current_period_end": 976287773,
"current_period_start": 1896570518,
"billing_thresholds": {
"usage_gte": null
}
}List all subscription items
GET/v1/subscription_items
Returns a list of your subscription items for a given subscription.
Query parameters
subscriptionstringRequiredThe ID of the subscription whose items will be retrieved.
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.
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_item objects.
curl -G https://api.knoxapi.com/v1/subscription_items \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode subscription=sub_1Pgc6xB7WZ01zgkWJMvZp5jaconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.subscriptionItems.list({
subscription: 'sub_1Pgc6xB7WZ01zgkWJMvZp5ja',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.subscription_items.list(params={
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::SubscriptionItem.list({
subscription: 'sub_1Pgc6xB7WZ01zgkWJMvZp5ja',
}){
"object": "list",
"url": "/v1/subscription_items",
"has_more": false,
"data": [
{
"created": 1721954060,
"discounts": [],
"id": "si_QXhVBoJ7NQdNXh",
"metadata": {},
"object": "subscription_item",
"price": {
"active": true,
"billing_scheme": "per_unit",
"created": 1721948530,
"currency": "usd",
"custom_unit_amount": {
"maximum": null,
"minimum": null,
"preset": null
},
"id": "price_1PgafmB7WZ01zgkW6dKueIc5",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"object": "price",
"product": "prod_QXg1hqf4jFNsqG",
"recurring": {
"interval": "month",
"interval_count": 1,
"meter": null,
"usage_type": "licensed",
"trial_period_days": null
},
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": {
"divide_by": 1592560163,
"round": "down"
},
"type": "recurring",
"unit_amount": 2000,
"unit_amount_decimal": "2000"
},
"quantity": 1,
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
"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"
},
"current_period_end": 976287773,
"current_period_start": 1896570518,
"billing_thresholds": {
"usage_gte": null
}
}
]
}Update a subscription item
POST/v1/subscription_items/{item}
Updates the plan or quantity of an item on a current subscription.
Path parameters
itemstringRequired
Body parameters
billing_thresholdsobjectDefine thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
Show 1 child parameter
usage_gteintegerRequired
discountsarray of objectsThe coupons to redeem into discounts for the subscription item.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
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.off_sessionbooleanIndicates if a customer is on or off-session while an invoice payment is attempted. Defaults to
false(on-session).payment_behaviorstringControls how Stripe handles payment when a subscription update requires payment and
collection_method=charge_automatically.Possible valuesallow_incompletedefault_incompleteerror_if_incompletepending_if_incomplete
pricestringThe ID of the price object. One of
priceorprice_datais required. When changing a subscription item's price,quantityis set to 1 unless aquantityparameter is provided.price_dataobjectData used to generate a new Price object inline. One of
priceorprice_datais required.Show 6 child parameters
currencystringRequiredproductstringRequiredrecurringobjectRequiredShow 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
proration_behaviorstringDetermines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting
billing_cycle_anchor=now, or starting a trial), or if an item'squantitychanges. The default value iscreate_prorations.Possible valuesalways_invoicecreate_prorationsnone
proration_dateintegerIf set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.
quantityintegerThe quantity you'd like to apply to the subscription item you're creating.
tax_ratesarray of stringsA list of Tax Rate ids. These Tax Rates will override the
default_tax_rateson the Subscription. When updating, pass an empty string to remove previously-defined tax rates.
Returns
The subscription_item object.
curl https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
-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 subscriptionItem = await stripe.subscriptionItems.update('li_1Pgc73B7WZ01zgkWx8kcmZPK', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_item = client.v1.subscription_items.update("li_1Pgc73B7WZ01zgkWx8kcmZPK", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_item = Stripe::SubscriptionItem.update('li_1Pgc73B7WZ01zgkWx8kcmZPK', {
metadata: {
order_id: '6735',
},
}){
"created": 1721954060,
"discounts": [],
"id": "si_QXhVBoJ7NQdNXh",
"metadata": {},
"object": "subscription_item",
"price": {
"active": true,
"billing_scheme": "per_unit",
"created": 1721948530,
"currency": "usd",
"custom_unit_amount": {
"maximum": null,
"minimum": null,
"preset": null
},
"id": "price_1PgafmB7WZ01zgkW6dKueIc5",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"object": "price",
"product": "prod_QXg1hqf4jFNsqG",
"recurring": {
"interval": "month",
"interval_count": 1,
"meter": null,
"usage_type": "licensed",
"trial_period_days": null
},
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": {
"divide_by": 1592560163,
"round": "down"
},
"type": "recurring",
"unit_amount": 2000,
"unit_amount_decimal": "2000"
},
"quantity": 1,
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
"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"
},
"current_period_end": 976287773,
"current_period_start": 1896570518,
"billing_thresholds": {
"usage_gte": null
}
}Retrieve a subscription item
GET/v1/subscription_items/{item}
Retrieves the subscription item with the given ID.
Path parameters
itemstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The subscription_item object.
curl https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscriptionItem = await stripe.subscriptionItems.retrieve('li_1Pgc73B7WZ01zgkWx8kcmZPK');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription_item = client.v1.subscription_items.retrieve("li_1Pgc73B7WZ01zgkWx8kcmZPK")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription_item = Stripe::SubscriptionItem.retrieve('li_1Pgc73B7WZ01zgkWx8kcmZPK'){
"created": 1721954060,
"discounts": [],
"id": "si_QXhVBoJ7NQdNXh",
"metadata": {},
"object": "subscription_item",
"price": {
"active": true,
"billing_scheme": "per_unit",
"created": 1721948530,
"currency": "usd",
"custom_unit_amount": {
"maximum": null,
"minimum": null,
"preset": null
},
"id": "price_1PgafmB7WZ01zgkW6dKueIc5",
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"object": "price",
"product": "prod_QXg1hqf4jFNsqG",
"recurring": {
"interval": "month",
"interval_count": 1,
"meter": null,
"usage_type": "licensed",
"trial_period_days": null
},
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": {
"divide_by": 1592560163,
"round": "down"
},
"type": "recurring",
"unit_amount": 2000,
"unit_amount_decimal": "2000"
},
"quantity": 1,
"subscription": "sub_1Pgc6xB7WZ01zgkWJMvZp5ja",
"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"
},
"current_period_end": 976287773,
"current_period_start": 1896570518,
"billing_thresholds": {
"usage_gte": null
}
}Delete a subscription item
DELETE/v1/subscription_items/{item}
Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.
Path parameters
itemstringRequired
Body parameters
clear_usagebooleanDelete all usage for the given subscription item. Allowed only when the current plan's
usage_typeismetered.payment_behaviorstringControls how Stripe handles payment when a subscription update requires payment and
collection_method=charge_automatically.Possible valuesallow_incompletedefault_incompleteerror_if_incompletepending_if_incomplete
proration_behaviorstringDetermines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting
billing_cycle_anchor=now, or starting a trial), or if an item'squantitychanges. The default value iscreate_prorations.Possible valuesalways_invoicecreate_prorationsnone
proration_dateintegerIf set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply the same proration that was previewed with the upcoming invoice endpoint.
Returns
The deleted_subscription_item object.
curl -X DELETE https://api.knoxapi.com/v1/subscription_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const deletedSubscriptionItem = await stripe.subscriptionItems.del('li_1Pgc73B7WZ01zgkWx8kcmZPK');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
deleted_subscription_item = client.v1.subscription_items.delete("li_1Pgc73B7WZ01zgkWx8kcmZPK")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
deleted_subscription_item = Stripe::SubscriptionItem.delete('li_1Pgc73B7WZ01zgkWx8kcmZPK'){
"deleted": true,
"id": "si_QXhVBoJ7NQdNXh",
"object": "subscription_item"
}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.