The API side
The Promotions API picks up three fields. is_featured_promotion is the boolean that marks a promotion as featured. featured_promotion_callout_message holds up to 80 characters of the text a shopper sees. promotion_category is read-only and reports whether the promotion is a cart or a shipping promotion, which gives the storefront something to branch on without parsing rules.
An is_featured query parameter filters promotions by the flag, so a store with a long promotion list can pull just the featured set in one call.
The cap is five featured promotions per store.
Where the context shows up
Stencil gains a featured_promotions array on the Product object, carrying each featured promotion's ID, callout text, priority and category. Priority is the interesting member of that set, because a field for ordering only exists if more than one callout can land on the same product.
The array is available on product detail pages, category listings, brand pages and search results. That is the part that changes merchandising rather than plumbing. Promotion messaging has historically lived at the point of decision, on the product page or in the cart, which is late for a threshold offer the shopper could have been building toward from the moment they landed on a category.
What to do about it
Decide which five earn the slot
Five is few enough that this is an editorial call rather than a configuration one. Rank by what changes basket behavior, not by discount depth: a free-shipping threshold and a multi-buy offer usually move more than a percentage off a single SKU. Set priority deliberately so the ordering is yours instead of whatever the array happens to return.
Put the threshold offer on listing pages
The context now reaches category, brand and search pages, which is where a shopper is still assembling a basket. A shipping-threshold callout on a category listing has room to change what they add; the same message at the cart mostly confirms a decision already made. Test it on your highest-traffic category before rolling it across the catalog.