Appearance
Source:
docs/affiliate-product-plan.md. Edit it there; this page is generated at build time.
Affiliate Site Product Plan
Date: 2026-09-06 Scope: What to build next on this Laravel 13 + Filament v4 review site, and why. Basis: Primary-source research into FTC rules (16 CFR 255 & 465), Google's reviews system and spam policies, Amazon's Associates operating agreement, WCAG 2.2, and teardowns of the shipped front-end code of Wirecutter, Tom's Guide, TechRadar, RTINGS and HouseFresh.
Out of date in these places, as checked against the code on 2026-09-19. The research in §2–§5 still stands. What's wrong is the description of the codebase and the roadmap.
- §1's "current state" table describes the site before Phase 1 and no longer matches it.
- §6 Phase 1, item 5 lists
AggregateRating. It appears nowhere inapp/. With one editorial review per product, correcting this plan may be the right fix rather than adding the markup.- §6 Phase 2, first bullet (Creators API price ingestion) has shipped. See ADR 0006.
- §5 "What not to build" lists dark mode. It shipped, and
tests/e2e/public-theme.spec.jscovers it.- §4 and §6's
lowest_used_pricecan no longer be sourced from Amazon. See ticket 005.
1. Where the site stands today
The editorial engine is genuinely good. Content is modelled properly (Review / Comparison / Listicle / Article as separate models, per ADR-0002), the catalog is shared and reusable, publishing has a workflow, and the public site has a real design system rather than a theme.
The monetisation and trust layers are the gap. Concretely:
| Area | Current state | Consequence |
|---|---|---|
| Offers | AffiliateLink = product + free-text network + URL. No price, no currency, no merchant entity | Cannot render a price, cannot compare retailers, cannot rank offers |
| Disclosure | One sentence in the site footer; the words "Affiliate Disclosure" there are plain text, not even a link | Non-compliant — see §2 |
| First-hand evidence | Review has no media of its own; the "cover image" borrows the linked Product's stock photo | Fails the single strongest signal in Google's reviews checklist |
| Methodology | No "how we tested", no test date, no measurements | Fails 4 of Google's 14 review criteria |
| Authors | Author model exists, but there are no author pages and no Person markup | E-E-A-T signal is modelled but never published |
| Structured data | Review, ItemList, Article only. No Offer, AggregateRating, BreadcrumbList, Organization, FAQPage | Leaves rich results on the table |
| Click data | Product + content + referrer only. No merchant, no dashboard, no aggregation | Cannot answer "which merchant converts" |
| Scheduling | scheduled status exists but nothing ever flips it to published | Scheduled posts never go live |
| Performance | No reserved space for any async content | CLS risk — the metric that actually fails affiliate sites |
2. Legal — the highest-risk, lowest-cost fix
This is not a "best practice" section. 16 CFR Part 465 is a trade regulation rule with civil penalties, effective 21 Oct 2024, currently $53,088 per violation (16 CFR §1.98; the 2026 inflation adjustment was cancelled government-wide by OMB M-26-11, so the Jan 2025 figure stands).
What the rule says, verbatim
§465.1(c)(4): "In any communication using an interactive electronic medium, such as social media or the internet, the disclosure must be unavoidable. A disclosure is not clear and conspicuous if a consumer must take any action, such as clicking on a hyperlink or hovering over an icon, to see it."
And the FTC's own Endorsement Guides FAQ forecloses the two patterns this site currently uses:
- Footer-only: "Consumers may miss a disclosure at the bottom of a blog or page. Many won't read to the very end… A disclosure is more likely to be seen if it's very close to, or — even better — part of — the endorsement to which it relates."
- Homepage/site-wide only: "No. A single disclosure on your home page won't be sufficient because people visiting your site might read individual reviews… without seeing the disclosure on your home page."
The co-visibility test — this is the actual design requirement
"When the review has a clear and conspicuous disclosure of your relationship and the reader can see both the review containing that disclosure and the link at the same time, readers have the information they need. But if the product review containing the disclosure and the link are separated, readers may not make the connection."
So: a disclosure must be visible in the same viewport as the affiliate link it covers. On a "best of" listicle with a buy button per entry, that means a short disclosure per entry — not one banner at the top of a 9,000-word page.
Wording matters, and the obvious phrase is wrong
| Verdict | Wording |
|---|---|
| ✅ Blessed | "Paid link" placed right next to the link |
| ✅ Blessed | "I get commissions for purchases made through links in this post" |
| ❌ Inadequate | "Affiliate link" — "Consumers might not understand that 'affiliate link' means that the person placing the link is getting paid" |
| ❌ Inadequate | "Commissionable link"; a bare "Buy now" button |
Ranking integrity cannot be disclosed away
§255.4(b)(3) is aimed squarely at "best X" sites:
"The website operator accepts money from manufacturers in exchange for higher rankings… Regardless of whether the website makes express claims of objectivity or independence, such paid-for rankings are deceptive… A disclosure that the website operator receives payments from headphone manufacturers would be inadequate because the payments actually determine the headphones' relative rankings."
"(ii) Assume that the review website operator uses a ranking methodology that results in higher rankings for products whose sellers have a relationship to the operator because of those relationships. The use of such a methodology is also misleading."
Product rule, permanently: commission rate, merchant relationship and click/conversion revenue must never be inputs to ranking or ordering. Sort by rank/score only.
Do not imply testing you did not do
There is no FTC duty to announce "we didn't test this". But §465.2(a)(2) prohibits misrepresenting "that the reviewer… used or otherwise had experience with the product", and §255.3(b) says an expert endorsement must rest on testing "at least as extensive as someone with the same degree of represented expertise would normally need to conduct." A disclaimer cannot rescue a "we tested 40 units" framing that didn't happen — §465.1(c)(7) bars a disclosure that is "contradicted or mitigated by, or inconsistent with, anything else in the communication."
Hence the is_hands_on flag in the data model: the site should state its evidence basis accurately rather than imply a lab it doesn't have.
UK / EU, if traffic warrants it later
- DMCCA 2024 (UK, in force 6 Apr 2025) — Sch. 20 para 12 bans undisclosed paid editorial; para 13 imposes a positive duty to police your own review pipeline. Penalties up to 10% of global turnover.
- UCPD as amended (EU) — Annex I point 11a bans undisclosed paid ranking; Art. 7(4a) requires published ranking-parameter transparency. Minimum penalty ceiling 4% of turnover.
- European Accessibility Act applied 28 Jun 2025. A pure affiliate site that never concludes a consumer contract is arguably outside the e-commerce category, and the microenterprise exemption (<10 staff) likely applies — but building to WCAG 2.2 AA settles it either way.
3. Google — what actually makes a review page rank
Google publishes a literal 14-point checklist ("Write high quality reviews"). The ones this site structurally cannot satisfy today are the ones worth building for:
- "Provide evidence such as visuals, audio, or other links of your own experience with what you are reviewing"
- "Share quantitative measurements about how something measures up in various categories of performance"
- "Discuss the benefits and drawbacks of something, based on your own original research"
- "Consider including links to multiple sellers to give the reader the option to purchase from their merchant of choice"
Point 12 is notable: Google explicitly endorses the multi-retailer price row, so the monetisation feature and the ranking feature are the same feature.
Two structural risks:
- The reviews system escalates site-wide. "primarily evaluates review content on a page-level basis. However, for sites that have a substantial amount of review content, any content within a site might be evaluated." One category you can't genuinely evaluate contaminates the rest.
- Thin affiliate is defined as affiliate links where descriptions are copied from the merchant "without any original content or added value" — and the named escape hatch is exactly the roadmap below: "additional information about price, original product reviews, rigorous testing and ratings, navigation of products or categories, and product comparisons."
The March 2026 core update is a warning about positioning: 24.1% of top-10 pages fell out of the top 100; the reported losers were "aggregators and directories" and "comparison-driven sites", the winners "specialist and niche platforms". Depth in one vertical beats breadth. HouseFresh — the canonical independent — went from 4,000 Google visits/day to 200 while publishing genuinely first-hand testing, and only partially recovered. Breadth is the losing archetype; this site should pick a vertical and go deep.
4. Monetisation mechanics — the constraints that shape the schema
Amazon PA-API 5.0 is deprecated. webservices.amazon.com/paapi5/… now 302s to a deprecation notice and calls return 403 AccessDeniedException — "Product Advertising API is deprecated. Please migrate to Creators API." Any PA-API tutorial or Laravel package is stale.
The licence terms that dictate data design:
| Constraint | Design consequence |
|---|---|
| Price/availability may not be cached beyond 24h, then must be refreshed or removed | price_updated_at + max_price_age_minutes per merchant; a stale price degrades to a CTA, never to an old number |
| A displayed price needs an adjacent "as of {time}" stamp + linked disclaimer | requires_price_timestamp flag per merchant |
| Images may not be stored or re-hosted (URL may be cached ≤24h) | Merchant imagery stays a URL; only our own photos go through MediaLibrary |
| ASINs may be stored indefinitely | The durable join key |
| In any comparison format, must show lowest new and lowest used price | lowest_used_price is a first-class column, not an afterthought |
| Price-history tracking now prohibited | No price charts, "lowest ever" badges, or drop alerts |
rel="noreferrer" strips the referrer Amazon requires be determinable | Ship rel="sponsored nofollow noopener" — never noreferrer |
Cloaked redirects (/go/{slug}) are fine: Wirecutter and RTINGS both run internal redirectors. Amazon's concern is that it can determine the originating site, which a same-origin redirect preserves. Keep /go/ disallowed in robots.txt (it already is).
5. UI & conversion — what the leaders actually ship
From reading the live shipped code of five leading sites, not from blog advice.
The buy button
Nobody uses "Buy Now". The price is the button.
| Site | Literal button text |
|---|---|
| Wirecutter | $398 from Amazon (no verb at all) |
| HouseFresh | $269.99 AT AMAZON, falling back to VIEW AT AMAZON |
| Tom's Guide | View at Amazon for a matched offer; Check Amazon for a keyword-search fallback |
| RTINGS | the price string + store name; Searching while loading; Unavailable when there is no offer |
Two rules fall out of this, and both are now in the data model:
- Front-load the price. NN/g's eye-tracking finds users read roughly the first two words of a link; 35% of tested links left users unable to guess the destination.
$269.99 at Amazonpasses;Buy Nowpromises a purchase the click doesn't deliver. - "Check" is the honest label for an unmatched link. Future's own markup distinguishes
data-product-type=1000(real offer → "View at") from200(search URL → "Check"). That is the industry's actual answer to the "Check price vs Buy now" question, and there is no published A/B test behind the folklore version.
Reserve the space — this is the one detail all five share
RTINGS sets min-height: 60px | 108px and renders skeletons; HouseFresh reserves 55px with a spinner and a 10s abort that hides the row rather than showing a stale price. CLS is the binding CWV failure for ad/affiliate sites: GPT-detected origins pass mobile CLS at 75.2% vs an 83.0% web baseline (−7.8pp), desktop −15.6pp. And reducing shift increases revenue — iCook +10% ad revenue from a 15% CLS improvement, Netzwelt +18%.
Page anatomy
- 2–3 retailers inline, more behind "See all prices". RTINGS hard-codes 2, or 3 in the US.
- Retailer name as text in-content; logos only in the end-of-article grid (logos cost layout stability and add nothing once the name is there).
- Keep the spec table separate from the price widget. TechRadar ships both and the spec table has no buy column — because static spec prices go stale and can't legally be Amazon-sourced.
- Stop monetising when the article turns educational. Every one of HouseFresh's 10 affiliate blocks sits in the first 45% of the page; the buying-advice and how-we-test back half carries zero buy buttons and switches to internal review links.
- Attention budget: 57% of viewing time is above the fold, 74% within two screenfuls. One CTA cluster above the fold, one per product section, one consolidating grid at the end — roughly 8–12 clusters, not 50 scattered links.
What not to build
- Sticky mobile buy bar. GoodUI's meta-analysis of 29 A/B tests is genuinely mixed, and none of the five leaders ships one — Future built the CSS class and chose not to deploy it.
- Exit-intent popup. Worst-converting trigger in the only vendor dataset that segments by trigger (3.94% vs 54.42% click-triggered); Baymard finds users dismiss load-triggered overlays reflexively; scroll-triggered popups count fully against CLS (only discrete input gets the
hadRecentInputexemption — scrolling does not); and Amazon's policies prohibit Amazon links or content in any pop-up. Ship an inline end-of-article form instead. - Dark mode, for now. NN/g's summary of the readability literature is that light mode wins on performance for most users and the advantage grows as font size shrinks — and it doubles the contrast-QA surface on stars, score meters and badges.
Accessibility, where it bites on this specific site
- Comparison tables: wrap in Roselli's
<div role="region" aria-labelledby="{caption-id}" tabindex="0">withoverflow:auto. Four attributes and two CSS rules that satisfy 1.4.10 (Reflow), 2.1.1 (Keyboard) and 4.1.2 (Name, Role, Value) simultaneously. Never restyle a table todisplay:blockstacked cards — that destroys the header/cell association outright. - Star ratings: symbols
aria-hidden="true"+ a visually-hidden "Rated 4.2 out of 5". Prefer hidden text overaria-labelbecause hidden text gets machine-translated andaria-labeldoes not.<meter>is effectively ignored by JAWS and iOS VoiceOver — don't rely on it. - Target size: 24×24 CSS px minimum (WCAG 2.5.8 AA). Individual stars and pagination links are the usual offenders.
- Sticky headers must not fully obscure a focused element (2.4.11) — fix with
html { scroll-padding-top: <header height> }.
6. Roadmap
Phase 1 — shipped in this pass
- Merchant entity + priced affiliate links, with per-merchant freshness TTL,
is_primary,lowest_used_price, and actaLabel()that degrades to "Check {merchant}" rather than ever printing a stale number. - Compliant disclosure: an unavoidable, per-cluster disclosure component rendered above the first buy button on every monetised page and beside each listicle entry; "Paid link" wording; Amazon's required string where an Amazon link is present. The review verdict box was missed until ticket 007 (2026-09-23).
FtcDisclosureTestnow checks the order on all four content types, andpublic-pages.spec.jschecks the review's disclosure and first buy button are on screen together. - First-hand evidence: Review gets its own photo gallery,
how_we_tested,is_hands_on,tested_at, quantitativemeasurements,alternatives, and achangelog/last_reviewed_at. - Buy component with price front-loaded, reserved height, and explicit empty/stale states.
- Structured data:
Offer/AggregateOffer,AggregateRating,BreadcrumbList,Organization,WebSite,Personauthors,FAQPage; null-stripped. - Author pages with credentials and external links.
- Scheduled publishing actually publishes (there is currently no job that flips the status).
- Click analytics: merchant attribution, a Filament dashboard, no PII stored.
- Accessibility pass on tables, ratings and targets; RSS; cached sitemap; 404 page.
Phase 2 — next
- Merchant price ingestion against the Creators API (queued, respecting the 24h TTL).
- Multi-currency / geo-routed merchant selection (HouseFresh runs per-locale Amazon tags).
- Review-comparison widget ("vs" pages generated from spec deltas).
- Editorial calendar + content-refresh queue driven by
last_reviewed_at. - Newsletter double opt-in and post-click follow-up (Amazon permits links in solicited email).
Phase 3 — later
- Conversion/EPC reporting via network postbacks, to measure merchants — for merchant choice and inventory decisions only, never as a ranking input (§255.4(b)(3)(ii)).
- Vertical focus: pick one category and go deep, per the March 2026 core-update signal.
7. Standing product rules
- Revenue never influences ranking or ordering. Not directly, not via a proxy feature.
- Never display a price older than its merchant's TTL. Degrade to a CTA.
- Never store or re-host merchant imagery. ASIN/SKU is the only durable merchant datum.
- Every buy button carries
rel="sponsored nofollow noopener"— nevernoreferrer. - A disclosure must be visible in the same viewport as the link it covers.
- Never imply testing that didn't happen;
is_hands_onis the source of truth. - Reserve space for anything that loads or changes late.
- No PII in the click log.