Back to Details

commercetools-commerce-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workflow

工作流程

When this skill is invoked, always follow these steps:
  1. <!-- ct:docs-search:begin -->
    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.
    <!-- ct:docs-search:end -->
  2. Combine with skill references — Cross-reference the analysis output with local references in 
    ./references/
    for complete context.
  3. Provide implementation guidance — Synthesize the documentation with the specific integration mode the user is targeting.
当调用此 skill 时，始终遵循以下步骤：
  1. <!-- ct:docs-search:begin -->
    文档搜索（必需，首先运行）——在一个会话中首次使用此 skill 时，必须在回答前运行此操作。它会将最新且经过验证的文档作为主要依据，并根据此 skill 覆盖的产品进行过滤。处理此 skill 时，使用此脚本进行文档搜索；其余所有内容由 Knowledge MCP 处理。务必对照检索到的文档核实细节，而非仅依赖 skill 文本：
    bash
    node "<此 skill 的目录>/scripts/docs-search.mjs" \
  --query "<从用户问题中提取关键术语>" \
  --app-name "<宿主应用：claude-code、claude-chat、cursor、codex、copilot，或宿主自身的名称>" \
  --model "<当前模型>" \
  --commercetools-project-key "<如果已知>" \
  --commercetools-region "<如果已知>" \
  --limit 10
    仅当上下文中已有 commercetools project key 和 region（格式为 
    api.{region}.commercetools.com
    ）时才传入这两项，否则应将其省略。切勿搜索文件或向用户询问这些信息。
    <!-- ct:docs-search:end -->
  2. 结合 skill 参考资料——将分析输出与 
    ./references/
    中的本地参考资料交叉核对，以获得完整的上下文。
  3. 提供实现指导——将文档与用户所面向的具体集成模式结合起来综合分析。

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 查询或 mutation 的上下文时运行此脚本，例如在编写查询前检查某个资源的字段、类型和可用操作，或根据真实 schema 验证刚生成的 GraphQL 查询或 mutation。它会获取单个 commercetools 资源的部分 GraphQL SDL：
bash
node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools 资源，例如 Cart、Product、Order>" \
  --app-name "<宿主应用：claude-code、claude-chat、cursor、codex、copilot，或宿主自身的名称>" \
  --model "<当前模型>"
输出结果是该资源的 GraphQL SDL。如果无法识别资源名称，脚本会打印有效资源名称列表——请选择正确的名称并重新运行。**注意：**SDL 中可能包含 stub 类型——被引用的资源会呈现为 stub，其真实类型名称会在注释中给出。使用 
--resource-name
重新运行脚本，以单独获取所需类型。
获取 OpenAPI（REST）schema——当需要了解 commercetools REST 端点、请求/响应负载或更新 action 的上下文时运行此脚本，例如在构建请求前检查某个资源的 REST 操作，或根据真实规范验证刚生成的 REST 请求或负载。它会获取单个 commercetools 资源的部分 OpenAPI 规范：
bash
node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools 资源，例如 api-Cart-write、api-Customer-read、checkout-Application>" \
  --app-name "<宿主应用：claude-code、claude-chat、cursor、codex、copilot，或宿主自身的名称>" \
  --model "<当前模型>"
输出结果是该资源的 OpenAPI 规范（YAML）。REST 资源使用读写分离的命名形式，例如 
api-Cart-read
、
api-Cart-write
。如果无法识别资源名称，脚本会打印有效资源名称列表——请选择正确的名称并重新运行。**注意：**该规范不包含引用展开 schema——请使用该资源作为 
--resource-name
重新运行脚本，以单独获取被引用资源的 schema。

Key Takeaways

核心要点

Discount stacking follows a strict priority chain. Product Discounts → Cart Discounts → Discount Codes → Direct Discounts. Direct Discounts on a cart block all Discount Codes. Never mix Direct Discounts and Discount Code flows on the same cart.
sortOrder direction: higher value fires first. For both Product Discounts and Cart Discounts, the discount with the highest 
sortOrder
value (closest to 1) is applied first. 
0.9
fires before 
0.5
. For Product Discounts only one applies (no stacking); for Cart Discounts they stack by default unless 
stackingMode: StopAfterThisDiscount
is set.
Product Discounts cannot be used with external pricing. If a project uses an external price source, Product Discounts are not applied. Use Cart Discounts for any promotional discounts when external pricing is active.
Discount Groups bundle multiple cart discounts under one entity. A Discount Group has its own 
sortOrder
and a 
"Best deal"
prioritization mode — only the cart discount from the group that gives the customer the greatest saving is applied. Use Discount Groups to manage large-scale campaigns (e.g., Black Friday) where deactivating dozens of individual discounts at once would otherwise be error-prone.
Customer Group pricing is set on embedded prices, not at the customer level. A buyer's Customer Groups are resolved at cart calculation time — the price with a matching 
customerGroup
on the variant is selected. A Customer can carry multiple Customer Groups (via 
customerGroupAssignments
, up to 500), and price resolution selects the best qualifying price across all assigned groups. For B2B buyers, assign Customer Groups directly to the buyer's customer record or via the Business Unit.
Cart Score is the key to dynamic shipping rates. Set the project's shipping rate input type to "Cart Score" in Merchant Center. Call 
setShippingRateInput
with a 
Score
type and an integer score. CT will look up the rate tier matching that score. The score must be a non-negative integer.
Cart Score is not available in shipping predicates — copy it to a cart custom field. The 
score
is not directly queryable in predicates. Write the underlying value (e.g., distance in km) to a cart custom field. Write your shipping predicate against that custom field.
Price functions turn cart score into a continuous rate. Configure a 
priceFunction
(e.g., 
(x / 30)
) where 
x
is the cart score. CT evaluates the function and sets the resulting amount as the shipping price, enabling rates that scale smoothly without enumerating every possible value.
Use 
taxMode: ExternalAmount
for most PSP/tax service integrations. This mode lets your tax service calculate the exact tax amount per line item and pass it directly to CT, eliminating rounding discrepancies between CT's engine and external tax services (AvaTax, Vertex).
CT records payment state; the PSP does the actual financial transaction. The Payment object is a ledger. Use 
addTransaction
update actions to track each PSP event (Authorization, Charge, Refund, Chargeback). Only set 
state: "Success"
after confirmed PSP confirmation.
interfaceId
on a Payment is immutable once set. This field links CT Payment to the PSP's identifier. Record it correctly the first time — there is no update path.
Cart prices are snapshotted at order creation. If a product price changes between cart creation and order creation, the cart holds the old price. Use the 
recalculate
action on the cart to refresh prices before checkout.
Business Units are the core B2B entity — all B2B operations run through them. All B2B operations use the 
as-associate
API chain (construction and scope in references/as-associate-api.md). Never use project-level cart/order APIs for B2B user-facing operations.
The quote lifecycle has four entities: QuoteRequest → StagedQuote → Quote → Order. A buyer creates a 
QuoteRequest
; a sales rep creates a 
StagedQuote
(working draft with negotiated prices); the 
Quote
is the finalized offer; if accepted, the buyer converts it to an Order. Each step has its own state machine.
POST /orders
vs 
POST /recurring-orders
produce fundamentally different results. Calling 
POST /orders
on a cart with recurring line items creates both a regular order (immediate) and a recurring order. Calling 
POST /recurring-orders
creates only the recurring order. Use 
/orders
for "subscribe and ship now" flow; use 
/recurring-orders
for future-dated subscriptions.
Cart discount 
recurringOrderScope
controls whether a discount repeats. Set 
"NonRecurringOrdersOnly"
for one-time welcome promotions. Set 
"AnyOrder"
for standing loyalty discounts that should apply on every recurrence cycle.
折扣叠加遵循严格的优先级链。 Product Discounts → Cart Discounts → Discount Codes → Direct Discounts。购物车上的 Direct Discounts 会阻止所有 Discount Codes。切勿在同一购物车中混用 Direct Discounts 和 Discount Code 流程。
**sortOrder 方向：数值越高，越先触发。**对于 Product Discounts 和 Cart Discounts，
sortOrder
值最高（最接近 1）的折扣会先应用。
0.9
会先于 
0.5
触发。对于 Product Discounts，只会应用一个折扣（不叠加）；对于 Cart Discounts，默认会叠加，除非设置 
stackingMode: StopAfterThisDiscount
。
**Product Discounts 无法与外部定价一起使用。**如果项目使用外部价格源，则不会应用 Product Discounts。启用外部定价时，应使用 Cart Discounts 作为所有促销折扣。
**Discount Groups 将多个购物车折扣捆绑到一个实体下。**Discount Group 有自己的 
sortOrder
和 "Best deal" 优先模式——只应用该组中能为客户带来最大优惠的购物车折扣。Discount Groups 适用于 Black Friday 等大规模营销活动；在这种场景中，逐个停用数十个独立折扣很容易出错。
**Customer Group 定价设置在嵌入式价格上，而不是客户层级。**买家的 Customer Groups 会在计算购物车时解析——系统会选择商品变体上带有匹配 
customerGroup
的价格。一个 Customer 可以拥有多个 Customer Groups（通过 
customerGroupAssignments
，最多 500 个），价格解析会从所有已分配组中选择最符合条件的最佳价格。对于 B2B 买家，可将 Customer Groups 直接分配给买家的 Customer 记录，或通过 Business Unit 分配。
**Cart Score 是动态配送费率的关键。**在 Merchant Center 中，将项目的配送费率输入类型设置为 "Cart Score"。使用 
Score
类型和整数 score 调用 
setShippingRateInput
。CT 会查找与该 score 匹配的费率档位。score 必须是非负整数。
Cart Score 无法在配送谓词中使用——请将其复制到购物车自定义字段。
score
不能直接在谓词中查询。将底层值（例如以 km 为单位的距离）写入购物车自定义字段，再基于该自定义字段编写配送谓词。
**Price functions 可将购物车 score 转换为连续费率。**配置 
priceFunction
（例如 
(x / 30)
），其中 
x
为购物车 score。CT 会计算该函数，并将结果金额设置为配送价格，从而实现平滑变化的费率，而无需枚举每个可能的值。
**大多数 PSP/税务服务集成应使用 
taxMode: ExternalAmount
。**此模式允许税务服务计算每个 line item 的精确税额，并将其直接传递给 CT，从而消除 CT 引擎与外部税务服务（AvaTax、Vertex）之间的舍入差异。
**CT 记录支付状态；实际金融交易由 PSP 执行。**Payment 对象是一份账本。使用 
addTransaction
更新 action 跟踪每个 PSP 事件（Authorization、Charge、Refund、Chargeback）。只有在收到 PSP 明确确认后，才能设置 
state: "Success"
。
**Payment 上的 
interfaceId
一旦设置便不可更改。**该字段用于将 CT Payment 关联到 PSP 的标识符。首次写入时必须正确记录，因为不存在更新路径。
**购物车价格会在创建订单时生成快照。**如果商品价格在创建购物车与创建订单之间发生变化，购物车会保留旧价格。结账前应使用购物车上的 
recalculate
action 刷新价格。
**Business Unit 是 B2B 的核心实体——所有 B2B 操作都通过其执行。**所有 B2B 操作都使用 
as-associate
API 链（构建方式和作用域请参阅 references/as-associate-api.md）。面向 B2B 用户的操作绝不能使用项目级购物车/订单 API。
**报价生命周期包含四个实体：QuoteRequest → StagedQuote → Quote → Order。**买家创建 
QuoteRequest
；销售代表创建 
StagedQuote
（包含协商价格的工作草稿）；
Quote
是最终报价；如果买家接受，则将其转换为 Order。每个步骤都有自己的状态机。
**
POST /orders
与 
POST /recurring-orders
会产生根本不同的结果。**对包含 recurring line items 的购物车调用 
POST /orders
，会同时创建一个常规订单（即时创建）和一个 recurring order。调用 
POST /recurring-orders
则只创建 recurring order。
/orders
适用于“订阅并立即发货”流程；
/recurring-orders
适用于未来日期开始的订阅。
**购物车折扣的 
recurringOrderScope
控制折扣是否重复应用。**对于一次性欢迎促销，设置 
"NonRecurringOrdersOnly"
。对于应在每个续订周期都适用的长期忠诚度折扣，设置 
"AnyOrder"
。

Reference Index

参考索引

Pricing & Promotions

定价与促销

TopicReference
Discount stacking rules, sortOrder, Direct Discount blocking Discount Codesreferences/discount-fundamentals.md
Buy/Get cart discount — triggerPattern, targetPattern, excludeCountreferences/bundle-discounting.md
Cart discount scenario cookbook — 12 named scenarios with full JSONreferences/cart-discount-scenarios.md
Fixed-price combo discount — buy N of X+Y at fixed combined pricereferences/fixed-price-combo.md
"Any N of a set for one fixed total price" (no trigger item), and per-cart firing caps via 
maxOccurrence
references/cart-discount-scenarios.md
Customer Group-based pricing — embedded price selection, group assignmentreferences/customer-group-pricing.md
B2B customer group pricing — buyer-specific pricing via Customer Groupsreferences/b2b-customer-group-pricing.md
High Precision Money — fractionDigits, currency configuration, roundingreferences/high-precision-money.md
Discount Groups and Promotion Prioritization — best-deal selectionreferences/discount-groups.md
Store credit & loyalty currency — external ledger patternreferences/store-credit.md
Limited-time pricing — validFrom/validUntil on embedded pricesreferences/limited-time-pricing.md
Discount code usage — code generation, redemption limitsreferences/discount-code-usage.md
主题参考资料
折扣叠加规则、sortOrder、Direct Discount 阻止 Discount Codesreferences/discount-fundamentals.md
Buy/Get 购物车折扣——triggerPattern、targetPattern、excludeCountreferences/bundle-discounting.md
购物车折扣场景手册——12 个具名场景及完整 JSONreferences/cart-discount-scenarios.md
固定价格组合折扣——以固定组合价购买 N 件 X+Yreferences/fixed-price-combo.md
"从一组商品中任选 N 件并按一个固定总价结算"（无 trigger item），以及每个购物车的触发次数上限 
maxOccurrence
references/cart-discount-scenarios.md
基于 Customer Group 的定价——嵌入式价格选择、组分配references/customer-group-pricing.md
B2B Customer Group 定价——通过 Customer Groups 实现买家专属定价references/b2b-customer-group-pricing.md
High Precision Money——fractionDigits、货币配置、舍入references/high-precision-money.md
Discount Groups 与促销优先级——最佳优惠选择references/discount-groups.md
Store credit 与忠诚度货币——外部账本模式references/store-credit.md
限时定价——嵌入式价格上的 validFrom/validUntilreferences/limited-time-pricing.md
Discount Code 使用——代码生成、兑换限制references/discount-code-usage.md

Shipping & Fulfillment

配送与履约

TopicReference
Tiered rates, cart score setup, ScoreShippingRateInputreferences/tiered-rates-cart-score.md
Shipping predicates — predicate syntax, custom field workaroundreferences/shipping-predicates.md
Price functions — priceFunction configuration, function syntaxreferences/price-functions.md
Dynamic shipping costs — external calculation, setCustomShippingMethodreferences/dynamic-shipping-costs.md
BOPIS shipping — multiple shipping methods, delivery group setupreferences/bopis-shipping.md
主题参考资料
分档费率、Cart Score 设置、ScoreShippingRateInputreferences/tiered-rates-cart-score.md
配送谓词——谓词语法、自定义字段变通方案references/shipping-predicates.md
Price functions——priceFunction 配置、函数语法references/price-functions.md
动态配送成本——外部计算、setCustomShippingMethodreferences/dynamic-shipping-costs.md
BOPIS 配送——多种配送方式、delivery group 设置references/bopis-shipping.md

Payments & Tax

支付与税务

TopicReference
Payments — Payment object model, transactions, PSP integration flowreferences/payments.md
Taxes — cart tax modes (Platform/External/ExternalAmount/Disabled)references/taxes.md
Financing & installments — BNPL integration, CT payment modelingreferences/financing-options.md
主题参考资料
支付——Payment 对象模型、transactions、PSP 集成流程references/payments.md
税务——购物车税务模式（Platform/External/ExternalAmount/Disabled）references/taxes.md
融资与分期付款——BNPL 集成、CT 支付建模references/financing-options.md

B2B Order Flows

B2B 订单流程

TopicReference
Custom Associate Roles — role definition, permission keys, assignment to BUreferences/custom-associate-roles.md
Business Unit hierarchy — parent/child BUs, inherited roles, store assignmentreferences/business-unit-hierarchy.md
Approval rules — predicate design, approval flow lifecyclereferences/approval-rules.md
Quote lifecycle — QuoteRequest, StagedQuote, Quote, Order conversionreferences/quote-lifecycle.md
as-associate API pattern — chain construction, scopereferences/as-associate-api.md
主题参考资料
Custom Associate Roles——角色定义、权限键、分配给 BUreferences/custom-associate-roles.md
Business Unit 层级——父/子 BU、继承角色、店铺分配references/business-unit-hierarchy.md
审批规则——谓词设计、审批流程生命周期references/approval-rules.md
报价生命周期——QuoteRequest、StagedQuote、Quote、Order 转换references/quote-lifecycle.md
as-associate API 模式——链构建、作用域references/as-associate-api.md

Recurring Orders

Recurring Orders

TopicReference
Recurring orders — RecurrencePolicy, priceSelectionMode, /orders vs /recurring-ordersreferences/recurring-orders.md
主题参考资料
Recurring orders——RecurrencePolicy、priceSelectionMode、/orders 与 /recurring-orders 的区别references/recurring-orders.md

Catalog & Import

商品目录与导入

TopicReference
Product data modeling — hierarchy, all 14 attribute types, Nested vs Custom Object
Bundle product modeling — ProductType design, child SKU reference, BFF orchestrationreferences/bundle-modeling.md
Import API — containers, batching, async processing, delta imports
Import API performance — 15M record pattern, container count, batch size
Item substitutes — modeling substitute/replacement productsreferences/item-substitutes.md
Inventory modeling — supply channels, inventory entries, backorder
主题参考资料
商品数据建模——层级、全部 14 种属性类型、Nested 与 Custom Object
Bundle 商品建模——ProductType 设计、子 SKU 引用、BFF 编排references/bundle-modeling.md
Import API——containers、批处理、异步处理、增量导入
Import API 性能——1500 万条记录模式、container 数量、批大小
Item substitutes——替代/替换商品建模references/item-substitutes.md
库存建模——supply channels、inventory entries、backorder

Priority Tiers

优先级层级

CRITICAL

关键

  • Direct Discounts block Discount Codes. Never add a Direct Discount to a cart if the checkout flow expects users to enter discount codes.
  • sortOrder: higher value fires first — for both Product Discounts and Cart Discounts. 
    0.9
    is applied before 
    0.5
    . This is a common misconception that causes incorrect promotion behavior.
  • Product Discounts do not work with external pricing. If the project uses an external price source, switch all promotional discounts to Cart Discounts.
  • triggerPattern SKU predicates are ANDed across entries. A single 
    CountOnLineItemUnits
    entry can only match one SKU — add separate entries per bundle component.
  • Score must be set before shipping rate lookup. 
    setShippingRateInput
    must be called before checkout and before shipping rate totals are calculated. Calling it after order creation has no effect.
  • Shipping predicate failures are silent. If a predicate syntax error exists, CT may silently return no methods or all methods. Always test predicate behavior explicitly with 
    GET /shipping-methods?cartId=<id>
    .
  • All B2B writes MUST use the 
    as-associate
    API chain.     Project-level 
    apiRoot.carts().*
    does not enforce B2B permissions. This is a security requirement, not just a convention.
  • An Associate must have 
    CreateMyCarts
    permission to add items to a cart as-associate.     Missing permissions result in a 403.
  • POST /orders
    creates both a regular order and recurring orders from a mixed cart.     Design the order confirmation flow to handle multiple order IDs.
  • A RecurrencePolicy cannot be deleted while in use. Remove all line item and cart references before attempting deletion.
  • Never set a Payment transaction to 
    Success
    before PSP confirmation.     Optimistic success marking creates reconciliation failures.
  • interfaceId
    on a Payment cannot be changed once set.     Record the PSP transaction identifier correctly on the first write.
  • Import API has no ordering guarantee. Poll the first operation's status before submitting the second.
  • productDraftImport
    is destructive.     Any field not included in the draft is deleted.
  • Version conflicts (409 ConcurrentModification) require retry with the latest version. Do NOT use the version from the failed request.
  • **Direct Discounts 会阻止 Discount Codes。**如果结账流程预期用户输入 discount codes，切勿向购物车添加 Direct Discount。
  • sortOrder
    ：数值越高，越先触发    ——对于 Product Discounts 和 Cart Discounts 均适用。
    0.9
    会先于 
    0.5
    应用。这是一个常见误解，会导致促销行为错误。
  • **Product Discounts 无法与外部定价配合使用。**如果项目使用外部价格源，应将所有促销折扣切换为 Cart Discounts。
  • **
    triggerPattern
    中的 SKU 谓词在各条目之间按 AND 组合。**单个 
    CountOnLineItemUnits
    条目只能匹配一个 SKU——应为 bundle 中的每个组件分别添加条目。
  • **必须在查找配送费率之前设置 Score。**必须在结账前以及计算配送费率总额前调用 
    setShippingRateInput
    。订单创建后再调用不会产生任何效果。
  • **配送谓词失败不会显式报错。**如果谓词存在语法错误，CT 可能静默返回无配送方式或返回所有配送方式。始终使用 
    GET /shipping-methods?cartId=<id>
    显式测试谓词行为。
  • **所有 B2B 写入都必须使用 
    as-associate
    API 链。**项目级 
    apiRoot.carts().*
    不会强制执行 B2B 权限。这是一项安全要求，而不仅仅是约定。
  • **Associate 必须拥有 
    CreateMyCarts
    权限，才能以 as-associate 身份向购物车添加商品。**缺少权限会返回 403。
  • **
    POST /orders
    会根据混合购物车同时创建常规订单和 recurring orders。**订单确认流程必须能够处理多个订单 ID。
  • **使用中的 RecurrencePolicy 无法删除。**尝试删除前，必须移除所有 line item 和购物车引用。
  • **在 PSP 确认前，绝不能将 Payment transaction 设置为 
    Success
    。**乐观地标记成功会造成对账失败。
  • **Payment 上的 
    interfaceId
    设置后无法更改。**首次写入时必须正确记录 PSP transaction identifier。
  • **Import API 不保证执行顺序。**提交第二个 operation 前，应先轮询第一个 operation 的状态。
  • **
    productDraftImport
    具有破坏性。**草稿中未包含的任何字段都会被删除。
  • **版本冲突（409 ConcurrentModification）需要使用最新版本重试。**不要使用失败请求中的版本。

HIGH

高

  • Customer Group pricing requires the customer to be logged in and have a customerGroup set. Anonymous carts get the default price.
  • HighPrecisionMoney must be consistent across all prices in a cart. Mixing centPrecision and highPrecision prices in the same cart/order causes calculation errors.
  • Discount Code 
    maxApplications
    is global across all customers.     Use 
    maxApplicationsPerCustomer
    for per-customer limits — they are separate fields.
  • Cart Score is not available in shipping predicates. Copy the distance or weight value to a cart custom field before writing predicates against it.
  • Per-warehouse predicates need the warehouse key in a cart custom field. The cart's assigned supply channel is not directly queryable in a shipping predicate.
  • StagedQuotes hold negotiated line item prices. When converting a StagedQuote to a Quote, prices from the StagedQuote are locked in.
  • Approval Rules are evaluated at Order creation, not Cart creation. Design the cart-to-order UX to set buyer expectations about the approval wait.
  • priceSelectionMode
    must be set intentionally per use case.     
    "Fixed"
    provides price guarantee; 
    "Dynamic"
    always applies current catalog pricing.
  • recurringOrderScope
    on cart discounts defaults to applying on all orders.     Explicitly set 
    "NonRecurringOrdersOnly"
    for introductory discounts.
  • Nested attributes are not searchable and cannot target discount predicates. Use flat attribute types for any attribute that must appear in search filters or predicates.
  • Batch size for Import API is max 20 operations per request. Always chunk.
  • Changing a ProductType attribute constraint after data exists requires a migration. Plan attribute constraints during initial design.
  • **Customer Group 定价要求客户已登录并设置 
    customerGroup
    。**匿名购物车会使用默认价格。
  • **HighPrecisionMoney 必须在同一购物车/订单的所有价格中保持一致。**在同一购物车/订单中混用 centPrecision 与 highPrecision 价格会导致计算错误。
  • **Discount Code 的 
    maxApplications
    对所有客户全局生效。**如需按客户限制，请使用 
    maxApplicationsPerCustomer
    ——这是两个独立字段。
  • **Cart Score 无法在配送谓词中使用。**编写谓词前，请将距离或重量值复制到购物车自定义字段。
  • **每个仓库的谓词都需要在购物车自定义字段中提供仓库 key。**购物车分配的 supply channel 无法直接在配送谓词中查询。
  • **StagedQuote 保存协商后的 line item 价格。**将 StagedQuote 转换为 Quote 时，来自 StagedQuote 的价格会被锁定。
  • **Approval Rules 在创建 Order 时评估，而不是在创建 Cart 时评估。**设计从购物车到订单的 UX 时，应让买家了解审批等待时间。
  • 必须根据用例有意识地设置 
    priceSelectionMode
    。
    "Fixed"
    提供价格保证；
    "Dynamic"
    始终应用当前商品目录价格。
  • **购物车折扣的 
    recurringOrderScope
    默认应用于所有订单。**对于 introductory discounts，应明确设置 
    "NonRecurringOrdersOnly"
    。
  • **Nested 属性不可搜索，也不能用于折扣谓词。**对于必须出现在搜索过滤器或谓词中的属性，请使用扁平属性类型。
  • **Import API 的批大小为每个请求最多 20 个 operations。**始终进行分块。
  • **数据存在后再更改 ProductType 属性约束需要执行迁移。**应在初始设计阶段规划属性约束。

MEDIUM

中

  • isActive
    on a Cart Discount is a soft toggle.     Use this for scheduled campaigns rather than creating/deleting discounts.
  • Use 
    stackingMode: StopAfterThisDiscount
     to make a specific discount exclusive. Cart discounts stack by default.
  • Price rounding is configurable via 
    priceRoundingMode
     (on Cart/Order/Quote and as a Project default). Modes: 
    HalfEven
    (banker's rounding — the default), 
    HalfUp
    , 
    HalfDown
    . Only 
    HalfDown
    rounds 
    .5
    in the customer's favor; align the mode with your ERP/tax system and budget margin accordingly for high-volume campaigns.
  • For unsupported discount scenarios, the pattern is an API Extension on cart/order that calculates and injects a Direct Discount or custom line item.
  • lineItemGrossTotal(categories.key = (...)) >= "X.XX USD"
    is the pattern for category spend thresholds.     The currency string must be included in the value.
  • Price functions are evaluated server-side at rate lookup time. Do not try to replicate the function in your frontend.
  • Quote negotiation supports multiple rounds. Track negotiation rounds via custom fields on QuoteRequest if your business requires round history.
  • Customer Group assignment on the buyer's customer record is the simplest B2B pricing pattern. All their carts inherit the group pricing automatically.
  • Order confirmation UX must handle multiple order IDs. A single cart checkout with recurring items at different frequencies produces N+1 orders.
  • Standalone prices via Import API support 
    validFrom
    /
    validUntil
     for time-limited pricing without product republication.
  • **Cart Discount 上的 
    isActive
    是软开关。**计划开展营销活动时应使用此字段，而不是创建或删除折扣。
  • **使用 
    stackingMode: StopAfterThisDiscount
    可使特定折扣具有互斥性。**Cart discounts 默认会叠加。
  • 价格舍入可通过 
    priceRoundingMode
    配置    （可设置于 Cart/Order/Quote，也可作为 Project 默认值）。模式包括：
    HalfEven
    （银行家舍入，默认值）、
    HalfUp
    、
    HalfDown
    。只有 
    HalfDown
    会将 
    .5
    向客户有利方向舍入；对于高容量营销活动，应结合 ERP/税务系统和预算利润对该模式进行统一。
  • 对于不支持的折扣场景，应使用 cart/order 上的 API Extension，由其计算并注入 Direct Discount 或自定义 line item。
  • **
    lineItemGrossTotal(categories.key = (...)) >= "X.XX USD"
    是类别消费门槛的实现模式。**值中必须包含货币字符串。
  • **Price functions 在查找费率时由服务端计算。**不要尝试在前端复制该函数。
  • **报价协商支持多个回合。**如果业务需要保留历史记录，可通过 QuoteRequest 上的自定义字段跟踪协商回合。
  • **在买家 Customer 记录上分配 Customer Group 是最简单的 B2B 定价模式。**其所有购物车都会自动继承组定价。
  • **订单确认 UX 必须处理多个订单 ID。**一次购物车结账如果包含不同频率的 recurring items，会产生 N+1 个订单。
  • 通过 Import API 创建的 Standalone prices 支持 
    validFrom
    /
    validUntil
    ，无需重新发布商品即可使用限时定价。