Troubleshooting Product Pages

“Generation failed” or empty drafts

If a Product Pages run completes with empty FAQs, no “best for” labels, or a generic summary, the most common cause is not enough review content to extract from. The AI needs reviews with actual substance — phrases customers wrote about the product, not just star ratings.

How to fix

• Wait for more reviews. Aim for at least 10 detailed AI-conversation reviews per product before the first optimization.
• Re-import your existing reviews from Judge.me/Okendo/Yotpo if you haven’t yet — those count too, but only once they are embedded. Imported reviews become available to the AI after the import has been indexed; until then they show in your review list without feeding a generation.
• If the product is new and has no reviews, Product Pages will skip it on bulk generation and show a “Needs reviews” status.

”Top review” is blank

The top review is never written by the AI — it picks one of your existing reviews and shows it word for word. There are three reasons it can come back blank:

1. no_candidates — nothing this product has is an approved, visible, 4-5 star review of at least 15 words, or nothing the search pulled in cleared that bar. It fills in on the next generation once one arrives.
2. requested_review_invalid — you chose a specific review for the block and it is not an approved, visible, 4-5 star review of at least 15 words on this product. Pick another review, or let the AI choose.
3. Every candidate touched a banned topic — reviews that talk about price, discounts, shipping, customer service or other retailers are skipped for the top review under your content rules, so if every eligible review does, the block stays empty. A review you pick yourself skips this check.

The reason is recorded on the draft’s fact check and readable through the API (GET /api/v1/products/:id/optimization); a picker in the dashboard is a later release. A blank top review is left off the published page entirely rather than rendered as an empty block.

Content not appearing on my storefront

Click Publish on a product, then visit your live storefront and don’t see the AI summary or FAQs?

Check

1. BetterReviews Script app embed enabled. The sections only load their styles and script through the BetterReviews Script app embed. In Theme Editor → Customize → App embeds, make sure it’s toggled on for your published theme.
2. Theme blocks installed. Each AI section requires a corresponding Liquid block in your theme — hero-section, top-section, middle-section, bottom-section. Open Theme Editor → Customize → Add block on a product page. If you don’t see them, the BetterReviews theme extension isn’t installed; reinstall via the app.
3. Theme cache. Shopify caches theme content for 30-60 seconds. Refresh the page after waiting a minute.
4. Metafield permissions. If your theme is on a custom dev branch, the metafield render may need permissions. The block’s Liquid code reads product.metafields.ppo.* — check your theme can access that namespace.

What happens to my Product Pages content if my plan lapses?

Storefront-side: nothing changes. Already-published optimizations keep rendering on your product pages, and your review widget keeps rendering too. Customers see what they saw yesterday.

Dashboard-side: locked out. Opening the Product page content card in the Studio tab of the BetterReviews admin shows a prompt to restart your subscription. You can’t generate new optimizations, edit existing ones, or republish. Your historical data is preserved — when you’re subscribed again, everything reappears.

API-side: 403. Calls to POST /api/v1/products/.../optimize and friends return 403 entitlement_required. Read endpoints (GET /api/v1/products/.../optimization) return your stored data with the AI-generated content field stripped to null.

”Publish more” errors

• 429 unpublished_optimization_limit on optimize/regenerate — you’ve optimized the maximum number of products without publishing any. Publish a draft to unlock the next. (Re-optimizing a product you’ve already drafted is always allowed.)

• 402 insufficient_credits on regenerate — each block gets 5 free regenerations per draft; past that a regenerated block costs 1 AI credit and your pool is empty. Publish the draft (which resets the counters) or turn on auto-recharge.

• 422 widget_disabled on optimize or regenerate — you named a block your store has turned off in its content settings (ppo_content.enabled_widgets). Turn it back on, or leave it out of blocks_to_optimize. Turned-off blocks are also left off the page when you publish.

• 422 invalid_blocks on regenerate — the blocks_to_optimize you sent named no block we recognise. Use features, top_review, reviews_summary, faq or seo_description, or omit the field to regenerate everything.

Publishing a product page draws 5 AI credits, and running out returns 402 credit_limit_reached on publish. Turn on auto-recharge and publishing continues, billing the overage at your plan’s block rate. See Billing & limits.

Publish is blocked and says the content hasn’t been checked

Every sentence on a product page has to trace back to one of your reviews or to your own product description. Publishing is blocked until every section has passed that check.

• “Checking…” — a check is running. It usually takes under a minute; more than two edited sections finish in the background.
• “Couldn’t be checked” — the checker was unreachable. Try to publish and a banner appears under the editor toolbar; click Re-check there. If it keeps failing, email us. (On the API this is POST /api/v1/products/:product_id/optimization/recheck.)
• “The reviews behind this draft are gone” — the reviews this draft was written from have since been deleted or erased at the customer’s request, so there is nothing left to check it against. Re-checking can’t fix that: regenerate it, then publish. (Drafts for products with no reviews at all are fine — those are checked against your product description.)
• “Generated before fact-checking” — this draft was generated before the fact check existed, so there’s no report to re-check. Regenerate it, then publish. Editing such a draft saves your text but can never make it publishable. (Via the API this is 422 unverified_content with can_recheck: false on publish, and 422 legacy_draft_regenerate on re-check.)

A section says “not enough evidence”

The section passed the check, but after unsupported sentences were removed there wasn’t enough left to fill it — fewer than 3 features, fewer than 3 FAQs, a one-sentence summary, an SEO description under 60 words, or a top review whose quote didn’t match any of your reviews (which empties it).

This does not block publishing, but the section is left off your live page when you publish (your draft keeps it). It’s a signal that the source material is thin:

• Collect more reviews for that product, then regenerate.
• Add detail to the product’s own description in Shopify — measurable facts (materials, dimensions, weight, care instructions) may only come from there, never from a review.

Why did a sentence disappear from my draft?

The fact check removed it. Two things get removed:

• A quote that no review contains exactly. Quoted text has to appear word for word in one of your reviews. A paraphrase or a near-match inside quotation marks — different wording, corrected spelling — is removed, including in text you typed yourself.
• A sentence making a claim nothing supports. Typically an invented spec (“waterproof to one metre”) or a descriptor no customer used.

Each removal is listed in the section’s fact-check panel with the sentence and the reason. Removals apply to text you wrote by hand too — saving an edit re-runs the check.

If a freshly generated section is missing a sentence or FAQ you expected, the content rules may have left it out: store topics (price, discounts, shipping, customer service, other retailers) are off-limits by default, only one drawback per page survives, and the summary and FAQ need at least 3 approved reviews.

A section is missing from my live page

Publishing leaves a section off the live page when it is marked Not enough evidence, or when your store has turned that block off in its content settings. The draft keeps it either way. Via the API the publish response lists these under omitted_widgets.

I’m a legacy “lite” plan customer — am I locked out?

No. If you were on the legacy “lite” plan before Product Pages launched, your account has a per-store override that grants Product Pages access. Reach out at [email protected] if you see an upsell screen — that’s a sync bug, not a plan change.

Still stuck?

Email us at [email protected] or, if you have the Slack integration set up, ping the BetterReviews team in your dedicated channel.