ce-catalog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LLM Docs Header: All requests to
https://llm-docs.commercengine.io
must include the
Accept: text/markdown
header (or append
.md
to the URL path). Without it, responses return HTML instead of parseable markdown.

LLM 文档头部要求：所有发往
https://llm-docs.commercengine.io
的请求必须携带
Accept: text/markdown
请求头（或者在URL路径末尾追加
.md
）。缺少该头部时，响应将返回HTML而非可解析的markdown格式。

Products & Catalog

商品与目录

Prerequisite: SDK initialized and anonymous auth completed. See
setup/
.

前置条件：已完成SDK初始化和匿名身份验证，详情参考
setup/
文档。

Quick Reference

快速参考

Task	SDK Method
List products	`sdk.catalog.listProducts({ page, limit, category_id })`
Get product detail	`sdk.catalog.getProductDetail({ product_id_or_slug })`
List variants	`sdk.catalog.listProductVariants({ product_id })`
Get variant detail	`sdk.catalog.getVariantDetail({ product_id, variant_id })`
List SKUs (flat)	`sdk.catalog.listSkus()`
List categories	`sdk.catalog.listCategories()`
Search products	`sdk.catalog.searchProducts({ query: searchTerm, filter?, sort?, facets? })`
Get reviews	`sdk.catalog.listProductReviews({ product_id })`
Submit review	`sdk.catalog.createProductReview({ product_id }, { ... })`
Similar products	`sdk.catalog.listSimilarProducts({ product_id })`
Upsell products	`sdk.catalog.listUpSellProducts({ product_id })`
Cross-sell products	`sdk.catalog.listCrossSellProducts({ product_id })`

任务	SDK 方法
商品列表查询	`sdk.catalog.listProducts({ page, limit, category_id })`
获取商品详情	`sdk.catalog.getProductDetail({ product_id_or_slug })`
变体列表查询	`sdk.catalog.listProductVariants({ product_id })`
获取变体详情	`sdk.catalog.getVariantDetail({ product_id, variant_id })`
扁平SKU列表查询	`sdk.catalog.listSkus()`
分类列表查询	`sdk.catalog.listCategories()`
商品搜索	`sdk.catalog.searchProducts({ query: searchTerm, filter?, sort?, facets? })`
获取评价列表	`sdk.catalog.listProductReviews({ product_id })`
提交评价	`sdk.catalog.createProductReview({ product_id }, { ... })`
相似商品推荐	`sdk.catalog.listSimilarProducts({ product_id })`
加价购商品推荐	`sdk.catalog.listUpSellProducts({ product_id })`
交叉销售商品推荐	`sdk.catalog.listCrossSellProducts({ product_id })`

Product Hierarchy

商品层级

Understanding the Product → Variant → SKU relationship is critical:

Product (has_variant: false)
  └─ A simple product with one SKU, one price

Product (has_variant: true)
  ├─ Variant A (Color: Red, Size: M) → SKU: "RED-M-001"
  ├─ Variant B (Color: Red, Size: L) → SKU: "RED-L-001"
  └─ Variant C (Color: Blue, Size: M) → SKU: "BLU-M-001"

Concept	Return Type	Description	When to Use
Product	`Product`	Base item with nested `variants` array	PLP where one card per product is desired (e.g., "T-Shirt" card showing color/size selectors)
Variant	—	A specific option combo (Color + Size)	PDPs, cart items — accessed via `listProductVariants()` or nested in Product
SKU / Item	`Item`	Flat sellable unit — each variant is its own record	PLP where a flat grid is desired (each color/size combo = separate card), or any page with filters/sorting/search

理解「商品→变体→SKU」的关联关系至关重要：

Product (has_variant: false)
  └─ 单SKU单价格的简单商品

Product (has_variant: true)
  ├─ Variant A (颜色: 红, 尺码: M) → SKU: "RED-M-001"
  ├─ Variant B (颜色: 红, 尺码: L) → SKU: "RED-L-001"
  └─ Variant C (颜色: 蓝, 尺码: M) → SKU: "BLU-M-001"

概念	返回类型	说明	适用场景
Product（商品）	`Product`	基础条目，包含嵌套的 `variants` （变体）数组	需要每个商品展示一张卡片的商品列表页（PLP），例如展示颜色/尺码选择器的「T恤」卡片
Variant（变体）	—	特定的属性组合（颜色+尺码）	商品详情页（PDP）、购物车条目，可通过 `listProductVariants()` 获取或在Product对象中嵌套获取
SKU / Item（库存单元）	`Item`	扁平化的可售单元，每个变体对应一条独立记录	需要展示扁平网格的商品列表页（每个颜色/尺码组合对应独立卡片），或者任何需要筛选/排序/搜索的页面

Decision Tree

决策树

User Request
    │
    ├─ "Show products" / "Product list"
    │   ├─ With filters/sorting/search? → sdk.catalog.searchProducts({ query, filter, sort, facets })
    │   │   → Returns Item[] (flat SKUs) + facet_distribution + facet_stats
    │   ├─ Flat grid (no filters)? → sdk.catalog.listSkus()
    │   │   → Returns Item[] (flat SKUs)
    │   └─ One card per product (group variants)? → sdk.catalog.listProducts()
    │       → Returns Product[] (with nested variants)
    │
    ├─ "Product detail page"
    │   ├─ sdk.catalog.getProductDetail({ product_id_or_slug })
    │   └─ If has_variant → sdk.catalog.listProductVariants({ product_id })
    │
    ├─ "Search" / "Filter" / "Sort"
    │   └─ sdk.catalog.searchProducts({ query, filter, sort, facets })
    │       → Returns Item[] + facet_distribution + facet_stats
    │
    ├─ "Categories" / "Navigation"
    │   └─ sdk.catalog.listCategories()
    │
    ├─ "Reviews"
    │   ├─ Read → sdk.catalog.listProductReviews({ product_id })
    │   └─ Write → sdk.catalog.createProductReview({ product_id }, body)
    │
    └─ "Recommendations"
        ├─ Similar → sdk.catalog.listSimilarProducts()
        ├─ Upsell → sdk.catalog.listUpSellProducts()
        └─ Cross-sell → sdk.catalog.listCrossSellProducts()

用户请求
    │
    ├─ "展示商品" / "商品列表"
    │   ├─ 需要筛选/排序/搜索？ → sdk.catalog.searchProducts({ query, filter, sort, facets })
    │   │   → 返回 Item[]（扁平SKU） + facet_distribution（分面分布） + facet_stats（分面统计）
    │   ├─ 无筛选的扁平网格？ → sdk.catalog.listSkus()
    │   │   → 返回 Item[]（扁平SKU）
    │   └─ 每个商品一张卡片（变体分组展示）？ → sdk.catalog.listProducts()
    │       → 返回 Product[]（嵌套变体结构）
    │
    ├─ "商品详情页"
    │   ├─ sdk.catalog.getProductDetail({ product_id_or_slug })
    │   └─ 如果存在变体 → sdk.catalog.listProductVariants({ product_id })
    │
    ├─ "搜索" / "筛选" / "排序"
    │   └─ sdk.catalog.searchProducts({ query, filter, sort, facets })
    │       → 返回 Item[] + 分面分布 + 分面统计
    │
    ├─ "分类" / "导航"
    │   └─ sdk.catalog.listCategories()
    │
    ├─ "评价"
    │   ├─ 读取 → sdk.catalog.listProductReviews({ product_id })
    │   └─ 写入 → sdk.catalog.createProductReview({ product_id }, body)
    │
    └─ "推荐商品"
        ├─ 相似商品 → sdk.catalog.listSimilarProducts()
        ├─ 加价购 → sdk.catalog.listUpSellProducts()
        └─ 交叉销售 → sdk.catalog.listCrossSellProducts()

Key Patterns

核心使用模式

Product Listing Page (PLP)

商品列表页（PLP）

For PLPs with filters, sorting, or search — use
searchProducts
(recommended). It returns

Item[]

(flat SKUs) plus

facet_distribution

and

facet_stats

for building filter UI:

typescript

const { data, error } = await sdk.catalog.searchProducts({
  query: "running shoes",
  filter: "pricing.selling_price 50 TO 200 AND categories.name = footwear",
  sort: ["pricing.selling_price:asc"],
  facets: ["categories.name", "product_type", "tags"],
  page: 1,
  limit: 20,
});

// data.skus → Item[] (flat list — each variant is its own record)
// data.facet_distribution → { [attribute]: { [value]: count } }
// data.facet_stats → { [attribute]: { min, max } } (e.g. price range)
// data.pagination → { page, limit, total, total_pages }

// filter also accepts arrays — conditions are AND'd:
// filter: ["product_type = physical", "rating >= 4"]
//
// Nested arrays express OR within AND:
// filter: ["pricing.selling_price 50 TO 200", ["categories.name = footwear", "categories.name = apparel"]]

For PLPs without filters where one card per product is desired (variants grouped under a single card):

typescript

const { data, error } = await sdk.catalog.listProducts({
  page: 1,
  limit: 20,
  category_id: ["cat_123"],  // Optional: filter by category
});

// data.products → Product[] (each product may contain a variants array)
// Check product.has_variant to know if options exist

For a flat grid without filters (each variant = separate card):

typescript

const { data, error } = await sdk.catalog.listSkus();
// Returns Item[] — same flat type as searchProducts

带筛选、排序或搜索功能的PLP推荐使用
searchProducts
，它返回

Item[]

（扁平SKU）以及用于构建筛选UI的

facet_distribution

和

facet_stats

：

typescript

const { data, error } = await sdk.catalog.searchProducts({
  query: "running shoes",
  filter: "pricing.selling_price 50 TO 200 AND categories.name = footwear",
  sort: ["pricing.selling_price:asc"],
  facets: ["categories.name", "product_type", "tags"],
  page: 1,
  limit: 20,
});

// data.skus → Item[]（扁平列表，每个变体对应一条独立记录）
// data.facet_distribution → { [属性]: { [属性值]: 数量 } }
// data.facet_stats → { [属性]: { min, max } } （例如价格区间）
// data.pagination → { page, limit, total, total_pages }

// filter也支持数组格式，多个条件为AND关系：
// filter: ["product_type = physical", "rating >= 4"]
//
// 嵌套数组表示AND条件内的OR关系：
// filter: ["pricing.selling_price 50 TO 200", ["categories.name = footwear", "categories.name = apparel"]]

无筛选功能、需要变体分组展示为单张卡片的PLP：

typescript

const { data, error } = await sdk.catalog.listProducts({
  page: 1,
  limit: 20,
  category_id: ["cat_123"],  // 可选：按分类筛选
});

// data.products → Product[]（每个商品可能包含variants数组）
// 可通过product.has_variant判断是否存在可选规格

无筛选功能的扁平网格PLP（每个变体对应独立卡片）：

typescript

const { data, error } = await sdk.catalog.listSkus();
// 返回Item[]，和searchProducts返回的扁平结构一致

Product Detail Page (PDP)

商品详情页（PDP）

typescript

const { data, error } = await sdk.catalog.getProductDetail({
  product_id_or_slug: "blue-running-shoes",
});

const product = data?.product;

// If product has variants, fetch them
if (product?.has_variant) {
  const { data: variantData } = await sdk.catalog.listProductVariants({
    product_id: product.id,
  });
  // variantData.variants contains all options with pricing and stock
}

typescript

const { data, error } = await sdk.catalog.getProductDetail({
  product_id_or_slug: "blue-running-shoes",
});

const product = data?.product;

// 如果商品存在变体，单独获取变体列表
if (product?.has_variant) {
  const { data: variantData } = await sdk.catalog.listProductVariants({
    product_id: product.id,
  });
  // variantData.variants包含所有带价格和库存的规格选项
}

Product Types

商品类型

Type	Description	Key Fields
`physical`	Tangible goods requiring shipping	`shipping` , `inventory`
`digital`	Downloadable or virtual products	No shipping required
`bundle`	Group of products sold together	Contains sub-items

类型	说明	核心字段
`physical`	需要配送的实物商品	`shipping` , `inventory`
`digital`	可下载或虚拟商品	无需配送
`bundle`	多件商品打包售卖的捆绑商品	包含子商品条目

Inventory & Availability

库存与可售状态

stock_available
— Boolean, always present on Product, Variant, and SKU schemas. Use it to disable "Add to Cart" or show "Out of Stock" when
```
false
```
.
backorder
— Boolean, set per product in Admin. When
```
true
```
, the product accepts orders even when out of stock. If your business allows backorders, keep the button enabled when
```
stock_available
```
is
```
false
```
but
```
backorder
```
is
```
true
```
.
Inventory count — Catalog APIs (
```
listProducts
```
,
```
listSkus
```
, etc.) support including inventory data in the response. Use this to display numeric stock levels in the UI.

stock_available
：布尔值，在商品、变体、SKU结构中始终存在。值为
```
false
```
时可禁用「加入购物车」按钮或展示「缺货」状态。
backorder
：布尔值，在管理后台针对单个商品配置。值为
```
true
```
时，即使商品缺货也可接受订单。如果业务支持预售/backorder，当
```
stock_available
```
为
```
false
```
但
```
backorder
```
为
```
true
```
时，可保持购买按钮可用。
库存数量：
```
listProducts
```
、
```
listSkus
```
等目录API支持在响应中返回库存数据，可用于在UI中展示具体库存数值。

Customer Groups & Pricing

客户分组与定价

An advanced feature for B2B storefronts where the admin has configured customer groups (e.g., retailers, stockists, distributors). When

customer_group_id

is sent in API requests, product listings, pricing, and promotions are returned for that specific group.

Do not pass the header per-call. Set it once via

defaultHeaders

in SDK config (see

setup/

§ "Default Headers"). After the user logs in, update the SDK instance with their group ID — all subsequent SDK calls automatically include it.

这是面向B2B门店的高级功能，管理员可配置不同客户分组（例如零售商、经销商、分销商）。在API请求中传入

customer_group_id

时，将返回对应分组专属的商品列表、定价和促销规则。

不要每次调用都单独传请求头，在SDK配置中通过

defaultHeaders

统一设置即可（参考

setup/

章节的「默认请求头」部分）。用户登录后，更新SDK实例的用户分组ID，后续所有SDK调用会自动携带该参数。

Wishlists

愿望清单

Commerce Engine supports wishlists (add, remove, fetch) via SDK methods. These skills cover the main storefront flows — for wishlists and other secondary features, refer to the LLM API reference or CE docs.

Commerce Engine通过SDK方法支持愿望清单功能（添加、移除、查询）。本文档覆盖了主要的门店流程，愿望清单及其他次要功能请参考LLM API 参考文档或CE 官方文档。

Common Pitfalls

常见误区

Level	Issue	Solution
CRITICAL	Building PLP with filters using `listProducts()`	Use `searchProducts({ query, filter, sort, facets })` — it returns `data.skus` ( `Item[]` ) + `data.facet_distribution` + `data.facet_stats` . `listProducts()` returns `Product[]` with no facets. Uses Meilisearch filter syntax (e.g. `"rating > 4 AND product_type = physical"` ).
CRITICAL	Confusing `Product` vs `Item` types	`listProducts()` returns `Product[]` (grouped, with variants array). `listSkus()` and `searchProducts()` return `Item[]` (flat — each variant is its own record).
HIGH	Ignoring `has_variant` flag	Always check `has_variant` before trying to access variant data
HIGH	Adding product to cart instead of variant	When `has_variant: true` , must add the specific variant, not the product
MEDIUM	Not using `slug` for URLs	Use `slug` field for SEO-friendly URLs, `product_id_or_slug` accepts both
MEDIUM	Missing pagination	All list endpoints return `pagination` — use `page` and `limit` params
LOW	Re-fetching categories	Categories rarely change — cache them client-side

严重等级	问题	解决方案
CRITICAL（严重）	使用 `listProducts()` 构建带筛选功能的商品列表页	使用 `searchProducts({ query, filter, sort, facets })` ，它会返回 `data.skus` （ `Item[]` 类型）+ `data.facet_distribution` + `data.facet_stats` 。 `listProducts()` 返回不带分面数据的 `Product[]` 类型。筛选语法使用Meilisearch规则，例如 `"rating > 4 AND product_type = physical"` 。
CRITICAL（严重）	混淆 `Product` 和 `Item` 类型	`listProducts()` 返回 `Product[]` （分组结构，包含变体数组）。 `listSkus()` 和 `searchProducts()` 返回 `Item[]` （扁平结构，每个变体对应一条独立记录）。
HIGH（高优先级）	忽略 `has_variant` 标识	在尝试访问变体数据前，必须先检查 `has_variant` 的值。
HIGH（高优先级）	将商品而非变体加入购物车	当 `has_variant: true` 时，必须添加指定的变体，而非商品本身。
MEDIUM（中优先级）	URL未使用 `slug`	使用 `slug` 字段生成对SEO友好的URL， `product_id_or_slug` 参数同时支持ID和slug。
MEDIUM（中优先级）	缺少分页处理	所有列表接口都会返回 `pagination` 信息，请使用 `page` 和 `limit` 参数进行分页。
LOW（低优先级）	重复请求分类数据	分类数据很少变动，可在客户端缓存。

Documentation

文档资源

Catalog Guide: https://www.commercengine.io/docs/storefront/catalog
API Reference: https://www.commercengine.io/docs/api-reference/catalog
LLM Reference: https://llm-docs.commercengine.io/storefront/operations/list-products

商品目录指南: https://www.commercengine.io/docs/storefront/catalog
API 参考文档: https://www.commercengine.io/docs/api-reference/catalog
LLM 参考文档: https://llm-docs.commercengine.io/storefront/operations/list-products

ce-catalog

Original

Translation

Products & Catalog

商品与目录

Quick Reference

快速参考

Product Hierarchy

商品层级

Decision Tree

决策树

Key Patterns

核心使用模式

Product Listing Page (PLP)

商品列表页（PLP）

Product Detail Page (PDP)

商品详情页（PDP）

Product Types

商品类型

Inventory & Availability

库存与可售状态

Customer Groups & Pricing

客户分组与定价

Wishlists

愿望清单

Common Pitfalls

常见误区

See Also

相关参考

Documentation

文档资源