# Shopify Admin Agentic Product Jsonld Backfill

> Backfill the structured product/variant fields that power Product JSON-LD — barcode (GTIN), SKU, vendor, product type, weight — so AI agents can quote exact, in-stock items instead of guessing.

- **Type:** Skill
- **Install:** `agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-agentic-product-jsonld-backfill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [40RTY-ai](https://agentstack.voostack.com/s/40rty-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [40RTY-ai](https://github.com/40RTY-ai)
- **Source:** https://github.com/40RTY-ai/shopify-admin-skills/tree/main/skills/agentic/shopify-admin-agentic-product-jsonld-backfill
- **Website:** http://skills.40rty.ai

## Install

```sh
agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-agentic-product-jsonld-backfill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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 |
|-----------|------|----------|---------|-------------|
| collection_id | string | no | — | Limit to a collection GID (else whole catalog) |
| tag | string | no | — | Limit to a product tag |
| set_vendor | string | no | — | Vendor to apply where missing (else only reports) |
| set_product_type | 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.

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

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

4. **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

```graphql
# 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 }
  }
}
```

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

```graphql
# 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:
```json
{
  "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](https://github.com/40RTY-ai)
- **Source:** [40RTY-ai/shopify-admin-skills](https://github.com/40RTY-ai/shopify-admin-skills)
- **License:** MIT
- **Homepage:** http://skills.40rty.ai

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-40rty-ai-shopify-admin-skills-shopify-admin-agentic-product-jsonld-backfill
- Seller: https://agentstack.voostack.com/s/40rty-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.