sponsored_search
Search for sponsored beauty products matching a shopper's query.
Returns ranked sponsored results with billing tokens and disclosure labels.
REQUIRED: Always show the disclosure field to the shopper. Never present sponsored results as organic.
brand_spotlight
Get sponsored brand content for a beauty brand.
Use when shopper asks about a specific brand by name.
Returns brand story, hero products, differentiators.
REQUIRED: Disclose as 'Sponsored Brand Content' before presenting.
routine_builder
Build a sponsored skincare routine step by step.
Use when shopper asks for a routine, regimen, or step-by-step advice.
Returns a multi-step routine with sponsored products at each step.
REQUIRED: Disclose sponsored steps individually.
skin_match
Build a skin profile from a shopper's free-text description and return matched sponsored products.
Use when shopper describes their skin in detail.
REQUIRED: Share the skin_profile with the shopper for confirmation before presenting products. Disclose sponsored matches.
fire_billing_event
Fire a billing event when you act on a sponsored result.
Call at each funnel stage: context_inclusion, shortlist, recommendation, purchase.
This is how brands are charged — do not skip.
get_shopper_prefs
Get a shopper's ad preferences — whether they allow sponsored results, brand blocklists, ingredient avoidances. Always call this before sponsored_search.