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.