Shopify Catalog Management
Before writing code
Fetch live docs:
- Web-search
site:shopify.dev graphql admin api product for product queries and mutations
- Web-search
site:shopify.dev metafields metaobjects for custom data APIs
- Web-search
site:shopify.dev inventory management api for inventory operations
- Fetch
https://shopify.dev/docs/api/admin-graphql and search for productCreate, metafieldsSet, bulkOperationRunQuery for current input schemas
- Web-search
site:shopify.dev product variant options 2025 for latest variant limits and option changes
Product Model
Hierarchy
Product
├── Title, description, vendor, type, tags
├── Status: ACTIVE, DRAFT, ARCHIVED
├── Options (up to 3): Size, Color, Material
├── Variants (combinations of options)
│ ├── Price, compare-at price
│ ├── SKU, barcode
│ ├── Inventory (per location)
│ └── Weight, dimensions
├── Media (images, video, 3D models)
├── Metafields (custom data)
└── Collections (many-to-many)
Options vs Variants
- Options define the axes of variation (e.g., Size, Color) — max 3 per product
- Variants are specific combinations of option values (e.g., Small/Red, Medium/Blue)
- A product with 3 sizes and 4 colors = 12 variants
- Each variant has its own price, SKU, inventory, and barcode
- Maximum 2,000 variants per product (increased from 100 in 2024 — verify current limit in live docs)
Key Mutations
| Operation |
Mutation |
Notes |
| Create product |
productCreate |
Returns product ID + userErrors |
| Update product |
productUpdate |
Partial updates supported |
| Delete product |
productDelete |
Removes all variants and media |
| Create variant |
productVariantCreate |
Specify options + price + inventory |
| Bulk update variants |
productVariantsBulkUpdate |
Up to 100 variants per call |
| Manage media |
productCreateMedia |
Images, video, 3D models |
| Set metafield |
metafieldsSet |
Works on any resource |
Fetch live docs for exact mutation input types and required fields — these evolve with each quarterly API version.
Minimal Query Pattern
# Pattern: paginated product query with cursor
# Fetch live docs for current available fields
query Products($first: Int!, $after: String) {
products(first: $first, after: $after) {
edges {
node {
id
title
handle
status
variants(first: 10) {
edges { node { id sku price } }
}
}
}
pageInfo { hasNextPage endCursor }
}
}
Collections
Two types:
- Manual collections — merchant adds products individually
- Smart collections — rule-based automatic membership (tags, price, vendor, type, etc.)
Smart collection rules support: tag, title, type, vendor, variant_price, variant_compare_at_price, variant_weight, variant_inventory, variant_title.
Metafields
Typed key-value pairs on any resource:
- Namespace + key = unique identifier (e.g.,
custom.care_instructions)
- Accessible from Liquid:
{{ product.metafields.custom.care_instructions.value }}
- Configurable for Storefront API access via metafield definition
Metafield Types
| Type |
Example Value |
Use Case |
single_line_text |
"Organic cotton" |
Short text |
multi_line_text |
"Line 1\nLine 2" |
Descriptions |
number_integer |
42 |
Counts, quantities |
number_decimal |
3.14 |
Measurements |
boolean |
true |
Flags |
date |
"2025-01-15" |
Dates |
json |
{"key": "value"} |
Structured data |
url |
"https://..." |
Links |
color |
"#FF0000" |
Colors |
file_reference |
GID |
Images, files |
product_reference |
GID |
Related products |
list.single_line_text |
["a", "b"] |
Multi-value |
Fetch live docs for the full list of metafield types — new types are added periodically (e.g., money, rating, dimension).
Metafield Pattern
# Pattern: set metafields on any resource
mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
metafieldsSet(metafields: $metafields) {
metafields { id namespace key value }
userErrors { field message }
}
}
# Fetch live docs for MetafieldsSetInput fields — ownerId, namespace, key, type, value
Metaobjects
Standalone custom content types:
- Define schema with fields and types (similar to metafield types)
- Create entries (instances) via
metaobjectCreate
- Usable in themes via section settings (dynamic sources)
- Queryable via Admin and Storefront APIs
- Use cases: size charts, FAQs, team members, custom lookbooks
Fetch live docs: Web-search site:shopify.dev metaobject definition create for schema creation and entry management.
Inventory
Multi-location inventory tracking:
inventoryAdjustQuantities — adjust stock by delta (+/-)
inventorySetQuantities — set absolute quantity
- Inventory items linked to variants (one-to-one)
- Fulfillment service integration for third-party warehouses
- Reason codes:
received, correction, shrinkage, promotion, etc.
Fetch live docs for InventoryAdjustQuantitiesInput fields — the input shape and available reason codes evolve.
Product Taxonomy
Shopify's standard product taxonomy:
- Structured category hierarchy (e.g., Apparel > Shirts > T-Shirts)
- Used for: tax calculations, product feeds, Shop app categorization
- Set via
productCategory field on products
- Recommended for all products for accurate tax and discoverability
Bulk Operations
For large catalog operations (> 250 items):
Export Pattern
bulkOperationRunQuery — submit a GraphQL query for bulk export
- Poll with
currentBulkOperation query until status is COMPLETED
- Download JSONL result from the
url field
- Each line is a JSON object (parent-child relationships via
__parentId)
Import Pattern
stagedUploadsCreate — get a presigned URL
- Upload JSONL file with product data
bulkOperationRunMutation — process the staged upload
- Poll for completion
Fetch live docs: Web-search site:shopify.dev bulk operations for current input format, JSONL structure, and polling patterns.
Best Practices
- Use GraphQL mutations (not REST) for all catalog operations
- Set metafield types explicitly — untyped metafields are deprecated
- Use bulk operations for imports/exports over 250 items
- Use smart collections for dynamic grouping
- Optimize images before upload — Shopify CDN serves them but original size affects processing
- Use product taxonomy for accurate categorization
- Store custom product data in metafields, not tags (tags are untyped strings)
- Always check
userErrors in mutation responses — 200 status does not mean success
- Use cursor pagination for product listing (not offset-based)
Fetch the Shopify product and metafield API documentation for exact mutation inputs, metafield types, and bulk operation patterns before implementing.
1---2name: shopify-catalog3description: Manage Shopify catalog — Product, Variant, and Option models, collections, metafields and metaobjects, inventory management, product taxonomy, bulk operations, and media. Use when working with Shopify product data.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/shopify-catalog7---89# Shopify Catalog Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:shopify.dev graphql admin api product` for product queries and mutations152. Web-search `site:shopify.dev metafields metaobjects` for custom data APIs163. Web-search `site:shopify.dev inventory management api` for inventory operations174. Fetch `https://shopify.dev/docs/api/admin-graphql` and search for `productCreate`, `metafieldsSet`, `bulkOperationRunQuery` for current input schemas185. Web-search `site:shopify.dev product variant options 2025` for latest variant limits and option changes1920## Product Model2122### Hierarchy2324```25Product26├── Title, description, vendor, type, tags27├── Status: ACTIVE, DRAFT, ARCHIVED28├── Options (up to 3): Size, Color, Material29├── Variants (combinations of options)30│ ├── Price, compare-at price31│ ├── SKU, barcode32│ ├── Inventory (per location)33│ └── Weight, dimensions34├── Media (images, video, 3D models)35├── Metafields (custom data)36└── Collections (many-to-many)37```3839### Options vs Variants4041- **Options** define the axes of variation (e.g., Size, Color) — max 3 per product42- **Variants** are specific combinations of option values (e.g., Small/Red, Medium/Blue)43- A product with 3 sizes and 4 colors = 12 variants44- Each variant has its own price, SKU, inventory, and barcode45- Maximum 2,000 variants per product (increased from 100 in 2024 — verify current limit in live docs)4647### Key Mutations4849| Operation | Mutation | Notes |50|-----------|----------|-------|51| Create product | `productCreate` | Returns product ID + userErrors |52| Update product | `productUpdate` | Partial updates supported |53| Delete product | `productDelete` | Removes all variants and media |54| Create variant | `productVariantCreate` | Specify options + price + inventory |55| Bulk update variants | `productVariantsBulkUpdate` | Up to 100 variants per call |56| Manage media | `productCreateMedia` | Images, video, 3D models |57| Set metafield | `metafieldsSet` | Works on any resource |5859> **Fetch live docs** for exact mutation input types and required fields — these evolve with each quarterly API version.6061### Minimal Query Pattern6263```graphql64# Pattern: paginated product query with cursor65# Fetch live docs for current available fields66query Products($first: Int!, $after: String) {67 products(first: $first, after: $after) {68 edges {69 node {70 id71 title72 handle73 status74 variants(first: 10) {75 edges { node { id sku price } }76 }77 }78 }79 pageInfo { hasNextPage endCursor }80 }81}82```8384## Collections8586Two types:87- **Manual collections** — merchant adds products individually88- **Smart collections** — rule-based automatic membership (tags, price, vendor, type, etc.)8990Smart collection rules support: `tag`, `title`, `type`, `vendor`, `variant_price`, `variant_compare_at_price`, `variant_weight`, `variant_inventory`, `variant_title`.9192## Metafields9394Typed key-value pairs on any resource:95- Namespace + key = unique identifier (e.g., `custom.care_instructions`)96- Accessible from Liquid: `{{ product.metafields.custom.care_instructions.value }}`97- Configurable for Storefront API access via metafield definition9899### Metafield Types100101| Type | Example Value | Use Case |102|------|--------------|----------|103| `single_line_text` | `"Organic cotton"` | Short text |104| `multi_line_text` | `"Line 1\nLine 2"` | Descriptions |105| `number_integer` | `42` | Counts, quantities |106| `number_decimal` | `3.14` | Measurements |107| `boolean` | `true` | Flags |108| `date` | `"2025-01-15"` | Dates |109| `json` | `{"key": "value"}` | Structured data |110| `url` | `"https://..."` | Links |111| `color` | `"#FF0000"` | Colors |112| `file_reference` | GID | Images, files |113| `product_reference` | GID | Related products |114| `list.single_line_text` | `["a", "b"]` | Multi-value |115116> **Fetch live docs** for the full list of metafield types — new types are added periodically (e.g., `money`, `rating`, `dimension`).117118### Metafield Pattern119120```graphql121# Pattern: set metafields on any resource122mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {123 metafieldsSet(metafields: $metafields) {124 metafields { id namespace key value }125 userErrors { field message }126 }127}128# Fetch live docs for MetafieldsSetInput fields — ownerId, namespace, key, type, value129```130131## Metaobjects132133Standalone custom content types:134- Define schema with fields and types (similar to metafield types)135- Create entries (instances) via `metaobjectCreate`136- Usable in themes via section settings (dynamic sources)137- Queryable via Admin and Storefront APIs138- Use cases: size charts, FAQs, team members, custom lookbooks139140> **Fetch live docs**: Web-search `site:shopify.dev metaobject definition create` for schema creation and entry management.141142## Inventory143144Multi-location inventory tracking:145- `inventoryAdjustQuantities` — adjust stock by delta (+/-)146- `inventorySetQuantities` — set absolute quantity147- Inventory items linked to variants (one-to-one)148- Fulfillment service integration for third-party warehouses149- Reason codes: `received`, `correction`, `shrinkage`, `promotion`, etc.150151> **Fetch live docs** for `InventoryAdjustQuantitiesInput` fields — the input shape and available reason codes evolve.152153## Product Taxonomy154155Shopify's standard product taxonomy:156- Structured category hierarchy (e.g., Apparel > Shirts > T-Shirts)157- Used for: tax calculations, product feeds, Shop app categorization158- Set via `productCategory` field on products159- Recommended for all products for accurate tax and discoverability160161## Bulk Operations162163For large catalog operations (> 250 items):164165### Export Pattern1661671. `bulkOperationRunQuery` — submit a GraphQL query for bulk export1682. Poll with `currentBulkOperation` query until status is `COMPLETED`1693. Download JSONL result from the `url` field1704. Each line is a JSON object (parent-child relationships via `__parentId`)171172### Import Pattern1731741. `stagedUploadsCreate` — get a presigned URL1752. Upload JSONL file with product data1763. `bulkOperationRunMutation` — process the staged upload1774. Poll for completion178179> **Fetch live docs**: Web-search `site:shopify.dev bulk operations` for current input format, JSONL structure, and polling patterns.180181## Best Practices182183- Use GraphQL mutations (not REST) for all catalog operations184- Set metafield types explicitly — untyped metafields are deprecated185- Use bulk operations for imports/exports over 250 items186- Use smart collections for dynamic grouping187- Optimize images before upload — Shopify CDN serves them but original size affects processing188- Use product taxonomy for accurate categorization189- Store custom product data in metafields, not tags (tags are untyped strings)190- Always check `userErrors` in mutation responses — 200 status does not mean success191- Use cursor pagination for product listing (not offset-based)192193Fetch the Shopify product and metafield API documentation for exact mutation inputs, metafield types, and bulk operation patterns before implementing.