Featured Offer

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

FeaturedOffer is a system-generated pricing snapshot that stores the best resolved offer for a product, country, state, quantity, and offer type. It is a derived pricing view, not a manually authored pricing source.

Parent hierarchy:

• Pricing & Promotions
• System-Generated Pricing Views
• Featured Offer

Primary implementation paths:

• packages/framework/src/Models/FeaturedOffer.php
• packages/framework/src/Actions/FeaturedOffer/CalculateFeaturedOffers.php
• packages/framework/src/Actions/Product/GetDisplayPricesByProvinceCodes.php
• packages/framework/src/Features/CalculateFeaturedOfferFeature.php

What Users Can Do With It

Direct capabilities

In the inspected packaged product, operators do not directly create or edit featured offers.

Indirect capabilities

Featured offers are affected by:

• underlying product-offer changes
• regional shipping-postal coverage
• offer-type filtering for public, sales-promotion, clearance, sample, or pro-deal pricing
• automated recalculation jobs

Where It Is Managed

Channel	Role	Notes
Background jobs	Direct system-owned	CalculateFeaturedOffers creates, updates, and deletes featured offers
Feature flag	Direct system-owned	Calculation is gated by CalculateFeaturedOfferFeature
Storefront and search consumers	Indirect	Derived pricing by province and region uses featured offers
Admin UI	Not confirmed	No packaged featured-offer CRUD or review screen was found in this sprint

Sources:

• packages/framework/src/Actions/FeaturedOffer/CalculateFeaturedOffers.php
• packages/framework/src/Features/CalculateFeaturedOfferFeature.php
• packages/framework/src/Actions/Product/GetDisplayPricesByProvinceCodes.php

Channel-Level Field Coverage

The model stores:

• product_id
• country_id
• state_id
• product_offer_id
• quantity
• offer_type
• regular_price
• sale_price
• msrp_price

Computed accessors include:

• current_price
• current_price_decimal

Source:

• packages/framework/src/Models/FeaturedOffer.php

Configuration And Data Model

Key model characteristics:

• system-generated
• region-aware
• quantity-aware
• linked back to the underlying ProductOffer

Important field groups:

Field Group	Purpose
identity	product, country, state, quantity, offer type
underlying linkage	product_offer_id
price snapshot	regular_price, sale_price, msrp_price, computed current price

Sources:

• packages/framework/src/Models/FeaturedOffer.php
• packages/framework/src/Actions/FeaturedOffer/CalculateFeaturedOffers.php

Relationships

FeaturedOffer directly relates to:

• product
• country
• state
• productOffer

Source:

• packages/framework/src/Models/FeaturedOffer.php

Rules And Downstream Effects

Important rules and effects:

• public featured offers are resolved separately from typed offers such as pro_deal
• the calculation job finds the best available offer per state and quantity
• stale featured offers are deleted when no valid offer remains
• any change in featured offers dispatches FeaturedOfferChanged
• featured-offer recalculation is requested from product-offer updates, deletes, restores, force deletes, and offer-inventory pivot changes, then gated through the calculate-featured-offer feature listener

Sources:

• packages/framework/src/Actions/FeaturedOffer/CalculateFeaturedOffers.php
• packages/framework/src/Observers/ProductOfferObserver.php
• packages/framework/src/Models/ProductOfferProductInventoryItem.php
• packages/framework/src/Listeners/CalculateFeaturedOfferListener.php
• packages/framework/src/Events/FeaturedOfferCalculationRequested.php

Integrations And Automation

Featured offers are produced by automation and then consumed by downstream pricing/search logic.

Important integrations:

• GetDisplayPricesByProvinceCodes
• search/index price-by-province generation
• feature-flagged queued recalculation via FeaturedOfferCalculationRequested

Sources:

• packages/framework/src/Actions/Product/GetDisplayPricesByProvinceCodes.php
• packages/framework/src/Actions/Product/ToSearchableArray.php
• packages/framework/src/Features/CalculateFeaturedOfferFeature.php

Where It Appears To End Users

FeaturedOffer is not a user-managed record, but it shapes shopper-visible price presentation.

It appears indirectly through:

• region-aware displayed prices
• product cards and product detail pricing
• province-based pricing/search payloads

Sources:

• packages/framework/src/Actions/Product/GetDisplayPricesByProvinceCodes.php
• packages/framework/src/Actions/Product/ToSearchableArray.php

Current Documentation Takeaways

• FeaturedOffer is a snapshot layer, not the source-of-truth price record.
• The real business input is ProductOffer; featured offers are optimized derived output.
• This node deserves technical documentation because it affects storefront pricing behavior, even though operators do not manage it directly.

Open Questions

• This first pass did not identify a dedicated packaged review screen or public resource for featured offers.
• Host-app-specific manual recalculation entry points, if any, were not explored beyond the framework event and listener chain.