API reference
Subscriptions
Subscriptions allow you to charge a customer on a recurring basis. Related guide: Creating subscriptions
https://api.knoxapi.com- POST/
v1/ subscriptions - GET/
v1/ subscriptions - GET/
v1/ subscriptions/ search - POST/
v1/ subscriptions/ {subscription_exposed_id} - GET/
v1/ subscriptions/ {subscription_exposed_id} - DELETE/
v1/ subscriptions/ {subscription_exposed_id} - DELETE/
v1/ subscriptions/ {subscription_exposed_id}/ discount - POST/
v1/ subscriptions/ {subscription}/ migrate - POST/
v1/ subscriptions/ {subscription}/ resume
Create a subscription
POST/v1/subscriptions
Creates a new subscription on an existing customer. Each customer can have up to 500 active or scheduled subscriptions. When you create a subscription with collection_method=charge_automatically, the first invoice is finalized as part of the request. The payment_behavior parameter determines the exact behavior of the initial payment. To start subscriptions where the first invoice always begins in a draft status, use subscription schedules instead. Schedules provide the flexibility to model more complex billing configurations that change over time.
Body parameters
add_invoice_itemsarray of objectsA list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
Show 8 child parameters
discountablebooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
metadataobjectperiodobjectShow 2 child parameters
endobjectRequiredChild parameters are listed in the OpenAPI document.
startobjectRequiredChild parameters are listed in the OpenAPI document.
pricestringprice_dataobjectShow 5 child parameters
currencystringRequiredproductstringRequiredtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
quantityintegertax_ratesarray of strings
application_fee_percentnumberA 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. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.
automatic_taxobjectAutomatic tax settings for this subscription.
Show 2 child parameters
enabledbooleanRequiredliabilityobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
backdate_start_dateintegerA past timestamp to backdate the subscription's start date to. If set, the first invoice will contain line items for the timespan between the start date and the current time. Can be combined with trials and the billing cycle anchor.
billing_cycle_anchorintegerA future timestamp in UTC format to anchor the subscription's billing cycle. The anchor is the reference point that aligns future billing cycle dates. It sets the day of week for
weekintervals, the day of month formonthandyearintervals, and the month of year foryearintervals.billing_cycle_anchor_configobjectMutually exclusive with billing_cycle_anchor and only valid with monthly and yearly price intervals. When provided, the billing_cycle_anchor is set to the next occurrence of the day_of_month at the hour, minute, and second UTC.
Show 5 child parameters
day_of_monthintegerRequiredhourintegerminuteintegermonthintegersecondinteger
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
billing_schedulesarray of objectsAn array of billing schedules, which allow you to bill customers in advance for multiple service periods. Requires flexible billing mode and API version 2026-05-27.dahlia or later. Learn more about prebilling.
Show 3 child parameters
bill_untilobjectRequiredShow 3 child parameters
typestringRequiredPossible valuesdurationtimestamp
durationobjectChild parameters are listed in the OpenAPI document.
timestampinteger
applies_toarray of objectsShow 2 child parameters
typestringRequiredPossible valuesprice
pricestring
keystring
billing_thresholdsobjectDefine thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
Show 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
cancel_atinteger | stringA timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using
proration_behavior. If set during a future period, this will always cause a proration for that period.Possible valuesmax_billed_untilmax_period_endmin_period_end
cancel_at_period_endbooleanIndicate whether this subscription should cancel at the end of the current period (
current_period_end). Defaults tofalse.collection_methodstringEither
charge_automatically, orsend_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the 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 asactive. Defaults tocharge_automatically.Possible valuescharge_automaticallysend_invoice
currencystringThree-letter ISO currency code, in lowercase. Must be a supported currency.
customerstringThe identifier of the customer to subscribe.
customer_accountstringThe identifier of the account representing the customer to subscribe.
days_until_dueintegerNumber of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where
collection_methodis set tosend_invoice.default_payment_methodstringID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over
default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.default_sourcestringID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If
default_payment_methodis also set,default_payment_methodwill take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.default_tax_ratesarray of stringsThe tax rates that will apply to any subscription item that does not have
tax_ratesset. Invoices created will have theirdefault_tax_ratespopulated from the subscription.descriptionstringThe subscription's 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.
discountsarray of objectsThe coupons to redeem into discounts for the subscription. If not specified or empty, inherits the discount from the subscription's customer.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
expandarray of stringsSpecifies which fields in the response should be expanded.
invoice_settingsobjectAll invoices will be billed using the specified settings.
Show 5 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsShow 2 child parameters
namestringRequiredvaluestringRequired
descriptionstringfooterstringissuerobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
itemsarray of objectsA list of up to 20 subscription items, each with an attached price.
Show 7 child parameters
billing_thresholdsobjectShow 1 child parameter
usage_gteintegerRequired
discountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
metadataobjectpricestringprice_dataobjectShow 6 child parameters
currencystringRequiredproductstringRequiredrecurringobjectRequiredChild parameters are listed in the OpenAPI document.
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
quantityintegertax_ratesarray of strings
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).on_behalf_ofstringThe account on behalf of which to charge, for each of the subscription's invoices.
payment_behaviorstringControls how Stripe handles the first invoice when payment is required and
collection_method=charge_automatically. Subscriptions withcollection_method=send_invoiceare automatically activated regardless of the first Invoice status.Possible valuesallow_incompletedefault_incompleteerror_if_incompletepending_if_incomplete
payment_settingsobjectPayment settings to pass to invoices created by the subscription.
Show 3 child parameters
payment_method_optionsobjectShow 11 child parameters
acss_debitobjectChild parameters are listed in the OpenAPI document.
bancontactobjectChild parameters are listed in the OpenAPI document.
billieobjectcardobjectChild parameters are listed in the OpenAPI document.
customer_balanceobjectChild parameters are listed in the OpenAPI document.
konbiniobjectpaytoobjectChild parameters are listed in the OpenAPI document.
pixobjectChild parameters are listed in the OpenAPI document.
sepa_debitobjectupiobjectChild parameters are listed in the OpenAPI document.
us_bank_accountobjectChild parameters are listed in the OpenAPI document.
payment_method_typesarray of stringssave_default_payment_methodstringPossible valuesoffon_subscription
pending_invoice_item_intervalobjectSpecifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.
Show 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
proration_behaviorstringDetermines how to handle prorations resulting from the
billing_cycle_anchor. If no value is passed, the default iscreate_prorations.Possible valuesalways_invoicecreate_prorationsnone
transfer_dataobjectIf specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges.
Show 2 child parameters
destinationstringRequiredamount_percentnumber
trial_endstring | integerUnix timestamp representing the end of the trial period the customer will get before being charged for the first time. If set, trial_end will override the default trial period of the plan the customer is being subscribed to. The special value
nowcan be provided to end the customer's trial immediately. Can be at most two years frombilling_cycle_anchor. See Using trial periods on subscriptions to learn more.Possible valuesnow
trial_from_planbooleanIndicates if a plan's
trial_period_daysshould be applied to the subscription. Settingtrial_endper subscription is preferred, and this defaults tofalse. Setting this flag totruetogether withtrial_endis not allowed. See Using trial periods on subscriptions to learn more.trial_period_daysintegerInteger representing the number of trial period days before the customer is charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. See Using trial periods on subscriptions to learn more.
trial_settingsobjectSettings related to subscription trials.
Show 1 child parameter
end_behaviorobjectRequiredShow 1 child parameter
missing_payment_methodstringRequiredPossible valuescancelcreate_invoicepause
Returns
The subscription object.
curl -X POST https://api.knoxapi.com/v1/subscriptions \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscription = await stripe.subscriptions.create();import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.create()require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.create(){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}List subscriptions
GET/v1/subscriptions
By default, returns a list of subscriptions that have not been canceled. In order to list canceled subscriptions, specify status=canceled.
Query parameters
automatic_taxobjectFilter subscriptions by their automatic tax settings.
Show 1 child parameter
enabledbooleanRequired
collection_methodstringThe collection method of the subscriptions to retrieve. Either
charge_automaticallyorsend_invoice.Possible valuescharge_automaticallysend_invoice
createdobject | integerOnly return subscriptions that were created during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
current_period_endobject | integerOnly return subscriptions whose minimum item current_period_end falls within the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
current_period_startobject | integerOnly return subscriptions whose maximum item current_period_start falls within the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
customerstringThe ID of the customer whose subscriptions you're retrieving.
customer_accountstringThe ID of the account representing the customer whose subscriptions you're retrieving.
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.
pricestringFilter for subscriptions that contain this recurring price ID.
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.statusstringThe status of the subscriptions to retrieve. Passing in a value of
canceledwill return all canceled subscriptions, including those belonging to deleted customers. Passendedto find subscriptions that are canceled and subscriptions that are expired due to incomplete payment. Passing in a value ofallwill return subscriptions of all statuses. If no value is supplied, all subscriptions that have not been canceled are returned.Possible valuesactiveallcanceledendedincompleteincomplete_expiredpast_duepausedtrialingunpaid
test_clockstringFilter for subscriptions that are associated with the specified test clock. The response will not include subscriptions with test clocks if this and the customer parameter is not set.
Returns
A list of subscription objects.
curl -G https://api.knoxapi.com/v1/subscriptions \
-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.subscriptions.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.subscriptions.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Subscription.list({
limit: 3,
}){
"object": "list",
"url": "/v1/subscriptions",
"has_more": false,
"data": [
{
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}
]
}Search subscriptions
GET/v1/subscriptions/search
Search for subscriptions you’ve previously created using Stripe’s Search Query Language. Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.
Query parameters
querystringRequiredThe search query string. See search query language and the list of supported query fields for subscriptions.
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.
pagestringA cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
Returns
A search result of subscription objects.
curl -G https://api.knoxapi.com/v1/subscriptions/search \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode "query=metadata['order_id']:'6735'"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.subscriptions.search({
query: "metadata['order_id']:'6735'",
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.subscriptions.search(params={
"query": "metadata['order_id']:'6735'",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Subscription.search({
query: "metadata['order_id']:'6735'",
}){
"object": "search_result",
"url": "/v1/subscriptions/search",
"has_more": false,
"data": [
{
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}
],
"next_page": null
}Update a subscription
POST/v1/subscriptions/{subscription_exposed_id}
Updates an existing subscription to match the specified parameters. When changing prices or quantities, we optionally prorate the price we charge next month to make up for any price changes. To preview how the proration is calculated, use the create preview endpoint. By default, we prorate subscription changes. For example, if a customer signs up on May 1 for a 100 price, they’ll be billed 100 immediately. If on May 15 they switch to a 200 price, then on June 1 they’ll be billed 250 (200 for a renewal of her subscription, plus a 50 prorating adjustment for half of the previous month’s 100 difference). Similarly, a downgrade generates a credit that is applied to the next invoice. We also prorate when you make quantity changes. You can also use scripts to prorate your billing. To learn more, see Prorations. Switching prices does not normally change the billing date or generate an immediate charge unless: The billing interval is changed (for example, from monthly to yearly). The subscription moves from free to paid. A trial starts or ends. In these cases, we apply a credit for the unused time on the previous price, immediately charge the customer using the new price, and reset the billing date. Learn about how Stripe immediately attempts payment for subscription changes. If you want to charge for an upgrade immediately, pass proration_behavior as always_invoice to create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment. If you pass create_prorations, the prorations are created but not automatically invoiced. If you want to bill the customer for the prorations before the subscription’s renewal date, you need to manually invoice the customer. If you don’t want to prorate, set the proration_behavior option to none. With this option, the customer is billed 100 on May 1 and 200 on June 1. Similarly, if you set proration_behavior to none when switching between different billing intervals (for example, from monthly to yearly), we don’t generate any credits for the old subscription’s unused time. We still reset the billing date and bill immediately for the new subscription. Updating the quantity on a subscription many times in an hour may result in rate limiting. If you need to bill for a frequently changing quantity, consider integrating usage-based billing instead.
Path parameters
subscription_exposed_idstringRequired
Body parameters
add_invoice_itemsarray of objectsA list of prices and quantities that will generate invoice items appended to the next invoice for this subscription. You may pass up to 20 items.
Show 8 child parameters
discountablebooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
metadataobjectperiodobjectShow 2 child parameters
endobjectRequiredChild parameters are listed in the OpenAPI document.
startobjectRequiredChild parameters are listed in the OpenAPI document.
pricestringprice_dataobjectShow 5 child parameters
currencystringRequiredproductstringRequiredtax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
quantityintegertax_ratesarray of strings
application_fee_percentnumberA 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. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.
automatic_taxobjectAutomatic tax settings for this subscription. We recommend you only include this parameter when the existing value is being changed.
Show 2 child parameters
enabledbooleanRequiredliabilityobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
billing_cycle_anchorstringEither
noworunchanged. Setting the value tonowresets the subscription's billing cycle anchor to the current time (in UTC). For more information, see the billing cycle documentation.Possible valuesnowunchanged
billing_schedulesarray of objectsAn array of billing schedules, which allow you to bill customers in advance for multiple service periods. Requires flexible billing mode and API version 2026-05-27.dahlia or later. Learn more about prebilling.
Show 3 child parameters
applies_toarray of objectsShow 2 child parameters
typestringRequiredPossible valuesprice
pricestring
bill_untilobjectShow 3 child parameters
typestringRequiredPossible valuesdurationtimestamp
durationobjectChild parameters are listed in the OpenAPI document.
timestampinteger
keystring
billing_thresholdsobjectDefine thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
Show 2 child parameters
amount_gteintegerreset_billing_cycle_anchorboolean
cancel_atinteger | stringA timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using
proration_behavior. If set during a future period, this will always cause a proration for that period.Possible valuesmax_billed_untilmax_period_endmin_period_end
cancel_at_period_endbooleanIndicate whether this subscription should cancel at the end of the current period (
current_period_end).cancellation_detailsobjectDetails about why this subscription was cancelled
Show 3 child parameters
commentstringfeedbackstringPossible valuescustomer_servicelow_qualitymissing_featuresotherswitched_servicetoo_complextoo_expensiveunused
feedback_optionstring
collection_methodstringEither
charge_automatically, orsend_invoice. When charging automatically, Stripe will attempt to pay this subscription at the end of the 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 asactive. Defaults tocharge_automatically.Possible valuescharge_automaticallysend_invoice
days_until_dueintegerNumber of days a customer has to pay invoices generated by this subscription. Valid only for subscriptions where
collection_methodis set tosend_invoice.default_payment_methodstringID of the default payment method for the subscription. It must belong to the customer associated with the subscription. This takes precedence over
default_source. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.default_sourcestringID of the default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If
default_payment_methodis also set,default_payment_methodwill take precedence. If neither are set, invoices will use the customer's invoice_settings.default_payment_method or default_source.default_tax_ratesarray of stringsThe tax rates that will apply to any subscription item that does not have
tax_ratesset. Invoices created will have theirdefault_tax_ratespopulated from the subscription. Pass an empty string to remove previously-defined tax rates.descriptionstringThe subscription's 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.
discountsarray of objectsThe coupons to redeem into discounts for the subscription. A populated array overwrites the existing discounts on the subscription. If not specified or empty array, it leaves the subscription's discounts unchanged. If empty string, it clears the subscription's discounts.
Show 3 child parameters
couponstringdiscountstringpromotion_codestring
expandarray of stringsSpecifies which fields in the response should be expanded.
invoice_settingsobjectAll invoices will be billed using the specified settings.
Show 5 child parameters
account_tax_idsarray of stringscustom_fieldsarray of objectsShow 2 child parameters
namestringRequiredvaluestringRequired
descriptionstringfooterstringissuerobjectShow 2 child parameters
typestringRequiredPossible valuesaccountself
accountstring
itemsarray of objectsA list of up to 20 subscription items, each with an attached price.
Show 10 child parameters
billing_thresholdsobjectShow 1 child parameter
usage_gteintegerRequired
clear_usagebooleandeletedbooleandiscountsarray of objectsShow 3 child parameters
couponstringdiscountstringpromotion_codestring
idstringmetadataobjectpricestringprice_dataobjectShow 6 child parameters
currencystringRequiredproductstringRequiredrecurringobjectRequiredChild parameters are listed in the OpenAPI document.
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
quantityintegertax_ratesarray of strings
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).on_behalf_ofstringThe account on behalf of which to charge, for each of the subscription's invoices.
pause_collectionobjectIf specified, payment collection for this subscription will be paused. Note that the subscription status will be unchanged and will not be updated to
paused. Learn more about pausing collection.Show 2 child parameters
behaviorstringRequiredPossible valueskeep_as_draftmark_uncollectiblevoid
resumes_atinteger
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
payment_settingsobjectPayment settings to pass to invoices created by the subscription.
Show 3 child parameters
payment_method_optionsobjectShow 11 child parameters
acss_debitobjectChild parameters are listed in the OpenAPI document.
bancontactobjectChild parameters are listed in the OpenAPI document.
billieobjectcardobjectChild parameters are listed in the OpenAPI document.
customer_balanceobjectChild parameters are listed in the OpenAPI document.
konbiniobjectpaytoobjectChild parameters are listed in the OpenAPI document.
pixobjectChild parameters are listed in the OpenAPI document.
sepa_debitobjectupiobjectChild parameters are listed in the OpenAPI document.
us_bank_accountobjectChild parameters are listed in the OpenAPI document.
payment_method_typesarray of stringssave_default_payment_methodstringPossible valuesoffon_subscription
pending_invoice_item_intervalobjectSpecifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval.
Show 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
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, prorations will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same prorations that were previewed with the create preview endpoint.
proration_datecan also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations.transfer_dataobjectIf specified, the funds from the subscription's invoices will be transferred to the destination and the ID of the resulting transfers will be found on the resulting charges. This will be unset if you POST an empty value.
Show 2 child parameters
destinationstringRequiredamount_percentnumber
trial_endstring | integerUnix timestamp representing the end of the trial period the customer will get before being charged for the first time. This will always overwrite any trials that might apply via a subscribed plan. If set,
trial_endwill override the default trial period of the plan the customer is being subscribed to. Thebilling_cycle_anchorwill be updated to thetrial_endvalue. The special valuenowcan be provided to end the customer's trial immediately. Can be at most two years frombilling_cycle_anchor.Possible valuesnow
trial_from_planbooleanIndicates if a plan's
trial_period_daysshould be applied to the subscription. Settingtrial_endper subscription is preferred, and this defaults tofalse. Setting this flag totruetogether withtrial_endis not allowed. See Using trial periods on subscriptions to learn more.trial_settingsobjectSettings related to subscription trials.
Show 1 child parameter
end_behaviorobjectRequiredShow 1 child parameter
missing_payment_methodstringRequiredPossible valuescancelcreate_invoicepause
Returns
The subscription object.
curl https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
-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 subscription = await stripe.subscriptions.update('subscription_exposed_id_123', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.update("subscription_exposed_id_123", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.update('subscription_exposed_id_123', {
metadata: {
order_id: '6735',
},
}){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}Retrieve a subscription
GET/v1/subscriptions/{subscription_exposed_id}
Retrieves the subscription with the given ID.
Path parameters
subscription_exposed_idstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The subscription object.
curl https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscription = await stripe.subscriptions.retrieve('subscription_exposed_id_123');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.retrieve("subscription_exposed_id_123")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.retrieve('subscription_exposed_id_123'){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}Cancel a subscription
DELETE/v1/subscriptions/{subscription_exposed_id}
Cancels a customer’s subscription immediately. The customer won’t be charged again for the subscription. After it’s canceled, the subscription is largely immutable. You can still update its metadata and cancellation_details. Any pending invoice items that you’ve created are still charged at the end of the period, unless manually deleted. If you’ve set the subscription to cancel at the end of the period, any pending prorations are also left in place and collected at the end of the period. But if the subscription is set to cancel immediately, pending prorations are removed if invoice_now and prorate are both set to false. By default, upon subscription cancellation, Stripe stops automatic collection of all finalized invoices for the customer. This is intended to prevent unexpected payment attempts after the customer has canceled a subscription. However, you can resume automatic collection of the invoices manually after subscription cancellation to have us proceed. Or, you could check for unpaid invoices before allowing the customer to cancel the subscription at all.
Path parameters
subscription_exposed_idstringRequired
Body parameters
cancellation_detailsobjectDetails about why this subscription was cancelled
Show 3 child parameters
commentstringfeedbackstringPossible valuescustomer_servicelow_qualitymissing_featuresotherswitched_servicetoo_complextoo_expensiveunused
feedback_optionstring
expandarray of stringsSpecifies which fields in the response should be expanded.
invoice_nowbooleanWill generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items. Defaults to
false.proratebooleanWill generate a proration invoice item that credits remaining unused time until the subscription period end. Defaults to
false.
Returns
The subscription object.
curl -X DELETE https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123 \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscription = await stripe.subscriptions.cancel('subscription_exposed_id_123');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.cancel("subscription_exposed_id_123")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.cancel('subscription_exposed_id_123'){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}Delete a subscription discount
DELETE/v1/subscriptions/{subscription_exposed_id}/discount
Removes the currently applied discount on a subscription.
Path parameters
subscription_exposed_idstringRequired
Returns
The deleted_discount object.
curl -X DELETE https://api.knoxapi.com/v1/subscriptions/subscription_exposed_id_123/discount \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('DELETE', '/v1/subscriptions/subscription_exposed_id_123/discount');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("delete", "/v1/subscriptions/subscription_exposed_id_123/discount")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:delete, '/v1/subscriptions/subscription_exposed_id_123/discount'){
"deleted": true,
"id": "",
"object": "discount",
"start": 1234567890,
"checkout_session": null,
"customer": null,
"invoice": null,
"invoice_item": null,
"promotion_code": null,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
}Migrate a subscription
POST/v1/subscriptions/{subscription}/migrate
Upgrade the billing_mode of an existing subscription.
Path parameters
subscriptionstringRequired
Body parameters
billing_modeobjectRequiredControls how prorations and invoices for subscriptions are calculated and orchestrated.
Show 2 child parameters
typestringRequiredPossible valuesflexible
flexibleobjectShow 1 child parameter
proration_discountsstringPossible valuesincludeditemized
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The subscription object.
curl https://api.knoxapi.com/v1/subscriptions/sub_1Pgc6rB7WZ01zgkWNy0Cn5nw/migrate \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "billing_mode[type]=classic"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscription = await stripe.subscriptions.migrate('sub_1Pgc6rB7WZ01zgkWNy0Cn5nw', {
billing_mode: {
type: 'classic',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.migrate("sub_1Pgc6rB7WZ01zgkWNy0Cn5nw", params={
"billing_mode": {
"type": "classic",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.migrate('sub_1Pgc6rB7WZ01zgkWNy0Cn5nw', {
billing_mode: {
type: 'classic',
},
}){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}Resume a subscription
POST/v1/subscriptions/{subscription}/resume
Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. Resume is only available for subscriptions that use charge_automatically collection. If Stripe doesn’t generate a resumption invoice, the subscription becomes active immediately. When a resumption invoice is generated, Stripe finalizes it immediately. If the invoice is paid or marked uncollectible, the subscription becomes active. If the invoice is manually voided, the subscription stays paused. If there is no payment attempt within 23 hours, Stripe voids the invoice and the subscription stays paused. Learn more about resuming subscriptions.
Path parameters
subscriptionstringRequired
Body parameters
billing_cycle_anchorstringThe billing cycle anchor that applies when the subscription is resumed. Either
noworunchanged. The default isnow. For more information, see the billing cycle documentation.Possible valuesnowunchanged
expandarray of stringsSpecifies which fields in the response should be expanded.
proration_behaviorstringDetermines how to handle prorations resulting from the
billing_cycle_anchorbeingunchanged. When thebilling_cycle_anchoris set tonow(default value), no prorations are generated. If no value is passed, the default iscreate_prorations.Possible valuesalways_invoicecreate_prorationsnone
proration_dateintegerIf set, prorations will be calculated as though the subscription was resumed at the given time. This can be used to apply exactly the same prorations that were previewed with the create preview endpoint.
Returns
The subscription object.
curl -X POST https://api.knoxapi.com/v1/subscriptions/sub_1Pgc6rB7WZ01zgkWNy0Cn5nw/resume \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const subscription = await stripe.subscriptions.resume('sub_1Pgc6rB7WZ01zgkWNy0Cn5nw');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
subscription = client.v1.subscriptions.resume("sub_1Pgc6rB7WZ01zgkWNy0Cn5nw")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
subscription = Stripe::Subscription.resume('sub_1Pgc6rB7WZ01zgkWNy0Cn5nw'){
"application": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": {
"type": "account"
},
"disabled_reason": null
},
"billing_cycle_anchor": 1234567890,
"billing_cycle_anchor_config": {
"day_of_month": 1361669285,
"hour": null,
"minute": null,
"month": null,
"second": null
},
"cancel_at": 1234567890,
"canceled_at": 1234567890,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null,
"feedback_option": null
},
"collection_method": "charge_automatically",
"created": 1234567890,
"currency": "usd",
"customer": "cus_QXg1o8vcGmoR32",
"days_until_due": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"ended_at": 1234567890,
"id": "sub_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"invoice_settings": {
"account_tax_ids": null,
"issuer": {
"type": "self"
},
"custom_fields": null,
"description": null,
"footer": null
},
"items": {
"data": [
{
"created": 1721954054,
"discounts": [],
"id": "si_QXhVnC2h0Jczwc",
"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_1Pgc6rB7WZ01zgkWNy0Cn5nw",
"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
}
}
],
"has_more": false,
"object": "list",
"url": "/v1/subscription_items?subscription=sub_1Pgc6rB7WZ01zgkWNy0Cn5nw"
},
"latest_invoice": null,
"livemode": false,
"metadata": {},
"next_pending_invoice_item_invoice": 1234567890,
"object": "subscription",
"on_behalf_of": null,
"pause_collection": {
"behavior": "mark_uncollectible",
"resumes_at": null
},
"payment_settings": {
"payment_method_options": {
"acss_debit": {},
"bancontact": {
"preferred_language": "fr"
},
"card": {
"network": null,
"request_three_d_secure": null
},
"customer_balance": {
"funding_type": null
},
"konbini": {},
"sepa_debit": {},
"us_bank_account": {},
"payto": {},
"pix": {},
"upi": {},
"billie": {}
},
"payment_method_types": null,
"save_default_payment_method": null
},
"pending_invoice_item_interval": {
"interval": "month",
"interval_count": 797691627
},
"pending_setup_intent": null,
"pending_update": {
"billing_cycle_anchor": null,
"discount": {
"checkout_session": null,
"customer": null,
"end": null,
"id": "obj_123",
"invoice": null,
"invoice_item": null,
"object": "discount",
"promotion_code": null,
"start": 109757538,
"subscription": null,
"subscription_item": null,
"source": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
},
"discounts": [],
"expires_at": 833811170,
"subscription_items": null,
"trial_end": null,
"trial_from_plan": null,
"metadata": null,
"cancel_at_period_end": null
},
"schedule": null,
"start_date": 1234567890,
"status": "active",
"test_clock": null,
"transfer_data": {
"amount_percent": null,
"destination": {
"id": "obj_123",
"object": "account"
}
},
"trial_end": 1234567890,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": 1234567890,
"cancel_at_period_end": true,
"billing_thresholds": {
"amount_gte": null,
"reset_billing_cycle_anchor": null
},
"billing_mode": {
"type": "classic",
"flexible": {}
},
"customer_account": null,
"managed_payments": {
"enabled": true
},
"billing_schedules": [
{
"applies_to": null,
"bill_until": {
"computed_timestamp": 2082605468,
"duration": {
"interval": "month",
"interval_count": null
},
"timestamp": null,
"type": "duration"
},
"key": "key"
}
]
}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.