--- name: shopify-catalog-c82cc455208e description: > 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. --- # Shopify Catalog Management ## Before writing code **Fetch live docs**: 1. Web-search `site:shopify.dev graphql admin api product` for product queries and mutations 2. Web-search `site:shopify.dev metafields metaobjects` for custom data APIs 3. Web-search `site:shopify.dev inventory management api` for inventory operations 4. Fetch `https://shopify.dev/docs/api/admin-graphql` and search for `productCreate`, `metafieldsSet`, `bulkOperationRunQuery` for current input schemas 5. 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 ```graphql # 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 ```graphql # 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 1. `bulkOperationRunQuery` — submit a GraphQL query for bulk export 2. Poll with `currentBulkOperation` query until status is `COMPLETED` 3. Download JSONL result from the `url` field 4. Each line is a JSON object (parent-child relationships via `__parentId`) ### Import Pattern 1. `stagedUploadsCreate` — get a presigned URL 2. Upload JSONL file with product data 3. `bulkOperationRunMutation` — process the staged upload 4. 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. --- Source attribution: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/shopify-commerce/skills/shopify-catalog/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: OrcaQubits Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/shopify-commerce/skills/shopify-catalog/SKILL.md Attribution basis: Source repository record Fields of work: Marketing Roles: Content Marketer, Growth Marketer, Product Marketer, SEO Specialist Specialties: API Tools: Shopify Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 6f5ec9026d485266e98df641f6cecb0357e05750b7eb6bf93cee718c744eab76