Stripe: Create a product

Stripe products.postProducts: arguments, response, policy and SDK examples.

Operation stripe.postproducts

Provider route: POST /v1/products. 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"]["postProducts"]>[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.postProducts(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.post_products(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`headers`	object	Optional	Additional keys: not allowed
`headers.Idempotency-Key`	string	Optional	Minimum length: 1 Maximum length: 255
`body`	object	Required within parent	Additional keys: not allowed
`body.active`	boolean	Optional	Whether the product is currently available for purchase. Defaults to `true`.
`body.default_price_data`	object	Optional	Data used to generate a new [Price](https://docs.stripe.com/api/prices) object. This Price will be set as the default price for this product.
`body.default_price_data.currency`	string	Required within parent	Format: currency
`body.default_price_data.currency_options`	object	Optional	Additional keys: see wildcard field
`body.default_price_data.currency_options.*`	Model	Additional keys	Expand Create a price — request body — body currency options value
`body.default_price_data.custom_unit_amount`	object	Optional
`body.default_price_data.custom_unit_amount.enabled`	boolean	Required within parent
`body.default_price_data.custom_unit_amount.maximum`	integer	Optional
`body.default_price_data.custom_unit_amount.minimum`	integer	Optional
`body.default_price_data.custom_unit_amount.preset`	integer	Optional
`body.default_price_data.metadata`	object	Optional	Additional keys: see wildcard field
`body.default_price_data.metadata.*`	string	Additional keys
`body.default_price_data.recurring`	object	Optional
`body.default_price_data.recurring.interval`	string	Required within parent	One of: day, month, week, year
`body.default_price_data.recurring.interval_count`	integer	Optional
`body.default_price_data.tax_behavior`	string	Optional	One of: exclusive, inclusive, unspecified
`body.default_price_data.unit_amount`	integer	Optional
`body.default_price_data.unit_amount_decimal`	string	Optional	Format: decimal
`body.description`	string	Optional	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: 40000
`body.expand`	array	Optional	Specifies which fields in the response should be expanded.
`body.expand[]`	string	Each item	Maximum length: 5000
`body.id`	string	Optional	An 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. Maximum length: 5000
`body.images`	array	Optional	A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
`body.images[]`	string	Each item
`body.marketing_features`	array	Optional	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).
`body.marketing_features[]`	object	Each item
`body.marketing_features[].name`	string	Required within parent	Maximum length: 5000
`body.metadata`	object	Optional	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`. Additional keys: see wildcard field
`body.metadata.*`	string	Additional keys
`body.name`	string	Required within parent	The product’s name, meant to be displayable to the customer. Maximum length: 5000
`body.package_dimensions`	object	Optional	The dimensions of this product for shipping purposes.
`body.package_dimensions.height`	number	Required within parent
`body.package_dimensions.length`	number	Required within parent
`body.package_dimensions.weight`	number	Required within parent
`body.package_dimensions.width`	number	Required within parent
`body.shippable`	boolean	Optional	Whether this product is shipped (i.e., physical goods).
`body.statement_descriptor`	string	Optional	An 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. Maximum length: 22
`body.tax_code`	string	Optional	A [tax code](https://docs.stripe.com/tax/tax-categories) ID.
`body.tax_details`	object	Optional	Tax details for this product, including the [tax code](/tax/tax-codes) and an optional performance location.
`body.tax_details.performance_location`	string	Optional	Maximum length: 5000
`body.tax_details.tax_code`	JSON	Optional
`body.tax_details.tax_code (anyOf 1)`	string	Alternative
`body.tax_details.tax_code (anyOf 2)`	string	Alternative	One of:
`body.unit_label`	string	Optional	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: 12
`body.url`	string	Optional	A URL of a publicly-accessible webpage for this product. Maximum length: 5000

Referenced models: Create a price — request body — body currency options value

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
`$`	Model	Root	Expand Create a product — response body

Referenced models: Create a product — response body

Schemas

9 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 price — request body — body currency options value

Field	Type	Presence	Description and constraints
`$`	object	Root
`custom_unit_amount`	object	Optional
`custom_unit_amount.enabled`	boolean	Required within parent
`custom_unit_amount.maximum`	integer	Optional
`custom_unit_amount.minimum`	integer	Optional
`custom_unit_amount.preset`	integer	Optional
`tax_behavior`	string	Optional	One of: exclusive, inclusive, unspecified
`tiers`	array	Optional
`tiers[]`	object	Each item
`tiers[].flat_amount`	integer	Optional
`tiers[].flat_amount_decimal`	string	Optional	Format: decimal
`tiers[].unit_amount`	integer	Optional
`tiers[].unit_amount_decimal`	string	Optional	Format: decimal
`tiers[].up_to`	JSON	Required within parent
`tiers[].up_to (anyOf 1)`	string	Alternative	One of: inf Maximum length: 5000
`tiers[].up_to (anyOf 2)`	integer	Alternative
`unit_amount`	integer	Optional
`unit_amount_decimal`	string	Optional	Format: decimal

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

Create a product — response body — tax details value performance location, tax code

Field	Type	Presence	Description and constraints
`$`	object	Root	Tax details contains information about the data that was used to calculate taxes.
`performance_location`	JSON	Optional
`performance_location (anyOf 1)`	string	Alternative	The ID of a tax location with type `performance`, representing where the performance takes place. Maximum length: 5000
`performance_location (anyOf 2)`	null	Alternative
`tax_code`	JSON	Optional
`tax_code (anyOf 1)`	string	Alternative	A [tax code](https://docs.stripe.com/tax/tax-categories) ID. Maximum length: 5000
`tax_code (anyOf 2)`	null	Alternative

Policy, approvals and errors

SDK function policy ID: stripe.postproducts. Catalog operation: PostProducts. 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

Report an issue with this page