commercetools API Development
Progressive loading — only load what you need:
- Setting up the SDK or client? Load
references/sdk-setup.md - Building cart or checkout? Load
references/cart-checkout.md - Working with orders? Load
references/order-management.md - Managing customers? Load
references/customer-management.md - Setting up extensions or subscriptions? Load
references/extensions-subscriptions.md - Implementing discounts? Load
references/promotions-pricing.md - Building B2B features? Load
references/b2b-patterns.md - Implementing search? Load
references/search-discovery.md - Optimizing performance? Load
references/performance.md - Code review or debugging? Load
references/anti-patterns.md
MUST load the relevant reference file before writing commercetools API code. For SDK client setup, always start with references/sdk-setup.md.
CRITICAL Priority
| Pattern | File | Impact |
|---|---|---|
| Optimistic concurrency & version handling | references/sdk-setup.md | Every update/delete fails without correct version tracking |
| Cart lifecycle & freeze before payment | references/cart-checkout.md | Price changes during checkout cause order failures |
| Payment flow — never reuse/delete Payments | references/cart-checkout.md | Lost audit trail, double charges, PSP inconsistencies |
| Extension timeout constraints (2s / 10s) | references/extensions-subscriptions.md | Entire API call fails on timeout — affects all clients |
| Discount stacking & sort order | references/promotions-pricing.md | Unexpected pricing, revenue loss, customer complaints |
| Direct Discounts block Discount Codes | references/promotions-pricing.md | Codes silently stop working when Direct Discounts exist |
HIGH Priority
| Pattern | File | Impact |
|---|---|---|
| Client setup & auth flows | references/sdk-setup.md | Wrong setup causes auth failures and token leaks |
| Order state machines & returns | references/order-management.md | Invalid state transitions, incomplete fulfillment |
| Customer auth & email verification | references/customer-management.md | Broken sign-up/login, unverified accounts |
| Subscription idempotency & ordering | references/extensions-subscriptions.md | Duplicate side effects, stale data overwrites |
| Business unit hierarchies & permissions | references/b2b-patterns.md | Security gaps, broken approval workflows |
| Product Search API vs Query API | references/search-discovery.md | 10-100x slower queries on large catalogs |
| N+1 queries & reference expansion | references/performance.md | Cascading latency on listing pages |
MEDIUM Priority
| Pattern | File | Impact |
|---|---|---|
| Tax mode configuration | references/cart-checkout.md | Failed order creation from incomplete tax data |
| Approval rules & quote lifecycle | references/b2b-patterns.md | Blocked B2B purchasing workflows |
| Connect application patterns | references/extensions-subscriptions.md | Deployment failures, resource constraint issues |
| Pagination & query optimization | references/performance.md | Slow page loads, unnecessary API load |
| Customer groups & address management | references/customer-management.md | Wrong pricing tiers, address data issues |
| Faceting & search performance | references/search-discovery.md | Slow search responses, poor relevance |
Common Anti-Patterns (Quick Reference)
| Anti-Pattern | File | Consequence |
|---|---|---|
| Creating a client per request | references/anti-patterns.md | Memory leaks, token exhaustion |
| Not batching update actions | references/anti-patterns.md | Version conflicts under load |
| Using /products instead of /product-projections | references/anti-patterns.md | 2x response payload size |
| Polling instead of Subscriptions | references/anti-patterns.md | Wasted API quota, delayed detection |
| Ignoring ConcurrentModification errors | references/anti-patterns.md | Silent data loss, corrupt state |
| Expanding all references "just in case" | references/anti-patterns.md | Bloated responses, slow queries |
| Creating empty carts for every visitor | references/anti-patterns.md | Millions of unused cart resources |
| Not monitoring Subscription health | references/anti-patterns.md | Silent notification failures for 7 days |
MCP Complement
Use this skill to understand the *right pattern*, then use the Developer MCP to look up exact field names and schemas, and the Commerce MCP for CRUD operations.