Products Catalog

The Products catalog provides tools for managing product catalogs, variants, and customer orders for retail and e-commerce.

Key resources

Resource (TypeScript)	Resource (Python)	Purpose
client.products	client.products	Categories and products
client.productVariants	—	Product variations (size, color)
client.productVariantAxes	—	Define variation axes
client.productOrders	client.product_orders	Customer orders

How it fits together

A category groups products; each product is priced by one or more variants, and each variant is described by axis values (Size, Color, Material). An order captures items — each line referencing a variant — plus pricing, shipping, and fulfillment.

• A category groups products for display.
• A product is an item; in the TypeScript SDK it requires at least one variant for pricing.
• A variant is a variation of a product, described by axis values (for example Size: 'Large', Color: 'Black').
• A variant axis defines the dimensions of variation (Size, Color, Material).
• An order captures items (each referencing a variantId), pricing, shipping, and fulfillment.

How an order works

A customer browses the catalog, chooses a specific variant, and places an order — which then moves through the fulfillment lifecycle.

Why it matters

• For the catalog — model a product once with variants and axes; the same data powers your web storefront and grounds the AI agent that answers product questions and takes orders.
• For ordering — orders capture the exact variant, axis values, and price at order time, so records stay accurate even when the catalog changes.
• For fulfillment — explicit stock status and a clear order lifecycle (with delivery and return branches) keep inventory, operations, and the customer aligned.

SDK parity matrix

The table below shows which operations the SDK example guides demonstrate for each language. Where a cell is —, the guide does not include an example for that language.

Area	Operations	TypeScript	Python
Categories	create, get, list, update, delete, batch	✓	✓
Products	create, get, list, update, delete, batch	✓	✓
Products	get by SKU	—	✓
Variant axes	create, get, get by name, list, update, delete, batch	✓	—
Product variants	create, get, get by SKU, get default, update, delete, batch	✓	—
Orders	create, get	✓	✓
Orders	get by customer	—	✓
Orders	list, update, update status, cancel, delete	✓	—

note

A key shape difference between the guides: the TypeScript product create embeds a required variants array, while the Python product create sets stock_quantity / track_inventory on the product and does not pass variants. Each page below shows each SDK exactly as its guide does.

Status models

Enum	Values
OrderStatus	pending, confirmed, preparing, ready, out_for_delivery, completed, cancelled, returned
PaymentStatus	pending, paid, partial, failed, refunded
VariantAxisType	TEXT, SWATCH
Stock status	in_stock, low_stock, out_of_stock

Pages

• Categories — group products for display
• Products — create and manage products
• Variants & axes — variations and the axes that describe them
• Orders — create and manage retail orders
• Quickstart — an end-to-end electronics-store flow