saleor/saleor-domain

Saleor Domain Knowledge

Overview

Saleor is a headless e-commerce platform with a GraphQL API. This skill covers the core entities you'll work with in Configurator -- what they are, how they relate, and the rules that govern them.

When to Use

• "What entities does Saleor have?"
• "How do channels, products, and variants relate?"
• "What's the difference between slug and name identifiers?"
• "What does Configurator manage vs. what's runtime only?"
• "What's a ProductType? What's a Channel?"
• When NOT designing product types -- use product-modeling instead
• When NOT writing YAML config -- use configurator-schema instead

Core Entities

Channel

Sales channels represent storefronts, marketplaces, or regions. Each has its own currency, country, product visibility, and pricing.

Product Type

Defines the structure for a group of products: which attributes are shared (product-level) and which create variants (variant-level), plus shipping and tax settings.

Product and Variant

Products are the items you sell. Each belongs to one product type and one category. Variants are the purchasable SKUs -- each with a unique SKU, specific attribute values, channel-specific pricing, and inventory tracking.

Attribute

Typed fields attached to product types. Product-level attributes (Brand, Material) are shared across variants. Variant-level attributes (Size, Color) create separate SKUs.

Category

Hierarchical product organization (tree structure). Each product belongs to one category. Used for navigation and filtering.

Collection

Curated product groupings that can span categories. A product can belong to many collections. Used for promotions and merchandising.

Warehouse

Inventory locations with stock tracking per variant. Associated with shipping zones.

Shipping Zone

Geographic shipping regions with country-based targeting and multiple shipping methods.

Entity Relationships

Channel ─────────────────────────────────────────────┐
    ├── Product Listings (visibility, pricing)       │
    ├── Variant Listings (price, availability)       │
    └── Checkout/Order settings                      │
                                                     │
ProductType ─────────────────────────────────────────┤
    ├── productAttributes ──> Attribute              │
    ├── variantAttributes ──> Attribute              │
    └── taxClass ──> TaxClass                        │
                                                     │
Product ─────────────────────────────────────────────┤
    ├── productType ──> ProductType                  │
    ├── category ──> Category                        │
    ├── collections ──> Collection[]                 │
    └── variants ──> ProductVariant[]                │
                     ├── warehouse ──> Warehouse     │
                     └── channelListings ────────────┘

Category (tree) └── subcategories ──> Category[]
ShippingZone    └── warehouses ──> Warehouse[]

Identifier Rules

Each entity is identified by either its slug or name. This is how Configurator matches your local config to remote entities.

| Entity | Identifier | Mutable? | |--------|------------|----------| | Channel, Category, Collection, Product, Warehouse, Menu, Page | slug | No -- creates new | | ProductType, PageType, Attribute, TaxClass, ShippingZone | name | No -- creates new |

Important: Changing an identifier creates a new entity and may orphan the old one. If you need to "rename" something, delete the old entity and create a new one.

Configuration vs Runtime

Configurator manages your store's structure. Some things are runtime-only:

| Configurator Manages | Runtime Only | |---------------------|--------------| | Product structure and pricing | Orders | | Categories and collections | Customers | | Attributes and channels | Checkouts | | Warehouses and shipping zones | Payments | | Tax classes | Webhooks |

Entity Relationships in config.yml

Here are practical examples showing how entities reference each other:

# A product references its type (by name), category (by slug path),
# and channels (by slug) for pricing:
products:
  - name: "Classic T-Shirt"
    slug: "classic-t-shirt"
    productType: "T-Shirt"        # -> matches productTypes[].name
    category: "clothing/t-shirts"  # -> matches category slug path
    variants:
      - sku: "TSHIRT-S-RED"
        channelListings:
          - channel: "us-store"    # -> matches channels[].slug
            price: 29.99
        stocks:
          - warehouse: "main-wh"   # -> matches warehouses[].slug
            quantity: 100

# A shipping zone references warehouses and targets countries:
shippingZones:
  - name: "US Shipping"
    countries: [US]
    warehouses:
      - "main-wh"                  # -> matches warehouses[].slug

Common Mistakes

| Mistake | Fix | |---------|-----| | Confusing slug-based vs name-based entities | Check the Identifier Rules table -- some use slug, others use name | | Changing an identifier to "rename" | This creates a duplicate. Delete old + create new instead. | | Creating products before their product type exists | Product types must be defined first. Configurator handles deploy order, but the type must be in your config. | | Not understanding channel scope | Products aren't visible until they have a channel listing. Each channel has independent pricing. | | Mixing up Categories (taxonomy) vs Collections (curation) | Categories = hierarchical, 1 per product, for navigation. Collections = flat, many per product, for merchandising. |

See Also

• For entity reference, see references/entities.md
• For relationship diagrams, see references/relationships.md
• For Storefront v26 integration, see references/storefront-v26.md

Related Skills

• configurator-schema - Config.yml structure and validation rules
• product-modeling - Product type design and attribute selection
• configurator-cli - CLI commands for deploying configurations