> ## 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. # Install the FairShare SDK on Any Website in Minutes > Add the FairShare SDK to any website with a single script tag. Configure your shop ID, attribution settings, and optional real-time updates. Installing FairShare takes one script tag. Once the tag is on your page, the SDK bootstraps itself, resolves attribution, and makes the full JavaScript API available under `window.FairShareSDK`. Everything else — cart widgets, lead capture, media — activates as soon as you add the relevant HTML elements or call the API. Place the script tag inside your `` element so attribution resolves before the rest of the page renders. This prevents a flash of un-attributed content and ensures cart widgets appear without delay. ## Basic Installation Add the following snippet to every page where you want FairShare to run. Replace `your-shop-id` with the shop identifier from your Fluid dashboard. ```html theme={null} ``` That's the minimum required configuration. The `id="fluid-cdn-script"` attribute must be present — the SDK uses it to read configuration at runtime. ## Configuration Options Customize SDK behavior by adding `data-*` attributes to the script tag. Only `data-fluid-shop` is required; all other attributes are optional. | Attribute | Description | Required | | ------------------------- | ------------------------------------------------------- | -------- | | `data-fluid-shop` | Your FairShare shop identifier | Yes | | `data-share-guid` | Attribution override — share GUID from a rep link | No | | `data-fluid-rep-id` | Attribution override — numeric Fluid rep ID | No | | `data-email` | Attribution override — rep email address | No | | `data-username` | Attribution override — rep Fluid username | No | | `data-external-id` | Attribution override — your own external rep identifier | No | | `data-fluid-api-base-url` | Custom API endpoint URL for enterprise setups | No | | `data-debug` | Enable verbose debug logging | No | | `data-pusher-enabled` | Enable real-time async cart updates via Pusher | No | ## Attribution Override By default, FairShare reads attribution signals from the current URL and stored cookies. You can override this by setting one or more attribution attributes directly on the script tag. Use this pattern when: * You're building a **rep-specific landing page** and want to hard-code credit to a known rep. * Your site runs **outside the Fluid ecosystem** and you're passing rep identity from your own user session. * You need to **test attribution** for a specific rep without using a share link. FairShare resolves the first signal that matches a known rep and ignores the rest, following this priority order: `share-guid` → `fluid-rep-id` → `email` → `username` → `external-id`. **Using a share GUID** (recommended for rep-specific share links): ```html theme={null} ``` **Using a numeric rep ID**: ```html theme={null} ``` **Using an email address**: ```html theme={null} ``` **Using a username**: ```html theme={null} ``` **Using an external ID** (when you manage rep identifiers in your own system): ```html theme={null} ``` ## Enabling Real-Time Updates Add `data-pusher-enabled="true"` to receive instant cart updates over a WebSocket connection. Without this attribute, cart state refreshes only on explicit API calls. With it, any change to the cart — whether triggered by this page or another tab — propagates immediately. ```html theme={null} ``` This is especially useful on cart pages or checkout flows where stale quantity counts would cause a poor experience. ## Custom API Endpoint Enterprise accounts may need to route SDK traffic to a dedicated API host. Set `data-fluid-api-base-url` to your custom endpoint and all SDK requests will use it instead of the default Fluid API. ```html theme={null} ``` ## Debug Mode Set `data-debug="true"` to enable verbose logging in the browser console. Debug mode prints attribution resolution steps, API request details, and widget lifecycle events. Disable it before going to production. ```html theme={null} ``` ## Manual Initialization (SPA / React) In single-page applications the `` script tag may execute before your framework has mounted the component tree. If you need to initialize FairShare after a dynamic render, call `initializeFluid()` directly: ```javascript theme={null} window.FairShareSDK.initializeFluid({ fluidShop: "your-shop-id", debug: true, }); ``` `initializeFluid()` initializes the full SDK, including cart and widget features. `initializeFairshare()` is a lower-level asynchronous initializer for tracking and attribution only. Use `initializeFluid()` for storefront integrations unless you intentionally need only the tracking layer. Call `initializeFluid()` once per session — typically in your root component's mount lifecycle hook (`useEffect` with an empty dependency array in React, `onMounted` in Vue, `ngOnInit` in Angular). The script tag must still be present in the document, but you can omit the `data-fluid-shop` attribute and provide it here instead. To reset the SDK state — for example, when a user logs out — call: ```javascript theme={null} window.FairShareSDK.reset(); ``` `reset()` clears stored SDK data, the local cart, real-time connections, and initialization state. If you only need to clear tracking and attribution data, do not use `resetFairshare()` as a partial reset. FairShare and Fluid share browser storage, so that method also removes stored cart, settings, and authentication data.