Shoppable Widgets

Shoppable widgets

Turn library videos into shoppable storefront experiences: tag products on videos, build onsite widgets (Stories, Carousel, Spotlight, For You Feed, Tile, Collection Grid, Bubble Feed), publish them, and read Meta ads performance. All via the Tolstoy Library MCP.

Mental model

• A video becomes shoppable when you tag store products on it (tag_video_product). Tagged videos feed the product_tagged playlist and show on those products' pages.
• A widget (onsite project) is what shoppers see on the store — it draws from playlists/rules and renders as Stories, Carousel, Spotlight, etc.
• A widget is live in Tolstoy when live: true, but storefront visibility also needs the Tolstoy app embed enabled in the Shopify theme (one-time, per store). The publish result spells out the steps — relay them.
• Tools default to the connected store; pass appUrl (full or a distinctive fragment) to target another of the account's stores. Use list_stores to see them.

Make a video shoppable

1. Find the video — search_assets (by name) or list_assets (recent/favorites).
2. Find the product — search_products with the product title → take its externalProductId.
3. Tag it — tag_video_product { vodAssetId, addProductIds: [externalProductId], appUrl? }. Untag with removeProductIds.
   • The result reports per-product success/failure — if a product id belongs to another store, it fails; pass the matching appUrl.

Build & publish a widget

1. Create — create_widget { type } where type is stories, carousel, spotlight, tv (For You Feed), tile-embed, collectionPageTile, or bubble-feed. It starts offline with the platform's defaults (most start from product-tagged videos).
2. Inspect — get_widget { publishId } shows the actual media it will render, content rules, and PDP mode. For PDP-mode widgets, pass productId to see exactly what a given product page would show.
3. Adjust — update_widget { publishId, ... }: rename, toggle isPdpMode, set maxMediaAgeDays, or replace content (sourcesIn/sourcesOut playlists, rules for pin/hide/manual/sort). Read with get_widget first; these are full replacements.
4. Publish — update_widget { publishId, live: true }. Relay the returned app-embed setup steps; confirm whether the embed is already enabled on the store.

Read ad performance

• list_ad_campaigns — Meta campaigns with real delivery status. Report effectiveStatus, not just status; ACTIVE-but-not-delivering is not "live."
• get_ads_performance { level, datePreset } — spend, ROAS, CTR, purchases. Use level: "ad" for winner/loser creative comparisons. If purchases are 0 but custom conversions exist, the account tracks conversions differently — don't call it unprofitable.
• publish_to_meta_ads_library { asset } — push a library video/image into Meta Ads Manager, ready for ad creation. No campaign or spend is created. With multiple ad accounts, pass adAccountId.

There is no create/activate/pause-campaign tool — money-moving operations stay in the Tolstoy platform on purpose.

End-to-end example

"Make my unboxing video shoppable for the DBTK 1 shirt, put it in a stories widget, publish it, and show me how my ads are doing."

1. search_assets "unboxing" → vodAssetId
2. search_products "DBTK 1" → externalProductId
3. tag_video_product { vodAssetId, addProductIds: [externalProductId] }
4. create_widget { type: "stories" } → publishId
5. get_widget { publishId, productId: "<DBTK 1 id>" } → confirm the video shows on that product's page
6. update_widget { publishId, live: true } → relay app-embed steps
7. get_ads_performance { level: "campaign", datePreset: "last_7d" }

Notes

• Multi-store: a product id is store-specific. Keep appUrl consistent across search_products and tag_video_product.
• get_widget content is the unscoped pool unless you pass productId; PDP-mode widgets show only the per-product subset to shoppers.
• App-aware clients (ChatGPT, Claude) render a shoppable-widget card grid and media previews inline.