> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # FairShare media > Embed FairShare media, listen for playback events, and configure calls to action. Use `` to display one media item or a playlist. You can listen for playback events and scope listeners to a specific embed. For widget modes that render CTA controls, you can also override the call to action without building a player from scratch. ## Embed media Use `media-id` for one item or `playlist-id` for a playlist: ```html theme={null} ``` If you provide both identifiers, `playlist-id` takes precedence. See [FairShare web components](/sdk/components#media-widget) for common widget attributes. ## Listen for media events The media API exposes six subscription methods: | Event | Method | When it fires | | --------- | -------------------- | -------------------------------------- | | Load | `onLoad()` | Media metadata is ready | | Start | `onStart()` | Playback begins for the first time | | Pause | `onPause()` | Playback pauses | | Resume | `onResume()` | Playback resumes after a pause | | Complete | `onComplete()` | Playback reaches the end | | CTA click | `onCtaActionClick()` | The shopper selects the call to action | Subscribe through `FairShareSDK.media`: ```javascript theme={null} const unsubscribe = window.FairShareSDK.media.onStart((payload) => { console.log("Started:", payload.mediaId); }); // Stop listening when your component unmounts. unsubscribe(); ``` Playback payloads include the media identifier and type, timestamp, playback position and duration, media URL, title, and the playlist identifier when applicable. Media types include `video`, `image`, `pdf`, and `website`. `START` fires once on the first play. A play after pausing emits `RESUME`. Completing the media resets the lifecycle, so replaying it emits `START` again. ### Filter subscriptions Pass a filter as the second argument to listen to one media item, one playlist, or a specific media item within a playlist: ```javascript theme={null} const stopMediaListener = window.FairShareSDK.media.onComplete( (payload) => { console.log("Completed:", payload.mediaId); }, { mediaId: "starter-kit-demo" }, ); const stopPlaylistListener = window.FairShareSDK.media.onPause( (payload) => { console.log("Paused:", payload.mediaId); }, { playlistId: "spring-launch-demos" }, ); ``` Every subscription returns an unsubscribe function. ### Listen on window The same lifecycle is available as window events: ```javascript theme={null} window.addEventListener("FLUID_MEDIA_CTA_CLICK", (event) => { console.log("CTA selected:", event.detail.ctaType); }); ``` The event names are: * `FLUID_MEDIA_LOAD` * `FLUID_MEDIA_START` * `FLUID_MEDIA_PAUSE` * `FLUID_MEDIA_RESUME` * `FLUID_MEDIA_COMPLETE` * `FLUID_MEDIA_CTA_CLICK` Prefer `FairShareSDK.media` subscriptions when possible because they support filters and return cleanup functions. ## Configure media calls to action CTA settings affect widgets that render CTA controls. Currently, `default` and `popover` widgets render them; `inline` and `inline-shopping` widgets do not. Set a default CTA for eligible media widgets on the page: ```javascript theme={null} window.FairShareSDK.media.settings.setDefault({ ctaOptionsManualOverride: { type: "cart", }, }); ``` Override the default for one playlist or media item: ```javascript theme={null} window.FairShareSDK.media.settings.setForPlaylist("spring-launch-demos", { ctaOptionsManualOverride: { type: "link", url: "https://shop.example.com/starter-kits", buttonText: "Shop starter kits", }, }); window.FairShareSDK.media.settings.setForMedia("unboxing-the-starter-kit", { ctaOptionsManualOverride: { type: "email", buttonText: "Ask a question", }, }); ``` Set defaults, playlist overrides, and media overrides together when you already have the complete page configuration: ```javascript theme={null} window.FairShareSDK.media.settings.set({ default: { ctaOptionsManualOverride: { type: "cart", buttonText: "Add to cart", }, }, byPlaylistId: { "spring-launch-demos": { ctaOptionsManualOverride: { type: "link", url: "https://shop.example.com/starter-kits", buttonText: "Shop starter kits", }, }, }, byMediaId: { "unboxing-the-starter-kit": { ctaOptionsManualOverride: { type: "email", buttonText: "Ask a question", }, }, }, }); ``` You can also set `cta-options-manual-override` directly on the embed: ```html theme={null} ``` FairShare resolves CTA settings in this order: 1. The embed's `cta-options-manual-override` attribute 2. Settings for the media item 3. Settings for the playlist 4. Page defaults Settings created through the media API are page-scoped and stored in local browser storage. Read or clear the settings for the current page: ```javascript theme={null} const mediaSettings = window.FairShareSDK.media.settings.get(); window.FairShareSDK.media.settings.clear(); ```