Saleor Catalog Management
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io products variants product types for product model and GraphQL operations
- Web-search
site:docs.saleor.io categories collections for category tree and collection management
- Web-search
site:docs.saleor.io warehouse stock allocation for inventory and warehouse operations
- Fetch
https://docs.saleor.io/developer/products/overview and review Product, ProductType, and ProductVariant schemas
- Web-search
site:docs.saleor.io product media images for media upload and assignment patterns
- Fetch
https://docs.saleor.io/developer/channels/overview 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.
1---2name: saleor-catalog-23description: Manage the Saleor catalog — products, variants, product types, categories, collections, media, and warehouse stock. Use when working with Saleor product data.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-catalog-27---89# Saleor Catalog Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io products variants product types` for product model and GraphQL operations152. Web-search `site:docs.saleor.io categories collections` for category tree and collection management163. Web-search `site:docs.saleor.io warehouse stock allocation` for inventory and warehouse operations174. Fetch `https://docs.saleor.io/developer/products/overview` and review Product, ProductType, and ProductVariant schemas185. Web-search `site:docs.saleor.io product media images` for media upload and assignment patterns196. Fetch `https://docs.saleor.io/developer/channels/overview` and review channel-aware product visibility2021## Product Hierarchy2223| Level | Contains |24|-------|----------|25| ProductType | Template: defines product and variant attributes, shipping/digital flags |26| Product | Name, description, slug, category, collections, media |27| ProductVariant | SKU, name, channel listings (price), stock (per warehouse), variant attributes |2829### Product Status3031| Status | Description |32|--------|-------------|33| `DRAFT` | Product is not visible to customers; work in progress |34| `ACTIVE` | Product is published and available for purchase (per channel listing) |3536> Products require a channel listing to be visible in a given channel. Status alone does not control storefront visibility.3738## Product Types3940A ProductType serves as a template that defines the structure for a group of products:4142| Concept | Purpose |43|---------|---------|44| Product attributes | Shared attributes across all products of this type (e.g., Brand, Material) |45| Variant attributes | Attributes that differ per variant (e.g., Size, Color) |46| `isShippingRequired` | Whether products of this type need physical shipping |47| `isDigital` | Whether this type represents digital goods |48| `hasVariants` | Whether products support multiple variants |49| Weight | Default weight for products of this type |5051### Key Product Type Mutations5253| Operation | Mutation | Notes |54|-----------|----------|-------|55| Create type | `productTypeCreate` | Define name, attributes, shipping flag |56| Update type | `productTypeUpdate` | Modify existing type settings |57| Delete type | `productTypeDelete` | Removes type (fails if products exist) |58| Assign attribute | `productAttributeAssign` | Add attribute to product type |59| Unassign attribute | `productAttributeUnassign` | Remove attribute from type |6061## Variant Model6263Each ProductVariant represents a purchasable unit within a product:6465| Field | Description |66|-------|-------------|67| `sku` | Stock Keeping Unit (unique identifier) |68| `name` | Display name for the variant |69| `trackInventory` | Whether stock levels are tracked |70| `weight` | Override weight from product type |71| `preorder` | Preorder settings (end date, global threshold) |72| `quantityLimitPerCustomer` | Maximum purchase quantity per customer |7374### Channel Listings for Variants7576Variants have per-channel pricing. Each `ProductVariantChannelListing` holds:7778| Field | Description |79|-------|-------------|80| `price` | Selling price in the channel currency |81| `costPrice` | Cost of goods (for margin calculations) |82| `channel` | The channel this listing belongs to |8384## Categories8586Categories form a nested tree structure for organizing products:8788| Feature | Detail |89|---------|--------|90| Structure | Single-root tree with unlimited nesting depth |91| Assignment | Each product belongs to exactly one category |92| SEO | Categories support `seoTitle` and `seoDescription` |93| Background image | Optional image for category pages |94| Slug | URL-friendly identifier |9596### Key Category Mutations9798| Operation | Mutation |99|-----------|----------|100| Create | `categoryCreate` (set `parent` for nesting) |101| Update | `categoryUpdate` |102| Delete | `categoryDelete` |103104## Collections105106Collections are curated groupings of products, independent of the category tree:107108| Feature | Detail |109|---------|--------|110| Purpose | Marketing-driven groupings (e.g., "Summer Sale", "Best Sellers") |111| Assignment | Many-to-many; a product can belong to multiple collections |112| Channel listing | Collections must be published per channel |113| Background image | Optional image for collection pages |114| SEO | Supports `seoTitle` and `seoDescription` |115116### Key Collection Mutations117118| Operation | Mutation |119|-----------|----------|120| Create | `collectionCreate` |121| Add products | `collectionAddProducts` |122| Remove products | `collectionRemoveProducts` |123| Delete | `collectionDelete` |124125## Product Media126127Products support images and videos:128129| Media Type | Upload Method |130|------------|---------------|131| Images | `productMediaCreate` with `image` file upload |132| URLs | `productMediaCreate` with `mediaUrl` for external images or videos |133| Reorder | `productMediaReorder` to set display order |134| Delete | `productMediaDelete` to remove media |135136> Images are served through Saleor's thumbnail system. Request specific sizes using the `thumbnail` field on `ProductMedia` with `size` parameter.137138## Key GraphQL Queries and Mutations139140### Admin API141142| Operation | Query / Mutation | Notes |143|-----------|-----------------|-------|144| List products | `products` | Supports filtering, sorting, and channel |145| Get product | `product` | By ID or slug; channel required for pricing |146| Create product | `productCreate` | Requires productType, name, and category |147| Update product | `productUpdate` | Partial updates supported |148| Delete product | `productDelete` | Removes product and all variants |149| Create variant | `productVariantCreate` | Requires product ID, attributes, SKU |150| Bulk create variants | `productVariantBulkCreate` | Create multiple variants at once |151| Update stock | `productVariantStocksUpdate` | Set stock quantities per warehouse |152153### Store API (channel-scoped)154155| Operation | Query | Notes |156|-----------|-------|-------|157| List products | `products(channel: "default")` | Only published, available products |158| Get product | `product(slug: "...", channel: "...")` | Returns pricing for the channel |159| Search | `products(filter: {search: "..."})` | Full-text search on name and description |160| By category | `products(filter: {categories: [...]})` | Filter by category IDs |161| By collection | `collection(slug: "...")` `{ products }` | Products within a collection |162163> **Fetch live docs** for exact filter fields and sorting options -- these evolve across Saleor versions.164165## Warehouse and Stock166167| Concept | Description |168|---------|-------------|169| Warehouse | Physical location where stock is held |170| Stock | Per-variant, per-warehouse quantity |171| Allocation | Reserved stock for unfulfilled orders |172| Available quantity | `stock.quantity - stock.allocations` |173174### Stock Mutations175176| Operation | Mutation |177|-----------|----------|178| Update stocks | `productVariantStocksUpdate` |179| Create stocks | `productVariantStocksCreate` |180| Delete stocks | `productVariantStocksDelete` |181182## Best Practices183184- Always create ProductTypes before products -- they define the attribute schema185- Use channel listings to control visibility and pricing per channel186- Assign products to exactly one category and use collections for cross-cutting groupings187- Use `productVariantBulkCreate` for efficiency when adding multiple variants188- Track inventory at the warehouse level for multi-location fulfillment189- Set `trackInventory` to `true` for physical goods to prevent overselling190- Use slugs for storefront URLs and SEO-friendly navigation191- Optimize images before upload -- Saleor generates thumbnails but original size affects storage192- Always pass `channel` when querying from the storefront to get correct pricing and availability193194Fetch the Saleor product and catalog documentation for exact mutation inputs, attribute types, and channel listing patterns before implementing.