API reference
Products
Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with Prices to configure pricing in Payment Links, Checkout, and Subscriptions. Related guides: Set up a subscription, share a Payment Link, accept payments with Checkout, and more about Products and Prices
https://api.knoxapi.comCreate a product
POST/v1/products
Creates a new product object.
Body parameters
namestringRequiredThe product's name, meant to be displayable to the customer.
activebooleanWhether the product is currently available for purchase. Defaults to
true.default_price_dataobjectData used to generate a new Price object. This Price will be set as the default price for this product.
Show 8 child parameters
currencystringRequiredcurrency_optionsobjectcustom_unit_amountobjectShow 4 child parameters
enabledbooleanRequiredmaximumintegerminimumintegerpresetinteger
metadataobjectrecurringobjectShow 2 child parameters
intervalstringRequiredPossible valuesdaymonthweekyear
interval_countinteger
tax_behaviorstringPossible valuesexclusiveinclusiveunspecified
unit_amountintegerunit_amount_decimalstring
descriptionstringThe product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
expandarray of stringsSpecifies which fields in the response should be expanded.
idstringAn identifier will be randomly generated by Stripe. You can optionally override this ID, but the ID must be unique across all products in your Stripe account.
imagesarray of stringsA list of up to 8 URLs of images for this product, meant to be displayable to the customer.
marketing_featuresarray of objectsA list of up to 15 marketing features for this product. These are displayed in pricing tables.
Show 1 child parameter
namestringRequired
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.package_dimensionsobjectThe dimensions of this product for shipping purposes.
Show 4 child parameters
heightnumberRequiredlengthnumberRequiredweightnumberRequiredwidthnumberRequired
shippablebooleanWhether this product is shipped (i.e., physical goods).
statement_descriptorstringAn arbitrary string to be displayed on your customer's credit card or bank statement. While most banks display this information consistently, some may display it incorrectly or not at all. This may be up to 22 characters. The statement description may not include
<,>,\,",'characters, and will appear on your customer's statement in capital letters. Non-ASCII characters are automatically stripped. It must contain at least one letter. Only used for subscription payments.tax_codestringA tax code ID.
unit_labelstringA label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal.
urlstringA URL of a publicly-accessible webpage for this product.
Returns
The product object.
curl https://api.knoxapi.com/v1/products \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d name=T-shirtconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const product = await stripe.products.create({
name: 'T-shirt',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
product = client.v1.products.create(params={
"name": "T-shirt",
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
product = Stripe::Product.create({
name: 'T-shirt',
}){
"active": true,
"created": 1234567890,
"default_price": "price_1PgafmB7WZ01zgkW02Hf9z6c",
"description": "Comfortable gray cotton t-shirt",
"id": "prod_QXg1hqf4jFNsqG",
"images": [],
"livemode": false,
"marketing_features": [],
"metadata": {},
"name": "T-shirt",
"object": "product",
"package_dimensions": {
"height": 1221029593,
"length": 1106363674,
"weight": 791592328,
"width": 113126854
},
"shippable": null,
"statement_descriptor": null,
"tax_code": null,
"unit_label": null,
"updated": 1234567890,
"url": null,
"type": "good"
}List all products
GET/v1/products
Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.
Query parameters
activebooleanOnly return products that are active or inactive (e.g., pass
falseto list all inactive products).createdobject | integerOnly return products that were created during the given date interval.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
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.
idsarray of stringsOnly return products with the given IDs. Cannot be used with starting_after or ending_before.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
shippablebooleanOnly return products that can be shipped (i.e., physical, not digital products).
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.urlstringOnly return products with the given url.
Returns
A list of product objects.
curl -G https://api.knoxapi.com/v1/products \
-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.products.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.products.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::Product.list({
limit: 3,
}){
"object": "list",
"url": "/v1/products",
"has_more": false,
"data": [
{
"active": true,
"created": 1234567890,
"default_price": "price_1PgafmB7WZ01zgkW02Hf9z6c",
"description": "Comfortable gray cotton t-shirt",
"id": "prod_QXg1hqf4jFNsqG",
"images": [],
"livemode": false,
"marketing_features": [],
"metadata": {},
"name": "T-shirt",
"object": "product",
"package_dimensions": {
"height": 1221029593,
"length": 1106363674,
"weight": 791592328,
"width": 113126854
},
"shippable": null,
"statement_descriptor": null,
"tax_code": null,
"unit_label": null,
"updated": 1234567890,
"url": null,
"type": "good"
}
]
}Search products
GET/v1/products/search
Search for products 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 products.
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 product objects.
curl -G https://api.knoxapi.com/v1/products/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.products.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.products.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::Product.search({
query: "metadata['order_id']:'6735'",
}){
"object": "search_result",
"url": "/v1/products/search",
"has_more": false,
"data": [
{
"active": true,
"created": 1234567890,
"default_price": "price_1PgafmB7WZ01zgkW02Hf9z6c",
"description": "Comfortable gray cotton t-shirt",
"id": "prod_QXg1hqf4jFNsqG",
"images": [],
"livemode": false,
"marketing_features": [],
"metadata": {},
"name": "T-shirt",
"object": "product",
"package_dimensions": {
"height": 1221029593,
"length": 1106363674,
"weight": 791592328,
"width": 113126854
},
"shippable": null,
"statement_descriptor": null,
"tax_code": null,
"unit_label": null,
"updated": 1234567890,
"url": null,
"type": "good"
}
],
"next_page": null
}Update a product
POST/v1/products/{id}
Updates the specific product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Path parameters
idstringRequired
Body parameters
activebooleanWhether the product is available for purchase.
default_pricestringThe ID of the Price object that is the default price for this product.
descriptionstringThe product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
expandarray of stringsSpecifies which fields in the response should be expanded.
imagesarray of stringsA list of up to 8 URLs of images for this product, meant to be displayable to the customer.
marketing_featuresarray of objectsA list of up to 15 marketing features for this product. These are displayed in pricing tables.
Show 1 child parameter
namestringRequired
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.namestringThe product's name, meant to be displayable to the customer.
package_dimensionsobjectThe dimensions of this product for shipping purposes.
Show 4 child parameters
heightnumberRequiredlengthnumberRequiredweightnumberRequiredwidthnumberRequired
shippablebooleanWhether this product is shipped (i.e., physical goods).
statement_descriptorstringAn arbitrary string to be displayed on your customer's credit card or bank statement. While most banks display this information consistently, some may display it incorrectly or not at all. This may be up to 22 characters. The statement description may not include
<,>,\,",'characters, and will appear on your customer's statement in capital letters. Non-ASCII characters are automatically stripped. It must contain at least one letter. May only be set iftype=service. Only used for subscription payments.tax_codestringA tax code ID.
unit_labelstringA label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal. May only be set if
type=service.urlstringA URL of a publicly-accessible webpage for this product.
Returns
The product object.
curl https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG \
-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 product = await stripe.products.update('prod_QXg1hqf4jFNsqG', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
product = client.v1.products.update("prod_QXg1hqf4jFNsqG", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
product = Stripe::Product.update('prod_QXg1hqf4jFNsqG', {
metadata: {
order_id: '6735',
},
}){
"active": true,
"created": 1234567890,
"default_price": "price_1PgafmB7WZ01zgkW02Hf9z6c",
"description": "Comfortable gray cotton t-shirt",
"id": "prod_QXg1hqf4jFNsqG",
"images": [],
"livemode": false,
"marketing_features": [],
"metadata": {},
"name": "T-shirt",
"object": "product",
"package_dimensions": {
"height": 1221029593,
"length": 1106363674,
"weight": 791592328,
"width": 113126854
},
"shippable": null,
"statement_descriptor": null,
"tax_code": null,
"unit_label": null,
"updated": 1234567890,
"url": null,
"type": "good"
}Retrieve a product
GET/v1/products/{id}
Retrieves the details of an existing product. Supply the unique product ID from either a product creation request or the product list, and Stripe will return the corresponding product information.
Path parameters
idstringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The product object.
curl https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const product = await stripe.products.retrieve('prod_QXg1hqf4jFNsqG');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
product = client.v1.products.retrieve("prod_QXg1hqf4jFNsqG")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
product = Stripe::Product.retrieve('prod_QXg1hqf4jFNsqG'){
"active": true,
"created": 1234567890,
"default_price": "price_1PgafmB7WZ01zgkW02Hf9z6c",
"description": "Comfortable gray cotton t-shirt",
"id": "prod_QXg1hqf4jFNsqG",
"images": [],
"livemode": false,
"marketing_features": [],
"metadata": {},
"name": "T-shirt",
"object": "product",
"package_dimensions": {
"height": 1221029593,
"length": 1106363674,
"weight": 791592328,
"width": 113126854
},
"shippable": null,
"statement_descriptor": null,
"tax_code": null,
"unit_label": null,
"updated": 1234567890,
"url": null,
"type": "good"
}Delete a product
DELETE/v1/products/{id}
Delete a product. Deleting a product is only possible if it has no prices associated with it. Additionally, deleting a product with type=good is only possible if it has no SKUs associated with it.
Path parameters
idstringRequired
Returns
The deleted_product object.
curl -X DELETE https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const deletedProduct = await stripe.products.del('prod_QXg1hqf4jFNsqG');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
deleted_product = client.v1.products.delete("prod_QXg1hqf4jFNsqG")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
deleted_product = Stripe::Product.delete('prod_QXg1hqf4jFNsqG'){
"deleted": true,
"id": "prod_QXg1hqf4jFNsqG",
"object": "product"
}Attach a feature to a product
POST/v1/products/{product}/features
Creates a product_feature, which represents a feature attachment to a product
Path parameters
productstringRequired
Body parameters
entitlement_featurestringRequiredThe ID of the Feature object attached to this product.
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The product_feature object.
curl https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG/features \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d entitlement_feature=exampleconst Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const response = await stripe.rawRequest('POST', '/v1/products/prod_QXg1hqf4jFNsqG/features', {
entitlement_feature: 'example',
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("post", "/v1/products/prod_QXg1hqf4jFNsqG/features", entitlement_feature="example")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:post, '/v1/products/prod_QXg1hqf4jFNsqG/features', {
entitlement_feature: 'example',
}){
"entitlement_feature": {
"active": false,
"id": "",
"livemode": false,
"lookup_key": "",
"metadata": {},
"name": "",
"object": "entitlements.feature"
},
"id": "",
"livemode": false,
"object": "product_feature"
}List all features attached to a product
GET/v1/products/{product}/features
Retrieve a list of features for a product
Path parameters
productstringRequired
Query parameters
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of product_feature objects.
curl -G https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG/features \
-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 response = await stripe.rawRequest('GET', '/v1/products/prod_QXg1hqf4jFNsqG/features', {
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("get", "/v1/products/prod_QXg1hqf4jFNsqG/features", limit=3)require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:get, '/v1/products/prod_QXg1hqf4jFNsqG/features', {
limit: 3,
}){
"object": "list",
"url": "/v1/products",
"has_more": false,
"data": [
{
"entitlement_feature": {
"active": false,
"id": "",
"livemode": false,
"lookup_key": "",
"metadata": {},
"name": "",
"object": "entitlements.feature"
},
"id": "",
"livemode": false,
"object": "product_feature"
}
]
}Retrieve a product_feature
GET/v1/products/{product}/features/{id}
Retrieves a product_feature, which represents a feature attachment to a product
Path parameters
idstringRequiredThe ID of the product_feature.
productstringRequiredThe ID of the product.
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The product_feature object.
curl https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG/features/ \
-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('GET', '/v1/products/prod_QXg1hqf4jFNsqG/features/');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
response = client.raw_request("get", "/v1/products/prod_QXg1hqf4jFNsqG/features/")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:get, '/v1/products/prod_QXg1hqf4jFNsqG/features/'){
"entitlement_feature": {
"active": false,
"id": "",
"livemode": false,
"lookup_key": "",
"metadata": {},
"name": "",
"object": "entitlements.feature"
},
"id": "",
"livemode": false,
"object": "product_feature"
}Remove a feature from a product
DELETE/v1/products/{product}/features/{id}
Deletes the feature attachment to a product
Path parameters
idstringRequiredproductstringRequired
Returns
The deleted_product_feature object.
curl -X DELETE https://api.knoxapi.com/v1/products/prod_QXg1hqf4jFNsqG/features/prodft_BcMBZUWCIOEgEc \
-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/products/prod_QXg1hqf4jFNsqG/features/prodft_BcMBZUWCIOEgEc');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/products/prod_QXg1hqf4jFNsqG/features/prodft_BcMBZUWCIOEgEc")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
response = Stripe.raw_request(:delete, '/v1/products/prod_QXg1hqf4jFNsqG/features/prodft_BcMBZUWCIOEgEc'){
"deleted": true,
"id": "prodft_BcMBZUWCIOEgEc",
"object": "product_feature"
}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.