commercetools-platform

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

commercetools TypeScript SDK

Foundational patterns for connecting to the commercetools API from TypeScript. These patterns are project-type agnostic — they apply whether you are building a Next.js storefront, a serverless function, or a CLI script.

使用 TypeScript 连接 commercetools API 的基础模式。这些模式与项目类型无关——无论你正在构建 Next.js storefront、serverless function，还是 CLI script，都适用。

Workflow

工作流

When this skill is invoked, always follow these steps:

Docs search (required, run first) — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:
bash
```
node "<this skill's directory>/scripts/docs-search.mjs" \
  --query "<extract key terms from user's question>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>" \
  --commercetools-project-key "<if known>" \
  --commercetools-region "<if known>" \
  --limit 10
```
Pass the commercetools project key and region (as in
```
api.{region}.commercetools.com
```
) only if already in your context; otherwise omit both. Never search files or ask the user for them.
Combine with skill references — Cross-reference the analysis output with local references in
```
./references/
```
for complete context.
Provide implementation guidance — Synthesize the documentation with the specific integration mode the user is targeting.

调用此 skill 时，始终遵循以下步骤：

文档搜索（必需，首先运行）——在一次会话中首次使用此 skill 时，必须在回答前运行此步骤。它会收集最新且经过验证的文档，作为主要依据，并按此 skill 涵盖的产品进行筛选。处理此 skill 时，使用此脚本进行文档搜索；其他内容由 Knowledge MCP 覆盖。始终根据检索到的文档确认细节，而不是仅依赖 skill 文本：
bash
```
node "<this skill's directory>/scripts/docs-search.mjs" \
  --query "<extract key terms from user's question>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>" \
  --commercetools-project-key "<if known>" \
  --commercetools-region "<if known>" \
  --limit 10
```
仅当上下文中已有 commercetools project key 和 region（采用
```
api.{region}.commercetools.com
```
格式）时才传入；否则省略这两项。不要搜索文件，也不要向用户询问这些信息。
结合 skill 引用资料——将分析输出与
```
./references/
```
中的本地引用资料交叉核对，以获取完整上下文。
提供实现指导——结合文档与用户目标的具体集成模式进行综合分析。

Optional scripts

可选脚本

Fetch GraphQL schema — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:

bash

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. Note: the SDL may contain stubbed types — referenced resources rendered as stubs, with their real type name given in a comment. Fetch any you need separately by re-running this script with that type name as

--resource-name

Fetch OpenAPI (REST) schema — Run this when you need context about a commercetools REST endpoint, request/response payload, or update action — for example, to inspect a resource's REST operations before constructing a request, or to verify a REST request/payload you have just generated against the real specification. It fetches the partial OpenAPI specification for a single commercetools resource:

bash

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

The output is the OpenAPI specification (YAML) for that resource. REST resources use a read/write-split naming form (e.g.

api-Cart-read

api-Cart-write

). If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. Note: the spec does not include reference-expansion schemas — fetch a referenced resource's schema separately by re-running this script with that resource as

--resource-name

获取 GraphQL schema——当需要了解 commercetools GraphQL query 或 mutation 的上下文时运行此脚本，例如在编写 query 前检查资源的字段、类型和可用操作，或根据真实 schema 验证刚生成的 GraphQL query/mutation。它会获取单个 commercetools 资源的部分 GraphQL SDL：

bash

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出结果为该资源的 GraphQL SDL。如果无法识别资源名称，脚本会打印有效资源名称列表——选择正确名称后重新运行。注意： SDL 中可能包含桩类型——被引用资源会以桩的形式呈现，并在注释中提供其真实类型名称。使用

--resource-name

重新运行脚本，单独获取所需的其他类型。

获取 OpenAPI（REST）schema——当需要了解 commercetools REST endpoint、请求/响应 payload 或 update action 的上下文时运行此脚本，例如在构建请求前检查资源的 REST 操作，或根据真实规范验证刚生成的 REST 请求/payload。它会获取单个 commercetools 资源的部分 OpenAPI 规范：

bash

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

输出结果为该资源的 OpenAPI 规范（YAML）。REST 资源使用读/写分离的命名形式（例如

api-Cart-read

、

api-Cart-write

）。如果无法识别资源名称，脚本会打印有效资源名称列表——选择正确名称后重新运行。注意： 该规范不包含引用展开 schema——使用

--resource-name

重新运行脚本，单独获取被引用资源的 schema。

SDK Setup

SDK 配置

See sdk-setup.md for:

Package installation (

@commercetools/platform-sdk

@commercetools/ts-client

)

```
ClientBuilder
```
singleton with Client Credentials flow
Required environment variables and auth URLs by region
Required API client scopes

有关以下内容，请参阅 sdk-setup.md：

软件包安装（

@commercetools/platform-sdk

@commercetools/ts-client

）

使用 Client Credentials 流程的
```
ClientBuilder
```
singleton
各 region 所需的环境变量和身份验证 URL
必需的 API client scopes

Product Search API

See product-search.md for:

Official docs and why the legacy
```
productProjections
```
search is deprecated
Full-text + filter + sort + facets example
Category filter, SKU lookup, price selection, discount expansion, BOPIS channel filtering

有关以下内容，请参阅 product-search.md：

官方文档，以及弃用旧版
```
productProjections
```
搜索的原因
全文搜索 + 过滤 + 排序 + 分面示例
Category 过滤、SKU 查询、价格选择、discount 展开及 BOPIS channel 过滤