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

```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.