ce

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 内容。

Commerce Engine Skills Router

Commerce Engine 技能路由器

These skills cover B2C storefronts. B2B storefronts share ~95% of the same patterns — the main difference is customer group pricing (see

ce-catalog

§ "Customer Groups & Pricing" and

ce-setup

§ "Default Headers").

Based on what you're trying to do, here's the right skill to use:

这些技能适用于B2C 店面。B2B 店面与 B2C 有~95%的模式是共通的，核心差异在于客户群体定价规则（参考

ce-catalog

§ "客户群体与定价" 以及

ce-setup

§ "默认请求头" 部分）。

根据你要完成的任务，可选择对应的技能模块：

By Task

按任务分类

Setting up the SDK → Use

ce-setup

Framework detection and SDK install
Token storage selection
Environment variables (
```
CE_STORE_ID
```
,
```
CE_API_KEY
```
)

Authentication & login → Use

ce-auth

Anonymous auth (always required)
OTP login (email/phone/WhatsApp), password auth, token refresh
Note: If using Hosted Checkout, login is handled inside the checkout drawer. Only build custom login UI if your app needs logged-in state outside of checkout (account pages, order history, etc.)

Products & catalog → Use

ce-catalog

Products, variants, SKUs
Categories, faceted search
Reviews, recommendations

Cart & checkout → Use

ce-cart-checkout

Hosted Checkout (recommended) — pre-built, embeddable, saves 2-3 months
Custom checkout (advanced) — Cart CRUD, fulfillment, payment gateways
Coupons, loyalty points

Orders & returns → Use

ce-orders

Create orders from cart
Shipment tracking, payment status
Cancellation, returns flow

Webhooks & events → Use

ce-webhooks

14 event types (order, payment, refund, shipment)
Signature verification
Async processing patterns

Next.js patterns → Use

ce-nextjs-patterns

```
storefront()
```
universal function
```
CookieTokenStorage
```
for SSR
Server Actions, SSG, ISR

SDK 初始化设置 → 使用

ce-setup

框架检测与 SDK 安装
Token 存储方案选择
环境变量配置（
```
CE_STORE_ID
```
、
```
CE_API_KEY
```
）

身份验证与登录 → 使用

ce-auth

匿名身份验证（必选配置）
验证码登录（邮箱/手机号/WhatsApp）、密码验证、Token 刷新
注意：如果使用托管结账服务，登录逻辑会在结账弹窗内完成。仅当你的应用需要在结账流程外保留登录状态（如账户页面、订单历史等）时，才需要自定义登录 UI。

商品与类目 → 使用

ce-catalog

商品、变体、SKU 管理
类目、分面搜索
评价、商品推荐

购物车与结账 → 使用

ce-cart-checkout

托管结账（推荐）：预制可嵌入的组件，可节省2-3个月的开发时间
自定义结账（高级方案）：购物车增删改查、履约配置、支付网关对接
优惠券、积分抵扣

订单与退换货 → 使用

ce-orders

基于购物车创建订单
物流跟踪、支付状态查询
订单取消、退换货流程

Webhook 与事件 → 使用

ce-webhooks

14种事件类型（订单、支付、退款、物流）
签名校验
异步处理模式

Next.js 开发模式 → 使用

ce-nextjs-patterns

```
storefront()
```
通用函数
适配 SSR 的
```
CookieTokenStorage
```
Server Actions、SSG、ISR 相关实现

Storefront Pages

店面页面映射

Canonical pages for a CE storefront and the skills/methods each needs:

Page	Example Route	Skills	Key SDK Methods
Home	`/`	catalog	`listProducts` , `listCategories` , recommendations ( `listSimilarProducts` , etc.)
Product Listing (PLP)	`/products` , `/categories/[slug]`	catalog	`searchProducts({ query, filter, sort, facets })` for filtered/search PLPs; `listProducts` for simple grids
Product Detail (PDP)	`/products/[slug]`	catalog	`getProductDetail` , `listProductVariants` (if `has_variant` ), `listProductReviews`
Cart	Hosted Checkout drawer	cart-checkout	`useCheckout().openCart()` , `useCheckout().addToCart()`
Checkout	Hosted Checkout drawer	cart-checkout	`useCheckout().openCheckout()`
Login	`/login`	auth	`loginWithEmail` / `loginWithPhone` , `verifyOtp`
Account	`/account`	auth	`getUserDetails` , `updateUserDetails` , `changePassword`
Orders	`/account/orders`	orders	`listOrders`
Order Detail	`/account/orders/[id]`	orders	`getOrderDetails` , `listOrderShipments` , `listOrderPayments`

Cart & Checkout routes: With Hosted Checkout (recommended), cart and checkout are drawers — no dedicated pages needed. With custom checkout, add
/cart
and
/checkout
as separate pages (see
ce-cart-checkout
).

Building a new storefront? Start with
ce-setup
, then build pages in this order: Home → PLP → PDP → Cart/Checkout → Login → Account → Orders.
Converting an existing project? Follow the migration checklist below.

CE 店面的标准页面、对应路由、所需技能/核心 SDK 方法如下：

页面	示例路由	所需技能	核心 SDK 方法
首页	`/`	catalog	`listProducts` 、 `listCategories` 、推荐接口（ `listSimilarProducts` 等）
商品列表页（PLP）	`/products` 、 `/categories/[slug]`	catalog	带筛选/搜索的列表页用 `searchProducts({ query, filter, sort, facets })` ；简单网格列表用 `listProducts`
商品详情页（PDP）	`/products/[slug]`	catalog	`getProductDetail` 、 `listProductVariants` （如果商品 `has_variant` 为真）、 `listProductReviews`
购物车	托管结账弹窗	cart-checkout	`useCheckout().openCart()` 、 `useCheckout().addToCart()`
结账页	托管结账弹窗	cart-checkout	`useCheckout().openCheckout()`
登录页	`/login`	auth	`loginWithEmail` / `loginWithPhone` 、 `verifyOtp`
账户中心	`/account`	auth	`getUserDetails` 、 `updateUserDetails` 、 `changePassword`
订单列表	`/account/orders`	orders	`listOrders`
订单详情	`/account/orders/[id]`	orders	`getOrderDetails` 、 `listOrderShipments` 、 `listOrderPayments`

购物车与结账路由说明：使用推荐的托管结账方案时，购物车和结账都是弹窗形式，不需要单独配置页面。如果使用自定义结账方案，需要新增
/cart
和
/checkout
独立页面（参考
ce-cart-checkout
文档）。

从零搭建新店面？ 先从
ce-setup
开始，然后按以下顺序开发页面：首页 → 商品列表页 → 商品详情页 → 购物车/结账 → 登录 → 账户中心 → 订单模块。
迁移现有项目？ 参考下方的迁移检查清单。

Converting an Existing Project

现有项目迁移指南

Step-by-step for replacing an existing backend (or mock data) with Commerce Engine:

Install SDK — Follow
```
ce-setup
```
. Detect framework, install packages, set env vars, choose token storage.
Add anonymous auth — Call
```
sdk.auth.getAnonymousToken()
```
at app startup. Every visitor needs this before any API call works.
Replace catalog data — Swap mock/existing product data with
```
sdk.catalog.*
```
calls. Start here because catalog is read-only and low-risk.
- Product lists →
```
searchProducts
```
  or
```
listProducts
```
- Product detail →
```
getProductDetail
```
  +
```
listProductVariants
```
- Categories →
```
listCategories
```
Add auth — Replace existing login with CE auth (
```
ce-auth
```
). Use
```
loginWithEmail
```
/
```
loginWithPhone
```
+
```
verifyOtp
```
.
Add cart + checkout — Install Hosted Checkout (
```
ce-cart-checkout
```
). Replace existing cart UI with
```
useCheckout()
```
hooks. Wire
```
authMode: "provided"
```
with two-way token sync.
Add orders — Replace order history with
```
listOrders
```
/
```
getOrderDetails
```
(
```
ce-orders
```
).
Add SEO metadata — Map CE product fields to meta tags (
```
ce-nextjs-patterns
```
§ "SEO Metadata" for Next.js).

Key principle: Replace one data source at a time. Keep existing UI components — only swap the data layer underneath.

将现有后端（或模拟数据）替换为 Commerce Engine 的分步操作：

安装 SDK — 参考
```
ce-setup
```
文档，检测项目框架、安装依赖包、配置环境变量、选择 Token 存储方案。
添加匿名身份验证 — 应用启动时调用
```
sdk.auth.getAnonymousToken()
```
，所有访客在调用任何API前都需要先获取该Token。
替换类目数据 — 将模拟/原有商品数据替换为
```
sdk.catalog.*
```
接口调用。建议从该模块开始，因为类目模块是只读的，风险最低。
- 商品列表 →
```
searchProducts
```
  或
```
listProducts
```
- 商品详情 →
```
getProductDetail
```
  +
```
listProductVariants
```
- 类目列表 →
```
listCategories
```
接入身份验证 — 将现有登录逻辑替换为 CE 提供的认证能力（
```
ce-auth
```
），使用
```
loginWithEmail
```
/
```
loginWithPhone
```
+
```
verifyOtp
```
实现。
接入购物车+结账 — 安装托管结账能力（
```
ce-cart-checkout
```
），用
```
useCheckout()
```
钩子替换原有购物车UI，配置
```
authMode: "provided"
```
实现双向Token同步。
接入订单模块 — 用
```
listOrders
```
/
```
getOrderDetails
```
替换原有订单历史逻辑（
```
ce-orders
```
）。
添加SEO元数据 — 将CE的商品字段映射到页面meta标签（Next.js项目可参考
```
ce-nextjs-patterns
```
§ "SEO元数据" 部分）。

核心原则：每次只替换一个数据源，保留现有UI组件，仅替换下层的数据层逻辑即可。

Decision Tree

决策树

User Request
    │
    ├─ "Set up SDK" / "Add Commerce Engine"  → ce-setup
    ├─ "Login" / "Auth" / "OTP"              → ce-auth
    ├─ "Products" / "Categories" / "Search"  → ce-catalog
    ├─ "Cart" / "Checkout" / "Payments"      → ce-cart-checkout
    ├─ "Orders" / "Returns" / "Shipments"    → ce-orders
    ├─ "Webhooks" / "Events" / "Sync"        → ce-webhooks
    └─ "Next.js" / "SSR" / "Server Actions"  → ce-nextjs-patterns

User Request
    │
    ├─ "Set up SDK" / "Add Commerce Engine"  → ce-setup
    ├─ "Login" / "Auth" / "OTP"              → ce-auth
    ├─ "Products" / "Categories" / "Search"  → ce-catalog
    ├─ "Cart" / "Checkout" / "Payments"      → ce-cart-checkout
    ├─ "Orders" / "Returns" / "Shipments"    → ce-orders
    ├─ "Webhooks" / "Events" / "Sync"        → ce-webhooks
    └─ "Next.js" / "SSR" / "Server Actions"  → ce-nextjs-patterns

Quick Navigation

快速导航

If you know your task, you can directly access:

```
/ce-setup
```
- SDK setup & framework detection
```
/ce-auth
```
- Authentication & user management
```
/ce-catalog
```
- Products & categories
```
/ce-cart-checkout
```
- Cart, checkout & payments
```
/ce-orders
```
- Order management
```
/ce-webhooks
```
- Webhook events & syncing
```
/ce-nextjs-patterns
```
- Next.js patterns

Or describe what you need and I'll recommend the right one.

如果你明确自己的任务，可以直接访问对应模块：

```
/ce-setup
```
- SDK 初始化与框架检测
```
/ce-auth
```
- 身份验证与用户管理
```
/ce-catalog
```
- 商品与类目管理
```
/ce-cart-checkout
```
- 购物车、结账与支付
```
/ce-orders
```
- 订单管理
```
/ce-webhooks
```
- Webhook 事件与同步
```
/ce-nextjs-patterns
```
- Next.js 开发模式

或者描述你的需求，我会为你推荐合适的模块。