orcaqubits/shopify-catalog

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

# 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

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.