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.