Payload CMS migration audit
Payload is developer-friendly, but migrations still fail when collections, slugs, redirects, sitemaps, canonicals, preview routes, and product/category models are not tied to an SEO migration plan.
Payload SEO risk map
| Area | How it fails | Audit check |
|---|---|---|
| Collections and slugs | Payload documents can publish with duplicate slugs, changed slugs, missing redirect records, or frontend paths that differ from the canonical field. | Compare collection schema, slug history, old WordPress URLs, current frontend routes, canonical URLs, and XML sitemap entries by document type. |
| Next.js routing | Route handlers, catch-all routes, dynamic segments, localized paths, and product/category templates resolve more URL variants than the team intended. | Crawl known route patterns and verify one indexable 200 URL per intended document, with redirects or canonical rules for every duplicate route. |
| Redirects | WordPress, WooCommerce, category, tag, media, and legacy subdomain URLs are not mapped to their closest Payload-backed frontend URL. | Join old sitemap exports, GSC top pages, backlinks, redirect rules, Payload collections, and Vercel/CDN redirects before launch or recovery. |
| Metadata and canonicals | Payload SEO fields are optional, inherited incorrectly, or canonicalize to the CMS admin/API URL, old WordPress URL, or redirected frontend URL. | Validate generated metadata for pages, posts, products, categories, filters, pagination, draft previews, and fallback templates. |
| Sitemap generation | The sitemap includes drafts, noindex documents, deleted products, soft 404 templates, redirected URLs, or stale lastmod values. | Filter by publish status, robots policy, canonical target, HTTP status, internal-link state, and document update source before writing XML. |
| Preview and drafts | Draft, preview, staging, Vercel deployment, or Payload admin URLs become crawlable and compete with production pages. | Require noindex on preview/draft responses, block admin/API crawl paths, and verify production canonicals never point to preview hosts. |
| Product and category models | Product availability, replacement products, primary category, breadcrumb trail, filters, and schema fields are modeled separately from SEO rules. | Review products and categories as SEO entities, not just CMS documents. Check stock state, redirects, canonicals, breadcrumbs, schema, and sitemap eligibility together. |
Technical examples
Canonicals should be generated from the production frontend route, not from Payload admin URLs, API URLs, or stale WordPress fields.
export function getCanonicalUrl(doc, siteUrl) {
const path = doc.seo?.canonicalPath || doc.frontendPath;
if (!path || path.startsWith('http')) {
throw new Error('Canonical must be a production relative path');
}
return new URL(path, siteUrl).toString();
}Preview and draft states can help editors without creating crawlable duplicate URLs on production or Vercel preview hosts.
export function robotsForPayloadDoc(doc, requestHost) {
const isPreviewHost = requestHost.includes('vercel.app');
const isDraft = doc._status !== 'published';
if (isPreviewHost || isDraft || doc.seo?.noindex) {
return 'noindex,follow';
}
return 'index,follow';
}The XML sitemap should be an indexable URL list, not a dump of every Payload document that has ever existed.
export function includeInSitemap(doc, canonicalUrl) {
return doc._status === 'published'
&& !doc.seo?.noindex
&& !doc.redirectTarget
&& canonicalUrl === doc.frontendUrl
&& doc.template !== 'not-found';
}Model review
A product, category, article, or page is not safe because it exists in Payload. It is safe when route, status, canonical, redirect, sitemap, schema, and internal-link behavior agree.
Canonical frontend path
Old WordPress or WooCommerce URL
Redirect target and status
Published, draft, or archived status
Noindex override
Sitemap eligibility
Last modified source
Primary category
Breadcrumb trail
Product stock state
Replacement product or category
Schema type and required fields
Example findings
| Finding | Evidence | Fix | Priority |
|---|---|---|---|
| Missing product returns 200 | Deleted product URL renders a product-not-found template with HTTP 200 and a self-canonical URL. | Return a real 404/410, redirect to a replacement when one exists, and remove the URL from the product sitemap. | P0 when the product had clicks, revenue, or backlinks. |
| Draft content in sitemap | Payload documents with `_status: draft` appear in `/sitemap.xml` and pass live URL Inspection as indexable. | Filter draft, preview, archived, and noindex documents before sitemap generation and invalidate sitemap cache after publish changes. | P0 for any exposed draft or staging content. |
| Old backend URL canonical | Frontend page canonicalizes to a WordPress, Payload admin, API, or redirected URL instead of the final production path. | Generate canonicals from the production route helper and reject absolute external or admin URLs at validation time. | P0 for pages with rankings or duplicate routes. |
| Duplicate collection routes | `/products/chair`, `/product/chair`, and `/shop/chair` all return 200 with separate self-canonicals. | Keep one production route, redirect legacy patterns, and align sitemap plus internal links to the chosen URL. | P1 unless the duplicate owns current search visibility. |
| Category relation breaks breadcrumbs | Product has multiple categories, but the frontend picks a different primary category than the canonical category path. | Store a primary category relation and use it consistently for URL, canonical, breadcrumb, Product schema, and internal links. | P1 for large product/category catalogs. |
Audit boundary
Small Payload marketing site, contained route count, no catalog, no urgent traffic loss, and a clear old-to-new URL map.
Payload build with multiple collections, localized slugs, product/category models, redirects in CMS, custom sitemap generation, or 1,000+ public URLs.
Site already launched, GSC pages dropped, Google selected unexpected canonicals, old URLs return 404, or product/category visibility fell.
Evidence pack
Payload migrations sit between content modeling and frontend routing. The useful audit connects both sides before fixes are ranked.
QA sequence
Recovery path
The first deliverable should be a failure map: URL groups, evidence, root cause, fix owner, deployment path, and recrawl plan. A second rebuild is not the default answer.
Open the recovery audit pageSupporting assets
Use this when Payload is replacing WordPress as the content model behind a Next.js frontend.
Open resourceUse this when Payload is part of an ecommerce, product/category, or 3,000+ URL migration.
Open resourceUse this after launch to monitor pages, queries, devices, sitemaps, and URL Inspection samples.
Open resourceUse this to structure old WordPress/Payload URL mapping and redirect QA.
Open resourceUse this when Payload route, sitemap, redirect, and canonical targets disagree.
Open resourceUse this when the Payload migration already launched and traffic or indexed pages dropped.
Open resourceUse this to see the evidence-first report shape before scoping a custom Payload recovery audit.
Open resourceSend the launch date, Payload collections, sitemap URLs, redirect source, GSC access, GA4 access, route code, and which templates changed. The output is a developer-ready fix order for the migration.