Shopify Admin Agentic Product Jsonld Backfill

Purpose

AI shopping agents read a product's structured data (the fields Shopify themes emit as schema.org/Product JSON-LD) to confirm price, availability, and identity. Missing barcodes (GTIN), SKUs, vendor, or product type leave the listing ambiguous — so the agent skips it or recommends a competitor whose data is complete. This skill finds products/variants with those gaps and backfills them: vendor and product type at the product level, barcode/SKU at the variant level. Fixes the agentiq.report findings product-schema-jsonld, gtin-sku-pdp, and variant-metadata.

Prerequisites

• Authenticated Shopify CLI session (shopify auth login --store )
• Required API scopes: read_products, write_products

Parameters

All skills accept these universal parameters:

| Parameter | Type | Required | Default | Description | |-----------|--------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | format | string | no | human | Output format: human (default) or json | | dry_run | bool | no | false | Preview mutations without executing |

Skill-specific parameters:

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | collectionid | string | no | — | Limit to a collection GID (else whole catalog) | | tag | string | no | — | Limit to a product tag | | setvendor | string | no | — | Vendor to apply where missing (else only reports) | | setproducttype | string | no | — | Product type to apply where missing | | barcodes_csv | string | no | — | Path to a CSV of sku,barcode to map GTINs onto matching variants | | fields | string | no | all | Comma list of fields to backfill: vendor,product_type,barcode,sku |

Safety

> ⚠️ Step 3 (productUpdate) and Step 4 (productVariantsBulkUpdate) write live product/variant data. Barcodes and SKUs are matched from your barcodes_csv; a wrong mapping mislabels a product's identity to every agent. Always run dry_run: true first and verify the change set CSV. This skill never overwrites a field that already has a value — it only fills blanks.

Workflow Steps

1. OPERATION: products — query

Inputs: first: 250, optional query: "tag:''" or collection filter; fields vendor, productType, variants{ id sku barcode }; paginate until hasNextPage: false. Expected output: Products/variants with missing target fields.

1. COMPUTE (no API): build the change set — only blank fields, joined to barcodes_csv by SKU for barcodes. Emit the preview CSV.

1. OPERATION: productUpdate — mutation

Inputs: per product { id, vendor?, productType? } (only where blank and a value is supplied). Expected output: Updated product; collect userErrors.

1. OPERATION: productVariantsBulkUpdate — mutation

Inputs: per product productId + variants: [{ id, barcode?, inventoryItem: { sku? } }] for blank variant fields. Expected output: Updated variants; collect userErrors across batches.

GraphQL Operations

# products:query — validated against api_version 2025-01
query BackfillProducts($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        vendor
        productType
        variants(first: 100) {
          edges { node { id sku barcode } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# productUpdate:mutation — validated against api_version 2025-01
mutation BackfillProductFields($input: ProductInput!) {
  productUpdate(input: $input) {
    product { id vendor productType }
    userErrors { field message }
  }
}

# productVariantsBulkUpdate:mutation — validated against api_version 2025-01
mutation BackfillVariantFields($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    productVariants { id sku barcode }
    userErrors { field message }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL:                          ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  :   
  Errors:           0
  Output:           
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "",
  "store": "",
  "started_at": "",
  "completed_at": "",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "",
      "type": "query",
      "params_summary": "",
      "result_summary": "",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}

Output Format

human: counts of products/variants updated per field + a CSV of every change (product, variant, field, old, new). json: { products_updated, variants_updated, by_field{...}, errors, output_file }.

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit | Wait 2s, retry up to 3 times | | userErrors non-empty | Invalid barcode/SKU format or duplicate | Log message, skip that variant, continue | | SKU not in CSV | No mapping supplied for that variant | Leave barcode blank, report it as still-missing |

Best Practices

• Run shopify-admin-agentic-readiness-audit first to size the gap, then dry_run: true here to review the exact change set.
• Barcodes are GTIN/UPC/EAN — get them from your supplier, never invent them. A wrong GTIN is worse than a blank one.
• This skill only fills blanks; to correct existing-but-wrong values use shopify-admin-bulk-price-adjustment-style targeted edits instead.
• Pair with shopify-admin-agentic-metafields-setup — barcodes power JSON-LD identity, metafields power agent filtering; you usually want both.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 40RTY-ai
• Source: 40RTY-ai/shopify-admin-skills
• License: MIT
• Homepage: http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.