> ## 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 Web Components > Use FairShare cart, banner, lead capture, and media web components. FairShare ships four web components that you place directly in your HTML markup: ``, ``, ``, and ``. The SDK registers a component when its tag appears on the page, so you do not need an import or build step. ## Cart Widget ### When to Use Use `` to add a floating cart button and slide-out cart sidebar to your site. The widget displays a live item count, lets shoppers review and edit their cart, and links to checkout. If you want to build a fully custom cart UI, you can hide the widget with `hideWidget` and drive the cart panel with the [JavaScript cart controls](/sdk/cart-api#cart-control) instead. ### Usage ```html theme={null} ``` ### Attributes | Attribute | Type | Default | Description | | ---------------------- | ------- | -------------- | --------------------------------------------------------------------------------------------- | | `useBrand` | boolean | `false` | Apply brand colors from your Fluid shop settings | | `primaryColor` | string | — | Primary color as a hex value, e.g. `#3461ff` | | `position` | string | `bottom_right` | Screen corner for the floating button: `bottom_right`, `bottom_left`, `top_right`, `top_left` | | `size` | number | `60` | Diameter of the floating cart button in pixels | | `hideWidget` | boolean | `false` | Hide the floating button while keeping the cart panel functional | | `alwaysOpen` | boolean | `false` | Keep the cart sidebar permanently open (useful for dedicated cart pages) | | `fluidShopDisplayName` | string | — | Display name for the shop shown inside the cart widget | ### JavaScript Settings Override Override widget settings at runtime using `cart.settings.set()`. Settings are scoped to the current URL path, so you can apply different configurations on different pages without changing the HTML. ```javascript theme={null} window.FairShareSDK.cart.settings.set({ hideWidget: false, position: "bottom_right", size: 60, placement: "right", primaryColor: "#3461ff", secondaryColor: "#2d3748", xMargin: 16, yMargin: 16, }); // Read active settings const settings = window.FairShareSDK.cart.settings.get(); // Reset to component-level defaults window.FairShareSDK.cart.settings.clear(); ``` *** ## Lead Capture Widget ### When to Use Use `` when you want a ready-made contact form that submits leads directly to Fluid. The widget handles field rendering, validation, submission, and success messaging. It's ideal for landing pages, contact sections, or anywhere you want to collect prospects without writing form-handling code. ### Usage ```html theme={null} ``` Common attributes include: | Attribute | Description | | -------------------- | ---------------------------------------------------------------------------------------------------- | | `title` | Heading displayed at the top of the form | | `description` | Subheading or instructional text below the title | | `submit-button-text` | Label for the form's submit button | | `success-message` | Message shown after a successful submission | | `contact-method` | Contact field to show: `email` or `phone`. Defaults to `email` | | `position` | Screen position of the widget trigger button: `bottom_right`, `bottom_left`, `top_right`, `top_left` | | `size` | Size of the widget trigger button in pixels | | `hide-widget` | Hide the trigger button while keeping the form accessible programmatically | ### Programmatic Lead Capture If you're building a custom form or capturing leads as part of another flow, submit directly via JavaScript without rendering the widget: ```javascript theme={null} await window.FairShareSDK.captureLead({ message: "I'm interested in the starter kit", contact: { name: "Dana Whitfield", email: "dana.whitfield@example.com", }, }); ``` Pass the prospect's details inside `contact` — `name`, `email`, and `phone`. Keys outside that shape are dropped silently, so a flat payload submits an empty lead and still resolves successfully. Every field is optional, but send at least one of `email` or `phone` so the lead is reachable. The captured lead is attributed to the same rep that was resolved when the SDK initialized. *** ## Affiliate hydration FairShare can fill affiliate-specific names, images, links, and visibility states into a shared storefront page after it loads. Use the [affiliate hydration guide](/themes/affiliate-hydration) to choose between custom elements, data attributes, and URL sentinels without duplicating a page for every affiliate. *** ## Media Widget ### When to Use Use `` to embed a product video, media file, or an entire playlist without building a custom player. The widget supports both inline and popover display modes, making it suitable for product pages, landing pages, and lightbox-style media galleries. ### Usage ```html theme={null} ``` ### Attributes These are the attributes you'll reach for most often. The widget accepts more than these — sizing, video-playback options, and event-callback hooks among them — so treat this table as a starting point rather than the complete set. | Attribute | Type | Default | Description | | ------------- | ------- | --------- | ------------------------------------------------------------------ | | `playlist-id` | string | — | Slug or ID of the playlist to display | | `media-id` | string | — | Slug or ID of a single media item to display | | `embed-type` | string | `default` | Display mode: `default`, `popover`, `inline`, or `inline-shopping` | | `auto-open` | boolean | `false` | Automatically open the media on page load | Use `playlist-id` to show a browsable collection. Use `media-id` to show one item. If you provide both, `playlist-id` takes precedence. The widget does not recognize `library-id`. For playback events and CTA overrides, see the [FairShare media guide](/sdk/media). ### JavaScript methods Fetch media metadata to build custom players or display additional information alongside the widget: ```javascript theme={null} // Fetch a media library by slug or ID const libraryResponse = await window.FairShareSDK.getLibrary("spring-launch-demos"); const library = libraryResponse.library; // Fetch a single media item by slug or ID const mediaResponse = await window.FairShareSDK.getMedia("unboxing-the-starter-kit"); const media = mediaResponse.media; ``` The methods return response wrappers. Read playlist content from `libraryResponse.library`, including `title` and `library_items`. Read the media record from `mediaResponse.media`. *** ## CSS Customization FairShare components expose CSS custom properties (variables) that you can set in your stylesheet to match your brand. Define them on `:root` to apply them globally: ```css theme={null} :root { --company-color: #3461ff; --ff-body: "Your Custom Font", sans-serif; } ``` | Variable | Description | | ----------------- | -------------------------------------------------------------------------- | | `--company-color` | Primary brand color used in buttons, links, and accents across all widgets | | `--ff-body` | Body font stack applied to widget text | For colors, provide a valid CSS hex, RGB, or HSL value. For fonts, list your custom font first and include a generic family fallback. *** ## Analytics and Events Track events and inspect attribution state from anywhere in your JavaScript code. **Firing a tracked event:** ```javascript theme={null} window.FairShareSDK.trackFairshareEvent({ eventName: "CHECKOUT_STARTED", data: { cart_token: "7Hq2Kd9Rm4bV1nX" }, }); ``` `eventName` accepts exactly one value, `"CHECKOUT_STARTED"`. Any other name is accepted at the call site but never reaches Fluid, and nothing raises an error — so the call looks successful while no event is recorded. The method returns nothing — call it directly rather than awaiting it. **Tracking checkout started:** ```javascript theme={null} window.FairShareSDK.trackCheckoutStarted({ cart_token: "7Hq2Kd9Rm4bV1nX" }); ``` **Inspecting attribution and session state:** ```javascript theme={null} // Returns the resolved attribution record for the current session const attribution = window.FairShareSDK.getAttribution(); // Returns the current session token for cross-system correlation const sessionToken = window.FairShareSDK.getSessionToken(); ``` `getSessionToken()` throws when tracking has not initialized, initialization is still in progress, session creation failed, or the `fluidShop` identifier is invalid. Call it after initialization and handle the error when session state is optional. **Flushing buffered events:** ```javascript theme={null} // Force all queued events to be sent immediately (useful before page unload) await window.FairShareSDK.flushEvents(); // Queue delivery without waiting for the request to finish window.FairShareSDK.flushEvents(false); // Flush using the Beacon API — safe to call during the page unload event window.FairShareSDK.flushEventsWithBeacon(); ``` `flushEvents()` waits for delivery by default. Pass `false` when the caller should continue immediately. *** ## Authentication If your site has its own authentication system, you can pass a JWT to FairShare so the SDK associates cart and order activity with the authenticated user. ```javascript theme={null} // Set the authenticated user's JWT await window.FairShareSDK.setAuthentication("your-jwt-token"); ``` Call `setAuthentication()` after your login flow completes. To clear the session — for example when the user logs out — call `window.FairShareSDK.reset()`.