shopify-redirect-mapping

name	shopify-redirect-mapping
description	Use when you need to map a pile of old URLs to live pages and turn them into 301 redirects on a Shopify store: fix 404s, bulk redirects after a migration/replatform/catalog restructure, turn a Google Search Console 404 export into live redirects, or WordPress→Shopify URL transforms (/YYYY/MM/slug/ → /products/slug). Trigger phrases: "map old URLs", "fix our 404s", "redirect the dead links", "we relaunched and lost our rankings". Recovers SEO equity and rescues users after a URL structure changes. Not for creating a single one-off redirect (do it in admin).
compatibility	Requires Shopify Admin API (custom-app token or Shopify CLI 3.x), GraphQL written against Admin API 2025-07, scopes read_products/read_content/ read_online_store_navigation/write_online_store_navigation. Or apply in bulk via the Matrixify Redirects sheet.

Shopify Redirect Mapping

Turn a list of 404ing URLs into live 301 redirects on a Shopify store using type-aware fuzzy matching with a manual review queue for the leftovers. The job is reclaiming search equity and rescuing lost visitors, not building a perfect 1:1 map. For bulk apply through a spreadsheet instead of the API, hand the final map to the sibling shopify-matrixify skill's Redirects sheet.

The one rule that matters: recall over precision

A wrong-but-related redirect beats a 404. A visitor who lands on a close product or the right category still converts; a visitor who hits a dead page leaves. Google keeps some of the old page's equity when the 301 points somewhere topical; it keeps none when the URL 404s. So tune for coverage, not for a flawless match, and let a human review pass catch the misfires.

Worked case (an automotive-lifestyle brand, anonymized). A first pass used a single conservative 0.92 similarity threshold across all URL types. Out of 1,010 dead URLs it produced 6 redirects: effectively nothing, and the merchant called it useless. Re-running with per-type thresholds plus cross-type fallbacks yielded 725 live redirects (~72% coverage) from the same export. The lesson is blunt: do not ship a conservative first pass. Precision-first thresholds look safe and deliver nothing.

Per-type thresholds (defaults, not suggestions)

Different URL types tolerate different looseness. Classify each dead path by its prefix, then match it only against live inventory of the same type at these cut-offs:

• Products: 0.85. Accepts some "same suffix, different product" matches (a discontinued -jacket landing on another -jacket). That is the acceptable cost of recall; the review pass pulls the ones that are genuinely wrong.
• Collections: 0.70. Most dead collection URLs are restructure churn. Any nearby collection is a better landing than the homepage.
• Blogs / pages: 0.85. Brand pages that resolve to collections: 0.70. The review queue catches the rest.

Cross-type fallback order

When a path can't clear its own-type threshold, fall down a type rather than giving up:

• Product path: product match @0.85 → fuzzy collection match @0.70 → review queue. A category page is a better landing than the homepage; a wrong product is worse than no product, so a weak product match falls through to collection rather than being forced.
• Collection path: collection match @0.70 → review queue.

Never silently fall back to / (the homepage). Homepage fallback looks like 100% coverage but destroys the one signal that tells you a URL still needs human attention, and it dilutes the redirect's topical value to nothing. A path that matches nothing goes to the review queue, not to home.

What thresholds cannot fix

Spec mismatches that are string-identical to the algorithm: a 12mm part slug is one character off a 14mm part slug, a size-S variant reads almost identical to size-XL. Fuzzy matching will confidently pick the wrong one. These get hand-pulled from the auto-apply set during review. That judgment call does not go away, and no threshold removes it.

Three-bucket output

Every matched path lands in exactly one bucket. This is what makes the pass auditable and the review scoped:

1. auto-apply: cleared its type threshold. Still eyeballed before pushing, but the default is to ship it.
2. review: low-confidence matches, media assets (.jpg, .mp4, /assets/), malformed rows, and anything that fell through to the queue. A human sets or confirms the target here.
3. skip: no-op, where the best target equals the source path. Dedupe source paths so one dead URL yields one redirect.

Review-pass budget

Expect iteration. The anonymized case above took several passes (6 → 725 redirects) as fallback stages were added and the review queue was worked down. Budget for at least 2–3 passes on a first engagement: run, review the buckets, adjust thresholds or hand-edit targets, re-run. A one-shot redirect map is a sign you tuned for precision and left coverage on the table.

Store access

This skill reads inventory and writes redirects through the Admin API. Pick one lane; never write a token to a committed file.

Lane A, custom-app token. In Shopify admin: Settings → Apps and sales channels → Develop apps → create an app → grant this skill's minimum scopes (read_products, read_content, read_online_store_navigation, write_online_store_navigation), install, and copy the Admin API access token. Keep it in the env:

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk

Lane B, Shopify CLI OAuth (no stored token). shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_content,read_online_store_navigation,write_online_store_navigation then shopify store execute to run a validated operation.

Toolkit preflight. Lane B rides on the Shopify CLI: run shopify version first and install it if missing. For the full Admin GraphQL schema and validated execution, pair this skill with Shopify's official AI toolkit plugin. In Claude Code, check claude plugin list; if it isn't there:

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

Recommended, not required: Lane A needs only curl and a token. The toolkit gives your agent the API; this skill gives it the playbook.

Preview before you mutate; stay non-destructive

• Read before you write. Pull the live inventory and the existing redirect list first. Before creating a redirect, query the existing set and skip duplicates: urlRedirectCreate will error on a source path that already redirects.
• Back up first. Export the store's current redirects (Matrixify export or a urlRedirects dump) before a large write, so the pass is reversible.
• Verify against the Admin API, not the storefront. The storefront is CDN-cached and lies about freshness. Confirm each write by re-querying the redirect through the API, then spot-check a handful of old paths with curl -I and look for 301 plus the mapped location.

Recipes, not scripts

The GraphQL and matching logic in references/pipeline.md are copy-and-adapt starting points. Your agent writes throwaway code per engagement against the current schema, runs it, and discards it: that keeps the pass honest across Shopify's quarterly schema changes rather than shipping a binary that silently rots. The eight-step runbook, the matching-algorithm spec, the urlRedirectCreate and Matrixify apply paths, the redirect-to-404 rot sweep (urlRedirectUpdate), and the WordPress URL transforms all live there.

References

• references/pipeline.md: the 8-step runbook, from GSC 404 export → inventory pull → matching-algorithm spec → apply → redirect-to-404 rot sweep → curl -I verify, plus WordPress pattern transforms.

Provenance and maintenance

Last verified: 2026-07-05. GraphQL pinned to Admin API 2025-07; Shopify deprecates versions on a rolling quarterly schedule, so verify the mutation and query names against shopify.dev before trusting a version-specific claim. Read-only re-verification a stranger can run:

# 1. List existing redirects (confirms scope + shows current map)
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ urlRedirects(first:10){ edges{ node{ path target } } } }"}'

# 2. Probe an old path and confirm it 301s where you expect
curl -sI "https://$SHOPIFY_STORE/old-path" | grep -iE "^(HTTP|location)"

Canonical docs: Shopify URL redirects and the Admin GraphQL API; source the 404 export from Google Search Console (Pages → Not found). These skills capture operational lessons the docs don't; they are not a replacement for the reference.