Appearance
Source:
docs/adr/0004-merchant-entity-and-priced-links.md. Edit it there; this page is generated at build time.
Merchant entity + priced Affiliate Links with a freshness TTL, not a cached price field
We considered three ways to make prices renderable: keep the free-text network string on AffiliateLink and add a plain price column; introduce a full Offer entity between Product and merchant; or introduce a Merchant entity and put pricing directly on AffiliateLink. We chose the third. A Merchant is a real shared entity — it carries a logo, a required disclosure string, and its own price-staleness policy — none of which a free-text string can express, and all of which were being duplicated or simply omitted. We rejected a separate Offer model because AffiliateLink already is the product-merchant pair; splitting it would add a join and a second slug for no gain, and CONTEXT.md deliberately reserves "offer" as a property rather than an entity.
The important part is that price is modelled as perishable data, not state. Amazon's operating agreement forbids caching price or availability beyond 24 hours, so AffiliateLink stores price_updated_at and each Merchant stores max_price_age_minutes (default 1440), and displayPrice() returns null once that window passes while ctaLabel() degrades from "$39.99 at Amazon" to "Check Amazon". Nothing in the app can render a stale price: the view, the CTA label and the Offer/AggregateOffer schema.org node all derive from the same isPriceFresh() predicate. This is also why there is no price-history table and no "lowest ever" badge — Amazon now prohibits price tracking outright — and why lowest_used_price is a first-class column, since displaying prices in any comparison format obliges us to show the lowest used price alongside the lowest new one.
The trade-off is that a merchant with no live price feed shows a CTA rather than a number, which converts less well than a price. We accept that: the alternative is either a licence breach or a number we know may be wrong, and every publisher we examined (RTINGS, HouseFresh) makes the same choice of hiding or degrading the row rather than printing a stale figure.