> ## 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. # Droplets: Extend Fluid with Third-Party Integrations > Droplets are modular third-party integrations for the Fluid platform. Install pre-built apps from the Marketplace or build your own custom Droplet. Droplets are Fluid's integration layer — self-contained apps that connect the Fluid platform to external services, add new functionality to your checkout flow, and expose custom UI inside the Fluid admin. Every Droplet is created by a company (either Fluid itself or a third-party developer), published to the Droplet Marketplace, and installed by merchants with a single click. If the Marketplace doesn't have what you need, you can build your own Droplet using the Fluid API and keep it private or publish it for others to use. ## Two Ways to Use Droplets ### 1. Install from the Marketplace The [Droplet Marketplace](https://admin.fluid.app/droplets) lists all publicly available Droplets. Browse by category, read the description and required permissions, and click **Install** to add a Droplet to your Fluid account. Fluid handles the credential exchange automatically — you don't need to write any code to install a pre-built Droplet. ### 2. Build Your Own If you need a custom integration — whether to connect an internal system, automate a specific workflow, or embed a branded UI inside the checkout — you can create a Droplet using the Fluid API. Once built and tested, you can keep the Droplet private to your own account or submit it to the Marketplace for other Fluid merchants to install. See the [Creating Droplets guide](/guides/creating-droplets) for a full walkthrough of building, testing, and publishing a Droplet. ## How Droplets Work Understanding the lifecycle of a Droplet installation helps you build integrations that are secure and reliable. ### Embed URL Every Droplet defines an `embed_url`. When a merchant opens the Droplet inside the Fluid admin, Fluid renders that URL inside an iframe. This is where you serve your Droplet's configuration UI, dashboards, or any other interface your integration needs. ### Install Webhook and Token Exchange When a company installs your Droplet, Fluid immediately sends a signed `POST` request to your Droplet's `install_webhook_url`. The payload contains a short-lived **exchange token** — a one-time credential you use to prove you received the installation event. Your server must exchange this token within 10 minutes (it is single-use and expires after that window). The token exchange flow looks like this: Fluid sends a signed webhook to your `install_webhook_url` with the company ID and a short-lived exchange token in the payload. Validate the request signature to confirm the request genuinely came from Fluid. Check the `X-Fluid-Shop`, `X-Fluid-Timestamp`, and `X-Fluid-Signature` headers. The signature is an HMAC-SHA256 digest computed over `timestamp.body` (where `timestamp` is the value of `X-Fluid-Timestamp` and `body` is the raw request body), signed with your Droplet's webhook verification secret. Make a `POST` request to `/api/droplet_installations/exchange` with the exchange token. The exchange token is valid for **10 minutes** and is single-use. A successful exchange returns an `authentication_token` (prefixed `dit_`) and a `webhook_verification_token` (prefixed `wvt_`). Persist the `authentication_token` and `webhook_verification_token` securely. Use the `authentication_token` to make authenticated API calls on behalf of the company, and use the `webhook_verification_token` to verify future webhook signatures from Fluid. When a company uninstalls your Droplet, Fluid sends a signed `POST` to your `uninstall_webhook_url`. Revoke and delete the stored credentials for that company when you receive this event. ### Drop Zones Droplets can embed external UI in configured Fluid experiences through **Drop Zones**. See [Embed apps with drop zones](/api/guides/drop-zones) for the Admin, direct Checkout, and FairShare SDK boundaries. For the canonical direct REST reader, use [List drop zones](/api-reference/store/list-drop-zones). ## Token Scopes When you create a Droplet, you declare the API scopes it needs. Fluid displays these scopes to merchants during installation so they understand what access they are granting. Request only the scopes your integration actually requires. | Scope | Access | | -------------- | --------------------------------------------------------------------------- | | `main` | Core company resources including settings and team members | | `prospects` | Prospect and lead data: read and manage prospect records | | `members` | Member accounts: read and manage customer membership data | | `web` | Web and storefront resources including themes and navigation | | `settings` | Account-level settings: read and update shop configuration | | `products` | Product catalog: create, read, update, and delete products and variants | | `orders` | Order management: read orders, update fulfillment status, and issue refunds | | `users` | User accounts: read and manage rep and admin user records | | `website` | Website pages and content: create and update pages, blog posts, and assets | | `header_menus` | Header navigation menus: read and update storefront menu structure | | `payments` | Payment processing: initiate charges, read transaction history | During local development, use [ngrok](https://ngrok.com) to expose your local server to the internet so Fluid can deliver install and uninstall webhooks to your machine. This lets you test the full token exchange flow without deploying to a staging environment. ## Next Steps Ready to build your first Droplet? The [Creating Droplets guide](/guides/creating-droplets) walks you through registering your Droplet, implementing the webhook handler, completing the token exchange, and testing Drop Zone embeds end to end.