orcaqubits/saleor-catalog

Saleor Catalog Management

Before writing code

Fetch live docs:

1. Web-search site:docs.saleor.io products variants product types for product model and GraphQL operations
2. Web-search site:docs.saleor.io categories collections for category tree and collection management
3. Web-search site:docs.saleor.io warehouse stock allocation for inventory and warehouse operations
4. Fetch https://docs.saleor.io/docs/developer/products and review Product, ProductType, and ProductVariant schemas
5. Web-search site:docs.saleor.io product media images for media upload and assignment patterns
6. Fetch https://docs.saleor.io/docs/developer/channels and review channel-aware product visibility

Product Hierarchy

| Level | Contains | |-------|----------| | ProductType | Template: defines product and variant attributes, shipping/digital flags | | Product | Name, description, slug, category, collections, media | | ProductVariant | SKU, name, channel listings (price), stock (per warehouse), variant attributes |

Product Status

| Status | Description | |--------|-------------| | DRAFT | Product is not visible to customers; work in progress | | ACTIVE | Product is published and available for purchase (per channel listing) |

Products require a channel listing to be visible in a given channel. Status alone does not control storefront visibility.

Product Types

A ProductType serves as a template that defines the structure for a group of products:

| Concept | Purpose | |---------|---------| | Product attributes | Shared attributes across all products of this type (e.g., Brand, Material) | | Variant attributes | Attributes that differ per variant (e.g., Size, Color) | | isShippingRequired | Whether products of this type need physical shipping | | isDigital | Whether this type represents digital goods | | hasVariants | Whether products support multiple variants | | Weight | Default weight for products of this type |

Key Product Type Mutations

| Operation | Mutation | Notes | |-----------|----------|-------| | Create type | productTypeCreate | Define name, attributes, shipping flag | | Update type | productTypeUpdate | Modify existing type settings | | Delete type | productTypeDelete | Removes type (fails if products exist) | | Assign attribute | productAttributeAssign | Add attribute to product type | | Unassign attribute | productAttributeUnassign | Remove attribute from type |

Variant Model

Each ProductVariant represents a purchasable unit within a product:

| Field | Description | |-------|-------------| | sku | Stock Keeping Unit (unique identifier) | | name | Display name for the variant | | trackInventory | Whether stock levels are tracked | | weight | Override weight from product type | | preorder | Preorder settings (end date, global threshold) | | quantityLimitPerCustomer | Maximum purchase quantity per customer |

Channel Listings for Variants

Variants have per-channel pricing. Each ProductVariantChannelListing holds:

| Field | Description | |-------|-------------| | price | Selling price in the channel currency | | costPrice | Cost of goods (for margin calculations) | | channel | The channel this listing belongs to |

Categories

Categories form a nested tree structure for organizing products:

| Feature | Detail | |---------|--------| | Structure | Single-root tree with unlimited nesting depth | | Assignment | Each product belongs to exactly one category | | SEO | Categories support seoTitle and seoDescription | | Background image | Optional image for category pages | | Slug | URL-friendly identifier |

Key Category Mutations

| Operation | Mutation | |-----------|----------| | Create | categoryCreate (set parent for nesting) | | Update | categoryUpdate | | Delete | categoryDelete |

Collections

Collections are curated groupings of products, independent of the category tree:

| Feature | Detail | |---------|--------| | Purpose | Marketing-driven groupings (e.g., "Summer Sale", "Best Sellers") | | Assignment | Many-to-many; a product can belong to multiple collections | | Channel listing | Collections must be published per channel | | Background image | Optional image for collection pages | | SEO | Supports seoTitle and seoDescription |

Key Collection Mutations

| Operation | Mutation | |-----------|----------| | Create | collectionCreate | | Add products | collectionAddProducts | | Remove products | collectionRemoveProducts | | Delete | collectionDelete |

Product Media

Products support images and videos:

| Media Type | Upload Method | |------------|---------------| | Images | productMediaCreate with image file upload | | URLs | productMediaCreate with mediaUrl for external images or videos | | Reorder | productMediaReorder to set display order | | Delete | productMediaDelete to remove media |

Images are served through Saleor's thumbnail system. Request specific sizes using the thumbnail field on ProductMedia with size parameter.

Key GraphQL Queries and Mutations

Admin API

| Operation | Query / Mutation | Notes | |-----------|-----------------|-------| | List products | products | Supports filtering, sorting, and channel | | Get product | product | By ID or slug; channel required for pricing | | Create product | productCreate | Requires productType, name, and category | | Update product | productUpdate | Partial updates supported | | Delete product | productDelete | Removes product and all variants | | Create variant | productVariantCreate | Requires product ID, attributes, SKU | | Bulk create variants | productVariantBulkCreate | Create multiple variants at once | | Update stock | productVariantStocksUpdate | Set stock quantities per warehouse |

Store API (channel-scoped)

| Operation | Query | Notes | |-----------|-------|-------| | List products | products(channel: "default") | Only published, available products | | Get product | product(slug: "...", channel: "...") | Returns pricing for the channel | | Search | products(filter: {search: "..."}) | Full-text search on name and description | | By category | products(filter: {categories: [...]}) | Filter by category IDs | | By collection | collection(slug: "...") { products } | Products within a collection |

Fetch live docs for exact filter fields and sorting options -- these evolve across Saleor versions.

Warehouse and Stock

| Concept | Description | |---------|-------------| | Warehouse | Physical location where stock is held | | Stock | Per-variant, per-warehouse quantity | | Allocation | Reserved stock for unfulfilled orders | | Available quantity | stock.quantity - stock.allocations |

Stock Mutations

| Operation | Mutation | |-----------|----------| | Update stocks | productVariantStocksUpdate | | Create stocks | productVariantStocksCreate | | Delete stocks | productVariantStocksDelete |

Best Practices

• Always create ProductTypes before products -- they define the attribute schema
• Use channel listings to control visibility and pricing per channel
• Assign products to exactly one category and use collections for cross-cutting groupings
• Use productVariantBulkCreate for efficiency when adding multiple variants
• Track inventory at the warehouse level for multi-location fulfillment
• Set trackInventory to true for physical goods to prevent overselling
• Use slugs for storefront URLs and SEO-friendly navigation
• Optimize images before upload -- Saleor generates thumbnails but original size affects storage
• Always pass channel when querying from the storefront to get correct pricing and availability

Fetch the Saleor product and catalog documentation for exact mutation inputs, attribute types, and channel listing patterns before implementing.