commercetools Data Modeling & Management
Product types are immutable once assigned to products -- getting the data model right is the single most consequential decision in any commercetools implementation.
Progressive loading — only load what you need:
- Designing product types? Load
references/product-type-design.md - Product type operations (CRUD, migration, versioning)? Load
references/product-type-operations.md - Choosing Custom Types vs Custom Objects? Load
references/custom-types-objects.md - Designing category hierarchies? Load
references/category-design.md - Setting up localization? Load
references/localization.md - Importing or exporting data? Load
references/import-export.md - Planning a migration? Load
references/migration.md - Auditing catalog completeness? Load
references/bulk-catalog-audit.md - Enriching catalog data (AI-assisted, batch updates)? Load
references/bulk-catalog-enrichment.md - Code review or debugging? Load
references/anti-patterns.md
CRITICAL Priority -- Irreversible Decisions
| Pattern | File | Impact |
|---|
| Product Type Design Principles | references/product-type-design.md | Cannot change product type on existing products. Cannot delete a type with products. Attribute removal is destructive. |
| Custom Types vs Custom Objects | references/custom-types-objects.md | Only one Custom Type per resource at a time. Field type changes silently fail. Wrong choice = data in unreachable places. |
| Category Hierarchy Design | references/category-design.md | Deep hierarchies degrade search. No automatic inheritance. Restructuring requires product reassignment. |
HIGH Priority -- Significant Rework
| Pattern | File | Impact |
|---|
| Localization Strategy | references/localization.md | Over-localizing bloats payloads. Missing fallbacks break storefronts. Wrong LocalizedString usage wastes storage. |
| Import & Export Patterns | references/import-export.md | 20-resource batch limit. Async processing with 48-hour window. Wrong import order causes unresolved references. |
| Migration Strategy | references/migration.md | Big-bang migrations fail. No built-in environment promotion. Product type changes require delete-and-recreate. |
MEDIUM Priority -- Quality & Maintainability
| Pattern | File | Impact |
|---|
| Bulk Catalog Operations | references/bulk-catalog-audit.md | Patterns for auditing catalog completeness (missing slugs, descriptions), batch updates, and AI-assisted data enrichment. |
| Anti-Patterns Catalog | references/anti-patterns.md | Comprehensive list of data modeling mistakes with consequences and corrections. |
Decision Flowcharts
"Where Should This Data Live?"
Is the data an attribute of a product variant? (color, size, weight)
YES --> Product Type attribute
NO --> Continue
Is the data extending an existing resource? (loyalty points on Customer,
gift wrap on LineItem, metadata on Order)
YES --> Custom Type (Custom Fields)
NO --> Continue
Is the data standalone reference/config? (feature flags, lookup tables,
app settings, cross-cutting data)
YES --> Custom Object (container/key)
NO --> Continue
Is the data classifying products for navigation? (department, collection)
YES --> Category
NO --> Continue
Is it a workflow state? (product review status, order fulfillment stage)
YES --> State Machine
NO --> Consider whether commercetools is the right place for this data
"Product Type or Category?"
Does it define WHAT the product IS? (its schema, its attributes)
YES --> Product Type
Does it define WHERE the product APPEARS? (navigation, browsing, collections)
YES --> Category
Rule: If you could model it as a Category, prefer Category.
Categories are flexible. Product Types are permanent.
"How Many Product Types?"
Do products share 80%+ of their attributes?
YES --> Same Product Type (use attributes for differentiation)
NO --> Different Product Types
Is data managed in Merchant Center?
YES --> Use more specific types (better editing UX)
NO (external PIM) --> Fewer generic types are acceptable
Key Platform Limits
| Resource | Limit | Notes |
|---|
| Product Types per Project | 1,000 | Hard limit |
| Attributes per Product Type | No hard limit | 50 product-level + 50 variant-level searchable attributes indexed |
| Variants per Product | 100 | Can be increased by contacting support |
| Categories per Project | 10,000 | Requires review to increase |
| Custom Objects per Project | 20,000,000 | Generous but not infinite |
| Import Containers per Project | 1,000 | Keep < 200K operations per container |
| Resources per Import Request | 20 | Hard limit, batch accordingly |
| Import Operation retention | 48 hours | Unresolved refs retry up to 5 times |
| Product Selections per Store | 100 | Plan assortment strategy carefully |
| Distribution Channels per Store | 100 | |
| Supply Channels per Store | 100 | |
MCP Complement
Use this skill to DESIGN the data model, then use the Developer MCP for schema details and the Commerce MCP to execute operations. For bulk catalog operations, see references/bulk-catalog-audit.md and references/bulk-catalog-enrichment.md.
