API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

GET /v1/subscription_items

List all subscription items

Returns a list of your subscription items for a given subscription.

Request parameters

Parameter	Location	Type	Description
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`subscription`	query	string	The ID of the subscription whose items will be retrieved.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of subscription_item
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/subscription_items

Create a subscription item

Adds a new item to an existing subscription. No existing items will be changed or replaced.

Request parameters

Field	Type	Description
`billing_thresholds`	one of multiple schemas	Define 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.
`discounts`	one of multiple schemas	The coupons to redeem into discounts for the subscription item.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. 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_behavior`	string	Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
`price`	string	The ID of the price object.
`price_data`	object	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline.
`proration_behavior`	string	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
`proration_date`	integer	If 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](/api/invoices/create_preview) endpoint.
`quantity`	integer	The quantity you'd like to apply to the subscription item you're creating.
`subscription` required	string	The identifier of the subscription to modify.
`tax_rates`	one of multiple schemas	A list of [Tax Rate](https://docs.stripe.com/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

Responses

HTTP 200: Successful response.

Field	Type	Description
`billed_until`	integer	The time period the subscription item has been billed for.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`current_period_end` required	integer	The end time of this subscription item's current billing period.
`current_period_start` required	integer	The start time of this subscription item's current billing period.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`id` required	string	Unique identifier for the object.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`price` required	price
`quantity`	integer	The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
`subscription` required	string	The `subscription` this `subscription_item` belongs to.
`tax_rates`	array of tax_rate	The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

DELETE /v1/subscription_items/{item}

Delete a subscription item

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Request parameters

Parameter	Location	Type	Description
`item`	path	string

Field	Type	Description
`clear_usage`	boolean	Delete all usage for the given subscription item. Allowed only when the current plan's `usage_type` is `metered`.
`payment_behavior`	string	Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
`proration_behavior`	string	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
`proration_date`	integer	If 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](/api/invoices/create_preview) endpoint.

Responses

HTTP 200: Successful response.

Field	Type	Description
`deleted` required	boolean	Always true for a deleted object
`id` required	string	Unique identifier for the object.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/subscription_items/{item}

Retrieve a subscription item

Retrieves the subscription item with the given ID.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`item`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`billed_until`	integer	The time period the subscription item has been billed for.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`current_period_end` required	integer	The end time of this subscription item's current billing period.
`current_period_start` required	integer	The start time of this subscription item's current billing period.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`id` required	string	Unique identifier for the object.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`price` required	price
`quantity`	integer	The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
`subscription` required	string	The `subscription` this `subscription_item` belongs to.
`tax_rates`	array of tax_rate	The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/subscription_items/{item}

Update a subscription item

Updates the plan or quantity of an item on a current subscription.

Request parameters

Parameter	Location	Type	Description
`item`	path	string

Field	Type	Description
`billing_thresholds`	one of multiple schemas	Define 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.
`discounts`	one of multiple schemas	The coupons to redeem into discounts for the subscription item.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	one of multiple schemas	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
`off_session`	boolean	Indicates if a customer is on or off-session while an invoice payment is attempted. Defaults to `false` (on-session).
`payment_behavior`	string	Controls how Stripe handles payment when a subscription update requires payment and `collection_method=charge_automatically`.
`price`	string	The ID of the price object. One of `price` or `price_data` is required. When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided.
`price_data`	object	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object inline. One of `price` or `price_data` is required.
`proration_behavior`	string	Determines how to handle [prorations](https://docs.stripe.com/billing/subscriptions/prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes. The default value is `create_prorations`.
`proration_date`	integer	If 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](/api/invoices/create_preview) endpoint.
`quantity`	integer	The quantity you'd like to apply to the subscription item you're creating.
`tax_rates`	one of multiple schemas	A list of [Tax Rate](https://docs.stripe.com/api/tax_rates) ids. These Tax Rates will override the [`default_tax_rates`](https://docs.stripe.com/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

Responses

HTTP 200: Successful response.

Field	Type	Description
`billed_until`	integer	The time period the subscription item has been billed for.
`billing_thresholds`	one of multiple schemas	Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`current_period_end` required	integer	The end time of this subscription item's current billing period.
`current_period_start` required	integer	The start time of this subscription item's current billing period.
`discounts` required	array of one of multiple schemas	The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
`id` required	string	Unique identifier for the object.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`price` required	price
`quantity`	integer	The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
`subscription` required	string	The `subscription` this `subscription_item` belongs to.
`tax_rates`	array of tax_rate	The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors