{"id":2945,"date":"2026-06-16T03:46:05","date_gmt":"2026-06-16T03:46:05","guid":{"rendered":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/16\/how-i-built-the-two-missing-payload-cms-v3-plugins-reviews-json-ld-real-production-bugs\/"},"modified":"2026-06-16T03:46:05","modified_gmt":"2026-06-16T03:46:05","slug":"how-i-built-the-two-missing-payload-cms-v3-plugins-reviews-json-ld-real-production-bugs","status":"publish","type":"post","link":"https:\/\/tucumandevelopers.com\/index.php\/2026\/06\/16\/how-i-built-the-two-missing-payload-cms-v3-plugins-reviews-json-ld-real-production-bugs\/","title":{"rendered":"How I Built the Two Missing Payload CMS v3 Plugins \u2014 Reviews, JSON-LD & Real Production Bugs"},"content":{"rendered":"
\n
<\/div>\n
\n

<\/a> Running 23 European e-commerce shops on Payload CMS v3 taught me that some things simply don’t exist yet. So I built them. <\/h2>\n

Background
I maintain a multi-clone e-commerce infrastructure \u2014 23 Next.js + Payload CMS v3 shops deployed across Europe, each on its own subdomain and language. Think fr.myshop.com<\/code>, de.myshop.com<\/code>, sk.myshop.com<\/code>… all running on the same codebase with country-specific patches.
While building this, I kept running into two missing pieces that no one had published for Payload v3:
A customer reviews system with admin moderation and Google star ratings
Complete Schema.org JSON-LD for Google rich snippets (Product, BreadcrumbList, ItemList, AggregateRating)<\/p>\n

<\/a> Both are now published on npm. Here’s what I built, the bugs I hit, and how I solved them. <\/h2>\n

Part 1 \u2014 The Reviews Plugin
What didn’t exist
Search npm for payload reviews<\/code> or payload ratings<\/code> \u2014 you’ll find nothing for v3. The official plugin ecosystem covers SEO, forms, redirects, Stripe… but not customer reviews.
Building the collection
The reviews<\/code> collection itself is straightforward \u2014 relationship to products<\/code>, rating<\/code> (1-5), status<\/code> select (pending\/approved\/rejected), author fields. The tricky parts came later.
Access control gotcha: Payload v3 uses a roles<\/code> array, not a role<\/code> string. This breaks if you copy v2 patterns: <\/p>\n

\n
\/\/ \u274c Wrong \u2014 always returns false<\/span> update<\/span>:<\/span> ({<\/span> req<\/span> })<\/span> =><\/span> req<\/span>.<\/span>user<\/span>?.<\/span>role<\/span> ===<\/span> '<\/span>admin<\/span>'<\/span>,<\/span> \/\/ \u2705 Correct for v3<\/span> update<\/span>:<\/span> ({<\/span> req<\/span> })<\/span> =><\/span> req<\/span>.<\/span>user<\/span>?.<\/span>roles<\/span>?.<\/span>includes<\/span>(<\/span>'<\/span>admin<\/span>'<\/span>),<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Prevent self-verification: Users can POST any field on create: () => true<\/code> collections. Lock verified<\/code> in a beforeChange<\/code> hook: <\/p>\n
\n
hooks<\/span>:<\/span> {<\/span> beforeChange<\/span>:<\/span> [<\/span> ({<\/span> data<\/span> })<\/span> =><\/span> {<\/span> if <\/span>(<\/span>!<\/span>data<\/span>.<\/span>status<\/span>)<\/span> data<\/span>.<\/span>status<\/span> =<\/span> '<\/span>pending<\/span>'<\/span> data<\/span>.<\/span>verified<\/span> =<\/span> false<\/span> \/\/ admin-only, always reset on create<\/span> return<\/span> data<\/span> },<\/span> ],<\/span> },<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Email protection: read: () => true<\/code> on the collection exposes authorEmail<\/code> in the public API. Add field-level access: <\/p>\n
\n
{<\/span> name<\/span>:<\/span> '<\/span>authorEmail<\/span>'<\/span>,<\/span> type<\/span>:<\/span> '<\/span>email<\/span>'<\/span>,<\/span> access<\/span>:<\/span> {<\/span> read<\/span>:<\/span> ({<\/span> req<\/span> })<\/span> =><\/span> req<\/span>.<\/span>user<\/span>?.<\/span>roles<\/span>?.<\/span>includes<\/span>(<\/span>'<\/span>admin<\/span>'<\/span>)<\/span> },<\/span> }<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The relationship bug \u2014 \"108 0\"<\/code> instead of 108<\/code>
 When the form submitted product: productId<\/code>, Payload rejected it with: <\/p>\n
\n
\"This relationship field has the following invalid relationships: 108 0\" <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The string \"108 0\"<\/code> was being sent instead of the number 108<\/code>. The fix: <\/p>\n
\n
\/\/ \u274c Sends \"108 0\" \u2014 unknown why the space appears<\/span> body<\/span>:<\/span> JSON<\/span>.<\/span>stringify<\/span>({<\/span> ...<\/span>form<\/span>,<\/span> product<\/span>:<\/span> productId<\/span> })<\/span> \/\/ \u2705 Force integer<\/span> body<\/span>:<\/span> JSON<\/span>.<\/span>stringify<\/span>({<\/span> ...<\/span>form<\/span>,<\/span> product<\/span>:<\/span> parseInt<\/span>(<\/span>productId<\/span>,<\/span> 10<\/span>)<\/span> })<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Custom endpoints don’t work for parameterized routes in v3
 I tried registering the reviews GET endpoint in payload.config.ts<\/code>: <\/p>\n
\n
endpoints<\/span>:<\/span> [{<\/span> path<\/span>:<\/span> '<\/span>\/reviews\/product\/:productId<\/span>'<\/span>,<\/span> method<\/span>:<\/span> '<\/span>get<\/span>'<\/span>,<\/span> handler<\/span>:<\/span> ...<\/span> }]<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Result: Route not found \"\/api\/reviews\/product\/108\"<\/code> \u2014 Payload v3 doesn’t mount parameterized endpoints correctly under \/api<\/code>.
 Solution: use a Next.js App Router route instead: <\/p>\n
\n
\/\/ src\/app\/(app)\/api\/reviews\/product\/[productId]\/route.ts<\/span> export<\/span> async<\/span> function<\/span> GET<\/span>(<\/span>req<\/span>,<\/span> {<\/span> params<\/span> })<\/span> {<\/span> const<\/span> {<\/span> productId<\/span> }<\/span> =<\/span> await<\/span> params<\/span> const<\/span> payload<\/span> =<\/span> await<\/span> getPayload<\/span>({<\/span> config<\/span>:<\/span> configPromise<\/span> })<\/span> const<\/span> reviews<\/span> =<\/span> await<\/span> payload<\/span>.<\/span>find<\/span>({<\/span> collection<\/span>:<\/span> '<\/span>reviews<\/span>'<\/span>,<\/span> where<\/span>:<\/span> {<\/span> and<\/span>:<\/span> [<\/span> {<\/span> product<\/span>:<\/span> {<\/span> equals<\/span>:<\/span> parseInt<\/span>(<\/span>productId<\/span>,<\/span> 10<\/span>)<\/span> }<\/span> },<\/span> {<\/span> status<\/span>:<\/span> {<\/span> equals<\/span>:<\/span> '<\/span>approved<\/span>'<\/span> }<\/span> },<\/span> ],<\/span> },<\/span> })<\/span> \/\/ ...<\/span> }<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The database table doesn’t auto-create
 Payload running with migration batch: -1<\/code> (dev mode) won’t auto-migrate on build. You need to create the reviews<\/code> table manually: <\/p>\n
\n
CREATE<\/span> TYPE<\/span> \"public\"<\/span>.<\/span>\"enum_reviews_status\"<\/span> AS<\/span> ENUM<\/span>(<\/span>'pending'<\/span>,<\/span> 'approved'<\/span>,<\/span> 'rejected'<\/span>);<\/span> CREATE<\/span> TABLE<\/span> IF<\/span> NOT<\/span> EXISTS<\/span> \"reviews\"<\/span> (<\/span> \"id\"<\/span> serial<\/span> PRIMARY<\/span> KEY<\/span>,<\/span> \"product_id\"<\/span> integer<\/span> NOT<\/span> NULL<\/span> REFERENCES<\/span> \"products\"<\/span>(<\/span>\"id\"<\/span>)<\/span> ON<\/span> DELETE<\/span> SET<\/span> NULL<\/span>,<\/span> \"author_name\"<\/span> varchar<\/span> NOT<\/span> NULL<\/span>,<\/span> \"author_email\"<\/span> varchar<\/span> NOT<\/span> NULL<\/span>,<\/span> \"rating\"<\/span> numeric<\/span> NOT<\/span> NULL<\/span>,<\/span> \"title\"<\/span> varchar<\/span>,<\/span> \"comment\"<\/span> varchar<\/span> NOT<\/span> NULL<\/span>,<\/span> \"verified\"<\/span> boolean<\/span> DEFAULT<\/span> false<\/span>,<\/span> \"status\"<\/span> \"enum_reviews_status\"<\/span> DEFAULT<\/span> 'pending'<\/span>,<\/span> \"updated_at\"<\/span> timestamp<\/span>(<\/span>3<\/span>)<\/span> with<\/span> time<\/span> zone<\/span> NOT<\/span> NULL<\/span> DEFAULT<\/span> now<\/span>(),<\/span> \"created_at\"<\/span> timestamp<\/span>(<\/span>3<\/span>)<\/span> with<\/span> time<\/span> zone<\/span> NOT<\/span> NULL<\/span> DEFAULT<\/span> now<\/span>()<\/span> );<\/span> ALTER<\/span> TABLE<\/span> \"payload_locked_documents_rels\"<\/span> ADD<\/span> COLUMN<\/span> IF<\/span> NOT<\/span> EXISTS<\/span> \"reviews_id\"<\/span> integer<\/span> REFERENCES<\/span> \"reviews\"<\/span>(<\/span>\"id\"<\/span>)<\/span> ON<\/span> DELETE<\/span> CASCADE<\/span>;<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Install <\/p>\n
\n
npm install <\/span>payload-plugin-reviews <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\n
\/\/ payload.config.ts<\/span> import<\/span> {<\/span> reviewsPlugin<\/span> }<\/span> from<\/span> '<\/span>payload-plugin-reviews<\/span>'<\/span> export<\/span> default<\/span> buildConfig<\/span>({<\/span> plugins<\/span>:<\/span> [<\/span>reviewsPlugin<\/span>({<\/span> productsCollection<\/span>:<\/span> '<\/span>products<\/span>'<\/span> })],<\/span> })<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\u2192 payload-plugin-reviews on npm<\/p>\n
  <\/a> \u2192 GitHub <\/h2>\n
Part 2 \u2014 The JSON-LD Plugin
 What didn’t exist
 Payload’s official SEO plugin handles meta tags. It does not handle Schema.org structured data. No one had published a complete JSON-LD solution for Payload v3 e-commerce either.
 After running 23 shops in production and passing Google Rich Results validation on all of them, I extracted the patterns into payload-plugin-seo-jsonld<\/code>.
 Bug 1 \u2014 price<\/code> vs lowPrice<\/code>
 Google’s Rich Results validator rejects AggregateOffer<\/code> with price<\/code>. It requires lowPrice<\/code>: <\/p>\n
\n
\/\/ \u274c Google rejects this<\/span> offers<\/span>:<\/span> {<\/span> '<\/span>@type<\/span>'<\/span>:<\/span> '<\/span>AggregateOffer<\/span>'<\/span>,<\/span> price<\/span>:<\/span> price<\/span> }<\/span> \/\/ \u2705 Google accepts this<\/span> offers<\/span>:<\/span> {<\/span> '<\/span>@type<\/span>'<\/span>:<\/span> '<\/span>AggregateOffer<\/span>'<\/span>,<\/span> lowPrice<\/span>:<\/span> price<\/span> }<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Bug 2 \u2014 Prices stored in cents
 Payload e-commerce stores prices in cents (3990<\/code> = \u20ac39.90). Pass the raw value to Google and you’ll have a \u20ac3,990 bracelet in your rich snippets: <\/p>\n
\n
\/\/ \u274c Sends 3990 to Google<\/span> lowPrice<\/span>:<\/span> product<\/span>.<\/span>priceInUSD<\/span> \/\/ \u2705 Correct<\/span> lowPrice<\/span>:<\/span> (<\/span>product<\/span>.<\/span>priceInUSD<\/span> \/<\/span> 100<\/span>).<\/span>toFixed<\/span>(<\/span>2<\/span>)<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
Bug 3 \u2014 ItemList duplicates crash Google validation
 If a page has two ItemList<\/code> JSON-LD scripts, Google invalidates both. This happened on shops that inherited a carousel from a base template and then had a new one patched in.
 The plugin returns null<\/code> when products are empty, and the pattern makes the single-instance contract explicit: <\/p>\n
\n
\/\/ Returns null if empty \u2014 safe conditional render<\/span> const<\/span> itemListJsonLd<\/span> =<\/span> buildItemListJsonLd<\/span>({<\/span> products<\/span>:<\/span> products<\/span>.<\/span>docs<\/span>,<\/span> siteUrl<\/span> })<\/span> {<\/span>itemListJsonLd<\/span> &&<\/span> (<\/span> <<\/span>script<\/span> type<\/span>=<\/span>\"<\/span>application\/ld+json<\/span>\"<\/span> dangerouslySetInnerHTML<\/span>=<\/span>{{<\/span> __html<\/span>:<\/span> JSON<\/span>.<\/span>stringify<\/span>(<\/span>itemListJsonLd<\/span>)<\/span> }}<\/span> \/<\/span>> <\/span>)}<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
BreadcrumbList with nested categories
 The BreadcrumbList recursively walks the category parent chain: <\/p>\n
\n
Shop \u2192 Jewelry \u2192 Bracelets \u2192 Product Name <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\n
const<\/span> collectParents<\/span> =<\/span> (<\/span>c<\/span>:<\/span> any<\/span>)<\/span> =><\/span> {<\/span> if <\/span>(<\/span>c<\/span>.<\/span>parent<\/span> &&<\/span> typeof<\/span> c<\/span>.<\/span>parent<\/span> ===<\/span> '<\/span>object<\/span>'<\/span>)<\/span> collectParents<\/span>(<\/span>c<\/span>.<\/span>parent<\/span>)<\/span> parents<\/span>.<\/span>push<\/span>(<\/span>c<\/span>)<\/span> }<\/span> collectParents<\/span>(<\/span>cat<\/span>)<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
This requires fetching products at depth: 3<\/code> to populate categories and their parents.
 AggregateRating \u2014 connecting reviews to JSON-LD
 Plug in your review data to get Google star ratings in search results: <\/p>\n
\n
const<\/span> productJsonLd<\/span> =<\/span> buildProductJsonLd<\/span>({<\/span> product<\/span>,<\/span> siteUrl<\/span>,<\/span> currency<\/span>:<\/span> '<\/span>EUR<\/span>'<\/span>,<\/span> averageRating<\/span>:<\/span> 4.8<\/span>,<\/span> \/\/ from your reviews query<\/span> reviewCount<\/span>:<\/span> 42<\/span>,<\/span> })<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
The plugin only adds aggregateRating<\/code> when reviewCount > 0<\/code> \u2014 no empty rating blocks.
 Install <\/p>\n
\n
npm install <\/span>payload-plugin-seo-jsonld <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\n
import<\/span> {<\/span> buildProductJsonLd<\/span>,<\/span> buildBreadcrumbJsonLd<\/span>,<\/span> buildItemListJsonLd<\/span>,<\/span> buildWebSiteJsonLd<\/span>,<\/span> buildOrganizationJsonLd<\/span>,<\/span> }<\/span> from<\/span> '<\/span>payload-plugin-seo-jsonld<\/span>'<\/span> <\/code><\/pre>\n
\n<\/p><\/div>\n<\/p><\/div>\n
\u2192 payload-plugin-seo-jsonld on npm<\/p>\n
  <\/a> \u2192 GitHub <\/h2>\n
Part 3 \u2014 Enabling Google indexing on new shops
 Two things block Google on fresh Payload v3 deployments that aren’t obvious:<\/p>\n
    \n
  1. Default noindex<\/code> in layout.tsx New Payload projects ship with indexing disabled: <\/li>\n<\/ol>\n
    \n
    \/\/ src\/app\/(app)\/layout.tsx<\/span> robots<\/span>:<\/span> {<\/span> index<\/span>:<\/span> false<\/span>,<\/span> \/\/ \u2190 blocks Google<\/span> follow<\/span>:<\/span> false<\/span>,<\/span> }<\/span> <\/code><\/pre>\n
    \n<\/p><\/div>\n<\/p><\/div>\n
    Fix: <\/p>\n
    \n
    sed<\/span> -i<\/span> 's\/index: false,\/index: true,\/'<\/span> src\/app\/(<\/span>app)<\/span>\/layout.tsx sed<\/span> -i<\/span> 's\/follow: false,\/follow: true,\/'<\/span> src\/app\/(<\/span>app)<\/span>\/layout.tsx <\/code><\/pre>\n
    \n<\/p><\/div>\n<\/p><\/div>\n
      \n
    1. robots.txt Verify your public\/robots.txt<\/code> allows crawling: <\/li>\n<\/ol>\n
      \n
      User-agent: * <\/span>Allow:<\/span> <\/span>\/<\/span> <\/span>Sitemap:<\/span> <\/span>https:\/\/myshop.com\/sitemap.xml<\/span> <\/span><\/code><\/pre>\n
      \n<\/p><\/div>\n<\/p><\/div>\n
      Verification: <\/p>\n
      \n
      # Check no noindex header<\/span> curl -sI<\/span> \"https:\/\/myshop.com\/shop\"<\/span> | grep<\/span> -i<\/span> \"x-robots<\/span>\\|<\/span>noindex\"<\/span> # Check single ItemList<\/span> curl -s<\/span> \"https:\/\/myshop.com\/shop\"<\/span> | grep<\/span> -o<\/span> '\"@type\":\"ItemList\"'<\/span> | wc<\/span> -l<\/span> # \u2192 must return 1<\/span> <\/code><\/pre>\n
      \n<\/p><\/div>\n<\/p><\/div>\n
        <\/a> Test structured data: Google Rich Results Test <\/h2>\n
      What I learned
       Payload v3 routes are Next.js routes \u2014 don’t fight the framework, use App Router for parameterized endpoints
       Always check migration mode \u2014 batch: -1<\/code> means Payload manages schema automatically in dev, but won’t auto-migrate in prod
       Google is strict on JSON-LD \u2014 lowPrice<\/code> not price<\/code>, one ItemList<\/code> per page, reviewCount > 0<\/code> before adding aggregateRating<\/code><\/p>\n
        <\/a> Field-level access control is underused \u2014 protect sensitive fields at the field level, not just the collection level <\/h2>\n
      Links
       payload-plugin-reviews \u2014 npm
       payload-plugin-seo-jsonld \u2014 npm
       Payload CMS \u2014 the framework<\/p>\n
        <\/a> Google Rich Results Test <\/h2>\n
      \n
      About the author
       I’m Camille, a freelance developer specializing in European e-commerce infrastructure. I build and maintain 23 Payload CMS v3 shops deployed across Europe \u2014 each country-specific, SEO-optimized, and running in production.
       The plugins in this article came directly from real production needs. If something didn’t exist, I built it.
       \ud83d\udd27 GitHub \u2014 github.com\/spiritracking-arch
       \ud83d\udce6 payload-plugin-reviews \u2014 npmjs.com\/package\/payload-plugin-reviews
       \ud83d\udce6 payload-plugin-seo-jsonld \u2014 npmjs.com\/package\/payload-plugin-seo-jsonld
       \ud83c\udf10 ScaleYourShop \u2014 lochness-paris.com\/scaleyourshop.html \u2014 the infrastructure behind these 23 shops<\/p>\n<\/p><\/div>\n<\/div>\n<\/div>\n<\/div>\n
      Fuente: Art\u00edculo original<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
      Running 23 European e-commerce shops on Payload CMS v3 taught me that some things simply don’t exist yet. So I built them. Background I maintain a multi-clone e-commerce infrastructure \u2014 23 Next.js + Payload CMS v3 shops deployed across Europe, each on its own subdomain and language. Think fr.myshop.com, de.myshop.com, sk.myshop.com… all running on the […]<\/p>\n","protected":false},"author":1,"featured_media":2944,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[41],"tags":[],"class_list":["post-2945","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devto"],"jetpack_publicize_connections":[],"_links":{"self":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/2945","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/comments?post=2945"}],"version-history":[{"count":0,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/posts\/2945\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media\/2944"}],"wp:attachment":[{"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/media?parent=2945"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/categories?post=2945"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tucumandevelopers.com\/index.php\/wp-json\/wp\/v2\/tags?post=2945"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}