API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/prices
List all prices
Returns a list of your active prices, excluding inline prices. For the list of inactive prices, set active to false.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
active | query | boolean | Only return prices that are active or inactive (e.g., pass `false` to list all inactive prices). |
created | query | one of multiple schemas | A filter on the list, based on the object `created` field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options. |
currency | query | string | Only return prices for the given currency. |
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. |
lookup_keys | query | array of string | Only return the price with these lookup_keys, if any exist. You can specify up to 10 lookup_keys. |
product | query | string | Only return prices for the given product. |
recurring | query | object | Only return prices with these recurring fields. |
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. |
type | query | string | Only return prices of type `recurring` or `one_time`. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of price | Details about each object. |
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/prices
Create a price
Creates a new Price for an existing Product. The Price can be recurring or one-time.
Request parameters
| Field | Type | Description |
|---|---|---|
active | boolean | Whether the price can be used for new purchases. Defaults to `true`. |
billing_scheme | string | Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes. |
currency required | string | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
currency_options | object | Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). |
custom_unit_amount | object | When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links. |
expand | array of string | Specifies which fields in the response should be expanded. |
lookup_key | string | A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. |
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`. |
nickname | string | A brief description of the price, hidden from customers. |
product | string | The ID of the [Product](https://docs.stripe.com/api/products) that this [Price](https://docs.stripe.com/api/prices) will belong to. |
product_data | object | These fields can be used to create a new product that this price will belong to. |
recurring | object | The recurring components of a price such as `interval` and `usage_type`. |
tax_behavior | string | Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. |
tiers | array of object | Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`. |
tiers_mode | string | Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price, in `graduated` tiering pricing can successively change as the quantity grows. |
transfer_lookup_key | boolean | If set to true, will atomically remove the lookup key from the existing price, and assign it to this price. |
transform_quantity | object | Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with `tiers`. |
unit_amount | integer | A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge. One of `unit_amount`, `unit_amount_decimal`, or `custom_unit_amount` is required, unless `billing_scheme=tiered`. |
unit_amount_decimal | string | Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places. Only one of `unit_amount` and `unit_amount_decimal` can be set. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the price can be used for new purchases. |
billing_scheme required | string | Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
currency_options | object | Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). |
custom_unit_amount | one of multiple schemas | When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
lookup_key | string | A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. |
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. |
nickname | string | A brief description of the price, hidden from customers. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
product required | one of multiple schemas | The ID of the product this price is associated with. |
recurring | one of multiple schemas | The recurring components of a price such as `interval` and `usage_type`. |
tax_behavior | string | Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. |
tiers | array of price_tier | Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`. |
tiers_mode | string | Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows. |
transform_quantity | one of multiple schemas | Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with `tiers`. |
type required | string | One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. |
unit_amount | integer | The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`. |
unit_amount_decimal | string | The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/prices/search
Search prices
Search for prices 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.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
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. |
page | query | string | A 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. |
query | query | string | The search query string. See [search query language](https://docs.stripe.com/search#search-query-language) and the list of supported [query fields for prices](https://docs.stripe.com/search#query-fields-for-prices). |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
data required | array of price | |
has_more required | boolean | |
next_page | string | |
object required | string | String representing the object's type. Objects of the same type share the same value. |
total_count | integer | The total number of objects that match the query, only accurate up to 10,000. |
url required | string |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/prices/{price}
Retrieve a price
Retrieves the price with the given ID.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
expand | query | array of string | Specifies which fields in the response should be expanded. |
price | path | string |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the price can be used for new purchases. |
billing_scheme required | string | Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
currency_options | object | Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). |
custom_unit_amount | one of multiple schemas | When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
lookup_key | string | A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. |
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. |
nickname | string | A brief description of the price, hidden from customers. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
product required | one of multiple schemas | The ID of the product this price is associated with. |
recurring | one of multiple schemas | The recurring components of a price such as `interval` and `usage_type`. |
tax_behavior | string | Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. |
tiers | array of price_tier | Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`. |
tiers_mode | string | Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows. |
transform_quantity | one of multiple schemas | Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with `tiers`. |
type required | string | One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. |
unit_amount | integer | The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`. |
unit_amount_decimal | string | The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/prices/{price}
Update a price
Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
price | path | string |
| Field | Type | Description |
|---|---|---|
active | boolean | Whether the price can be used for new purchases. Defaults to `true`. |
currency_options | one of multiple schemas | Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). |
expand | array of string | Specifies which fields in the response should be expanded. |
lookup_key | string | A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. |
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`. |
nickname | string | A brief description of the price, hidden from customers. |
tax_behavior | string | Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. |
transfer_lookup_key | boolean | If set to true, will atomically remove the lookup key from the existing price, and assign it to this price. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the price can be used for new purchases. |
billing_scheme required | string | Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes. |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
currency required | string | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). |
currency_options | object | Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies). |
custom_unit_amount | one of multiple schemas | When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links. |
id required | string | Unique identifier for the object. |
livemode required | boolean | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
lookup_key | string | A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. |
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. |
nickname | string | A brief description of the price, hidden from customers. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
product required | one of multiple schemas | The ID of the product this price is associated with. |
recurring | one of multiple schemas | The recurring components of a price such as `interval` and `usage_type`. |
tax_behavior | string | Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`. Once specified as either `inclusive` or `exclusive`, it cannot be changed. |
tiers | array of price_tier | Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`. |
tiers_mode | string | Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows. |
transform_quantity | one of multiple schemas | Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with `tiers`. |
type required | string | One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. |
unit_amount | integer | The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`. |
unit_amount_decimal | string | The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |