Stripe: Search products

← Products operations · Get started

Operation stripe.getproductssearch

Provider route: GET /v1/products/search. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["products"]["getProductsSearch"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.products.getProductsSearch(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.products.get_products_search(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.expand	array	Optional
query.expand[]	string	Each item	Maximum length: 5000
query.limit	integer	Optional
query.page	string	Optional	Maximum length: 5000
query.query	string	Required within parent	Maximum length: 5000

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root
data	array	Required within parent
data[]	Model	Each item	Expand Create a product — response body
has_more	boolean	Required within parent
next_page	JSON	Optional
next_page (anyOf 1)	string	Alternative	Maximum length: 5000
next_page (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object’s type. Objects of the same type share the same value. Known values: search_result
total_count	JSON	Optional
total_count (anyOf 1)	integer	Alternative	The total number of objects that match the query, only accurate up to 10,000.
total_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
url	string	Required within parent	Maximum length: 5000

Referenced models: Create a product — response body

Schemas

8 more schemas are linked from the tables above, on the schema pages.

Create a product — response body

Field	Type	Presence	Description and constraints
$	object	Root	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](https://docs.stripe.com/api#prices) to configure pricing in Payment Links, Checkout, and Subscriptions. Related guides: [Set up a subscription](https://docs.stripe.com/billing/subscriptions/set-up-subscription), [share a Payment Link](https://docs.stripe.com/payment-links), [accept payments with Checkout](https://docs.stripe.com/payments/accept-a-payment#create-product-prices-upfront), and more about [Products and Prices](https://docs.stripe.com/products-prices/overview)
active	boolean	Required within parent	Whether the product is currently available for purchase.
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
default_price	JSON	Optional
default_price (anyOf 1)	JSON	Alternative	The ID of the [Price](https://docs.stripe.com/api/prices) object that is the default price for this product.
default_price (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
default_price (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a price — response body
default_price (anyOf 2)	null	Alternative
description	JSON	Optional
description (anyOf 1)	string	Alternative	The 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. Maximum length: 5000
description (anyOf 2)	null	Alternative
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
images	array	Required within parent	A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
images[]	string	Each item	Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
marketing_features	array	Required within parent	A list of up to 15 marketing features for this product. These are displayed in [pricing tables](https://docs.stripe.com/payments/checkout/pricing-table).
marketing_features[]	Model	Each item	Expand Create a product — response body — marketing features item
metadata	object	Required within parent	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. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
name	string	Required within parent	The product's name, meant to be displayable to the customer. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: product
package_dimensions	JSON	Optional
package_dimensions (anyOf 1)	JSON	Alternative	The dimensions of this product for shipping purposes.
package_dimensions (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a product — response body — package dimensions value height, length, weight, width
package_dimensions (anyOf 2)	null	Alternative
shippable	JSON	Optional
shippable (anyOf 1)	boolean	Alternative	Whether this product is shipped (i.e., physical goods).
shippable (anyOf 2)	null	Alternative
statement_descriptor	JSON	Optional
statement_descriptor (anyOf 1)	string	Alternative	Extra information about a product which will appear on your customer's credit card statement. In the case that multiple products are billed at once, the first statement descriptor will be used. Only used for subscription payments. Maximum length: 5000
statement_descriptor (anyOf 2)	null	Alternative
tax_code	JSON	Optional
tax_code (anyOf 1)	JSON	Alternative	A [tax code](https://docs.stripe.com/tax/tax-categories) ID.
tax_code (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
tax_code (anyOf 1) (anyOf 2)	Model	Alternative	Expand Retrieve a tax code — response body
tax_code (anyOf 2)	null	Alternative
tax_details	JSON	Optional
tax_details (anyOf 1)	JSON	Alternative	Tax details for this product, including the [tax code](/tax/tax-codes) and an optional performance location.
tax_details (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a product — response body — tax details value performance location, tax code
tax_details (anyOf 2)	null	Alternative
unit_label	JSON	Optional
unit_label (anyOf 1)	string	Alternative	A label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal. Maximum length: 5000
unit_label (anyOf 2)	null	Alternative
updated	JSON	Required within parent
updated (anyOf 1)	integer	Alternative	Time at which the object was last updated. Measured in seconds since the Unix epoch. Format: unix-time
updated (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
url	JSON	Optional
url (anyOf 1)	string	Alternative	A URL of a publicly-accessible webpage for this product. Maximum length: 2048
url (anyOf 2)	null	Alternative

Referenced models: Create a product — response body — package dimensions value height, length, weight, width, Create a price — response body, Create a product — response body — marketing features item, Retrieve a tax code — response body, Create a product — response body — tax details value performance location, tax code

Create a product — response body — package dimensions value height, length, weight, width

Field	Type	Presence	Description and constraints
$	object	Root
height	JSON	Required within parent
height (anyOf 1)	number	Alternative	Height, in inches.
height (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
length	JSON	Required within parent
length (anyOf 1)	number	Alternative	Length, in inches.
length (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
weight	JSON	Required within parent
weight (anyOf 1)	number	Alternative	Weight, in ounces.
weight (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
width	JSON	Required within parent
width (anyOf 1)	number	Alternative	Width, in inches.
width (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Create a product — response body — marketing features item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Optional	The marketing feature name. Up to 80 characters long. Maximum length: 5000

Retrieve a tax code — response body

Field	Type	Presence	Description and constraints
$	object	Root	[Tax codes](https://stripe.com/docs/tax/tax-categories) classify goods and services for tax purposes.
description	string	Required within parent	A detailed description of which types of products the tax code represents. Maximum length: 5000
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	string	Required within parent	A short name for the tax code. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: tax_code
requirements	JSON	Optional
requirements (anyOf 1)	JSON	Alternative	An object that describes more information about the tax location required for this tax code. Some tax codes require a [performance location](/tax/location-sales#required-versus-optional-performance-locations) to calculate tax correctly.
requirements (anyOf 1) (anyOf 1)	Model	Alternative	Expand Retrieve a tax code — response body — requirements / value / performance_location: optional, required
requirements (anyOf 2)	null	Alternative

Referenced models: Retrieve a tax code — response body — requirements / value / performance_location: optional, required

Delete a product — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: product

Policy, approvals and errors

SDK function policy ID: stripe.getproductssearch. Catalog operation: GetProductsSearch. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source