Connect member data to a Droplet backend

​

Member API alternative for authenticated applications

​

Use one Droplet selector for applications and widgets

1. Register the receiver. Configure the Droplet’s data_url and securely provision its existing webhook secret on your backend. The backend setup applies to either query target.
2. Install the Droplet. Verify an active installation in the member’s company. A Member API integration does not need a theme-extension ZIP or a UI placement.
3. Define the reads. Implement application-owned operation names and input/result shapes on the receiver. Verify the signature, resolve the signed company and member together, and authorize each read. This connection does not permit backend writes.
4. Query as the member. Use the supported Member API authentication flow and the Droplet’s actual public identifier. Keep member credentials in the authenticated application, validate the returned fields, and clear private results when the member changes or signs out.

​

What the browser helper needs

​

How the data reaches the section

1. The section calls client.query("commissions.summary", {}).
2. The helper obtains same-origin session and CSRF information, then submits the operation and Droplet UUID to Fluid.
3. Fluid checks the live member/site access, member-storefront flag, active Droplet installation and Droplet availability. Extension publication checks apply only to the legacy extension target.
4. Fluid signs the server-derived member and company context, then posts to the Droplet’s registered data_url.
5. Your backend verifies the signature and timestamp, checks the member’s permissions, and returns a JSON object.
6. The helper checks that the login has not changed. Your section renders the object or an empty/error state.

​

Prepare the backend

​

Register the destination and save the secret

{
  "operation": "commissions.summary",
  "params": { "period": "2026-09" },
  "company": { "id": 1842, "fluid_shop": "northwind.fluid.app" },
  "member": {
    "id": "01990000-0000-7000-8000-000000000002",
    "public_id": "01990000-0000-7000-8000-000000000001",
    "external_id": "exigo-4821"
  }
}

​

Verify the raw body

import { verifySignature } from "@fluid-app/droplet-sdk";

const rawBody = Buffer.from(await request.arrayBuffer());
const verification = verifySignature({
  rawBody,
  timestamp: request.headers.get("x-fluid-timestamp"),
  signature: request.headers.get("x-fluid-signature"),
  secret: process.env.FLUID_DROPLET_SECRET ?? "",
});
if (!verification.valid) {
  return new Response("Invalid signature", { status: 401 });
}

const query = JSON.parse(rawBody.toString("utf8"));
// Validate the query, resolve the signed tenant/member, and authorize the operation.

​

Dispatch operations to your own APIs

async function dispatchVerifiedQuery(query, backend) {
  const { company, member, operation, params } = query;
  if (!Number.isSafeInteger(company?.id) || typeof member?.public_id !== "string") {
    throw new Error("Invalid signed identity");
  }
  if (!params || typeof params !== "object" || Array.isArray(params) ||
      Object.keys(params).some((key) => key !== "period")) {
    throw new Error("Invalid parameters");
  }
  const period = params.period;
  if (period !== undefined &&
      (typeof period !== "string" || !/^\d{4}-(0[1-9]|1[0-2])$/.test(period))) {
    throw new Error("Invalid period");
  }
  if (!["commissions.summary", "commissions.history"].includes(operation)) {
    throw new Error("Unknown operation");
  }
  const identity = await backend.resolveMember({
    companyId: company.id,
    memberPublicId: member.public_id,
  });
  if (!identity || identity.canReadCommissions !== true) {
    throw new Error("Member cannot read commissions");
  }
  if (operation === "commissions.summary") {
    return backend.summary(identity, period);
  }
  return { entries: await backend.history(identity, period) };
}

​

Render the result in a section

<section data-commission-example {% droplet_data_attributes %}>
  <h2>Your commissions</h2>
  <p role="status" aria-live="polite">Loading…</p>
  <pre data-output></pre>
  <button type="button">Refresh</button>
</section>

async function mountCommissions(root) {
  const status = root.querySelector('[role="status"]');
  const output = root.querySelector("[data-output]");
  let revision = 0;
  let client;
  try {
    client = await window.Fluid.droplets.createQueryClient(root, {
      dropletUuid: root.dataset.dropletUuid,
      onInvalidate() {
        revision += 1;
        output.textContent = "";
        status.textContent = "Refresh to load member data.";
      }
    });
  } catch {
    if (root.isConnected) status.textContent = "Unable to start. Reload the page to try again.";
    return;
  }
  async function load() {
    const pending = client.query("commissions.summary", {});
    const currentRevision = revision;
    status.textContent = "Loading…";
    try {
      const data = await pending;
      if (revision !== currentRevision || !root.isConnected) return;
      status.textContent = Object.keys(data).length ? "Loaded" : "No commissions yet.";
      output.textContent = Object.keys(data).length ? JSON.stringify(data, null, 2) : "";
    } catch {
      if (revision !== currentRevision || !root.isConnected) return;
      status.textContent = "Unable to load. Sign in or try again.";
      output.textContent = "";
    }
  }
  root.querySelector("button").addEventListener("click", () => void load());
  void load();
}

for (const root of document.querySelectorAll("[data-commission-example]")) {
  void mountCommissions(root);
}

​

Backend errors

​

Builder and CLI previews

​

Place it in the builder or directly in Liquid

{% section 'fluid://extensions/42/sections/commission_summary', id: 'commissions' %}

{% schema %}
{
  "sections": {
    "commissions": {
      "id": "commissions",
      "type": "fluid://extensions/42/sections/commission_summary",
      "settings": {}
    }
  }
}
{% endschema %}

​

Verify the complete connection

​

Instructions for Mist and other AI agents

​

Collect the inputs

​

Build the backend and section together

1. Agree on the operation contract. Write down each operation’s name, allowed parameters, authorized data scope and result object before building the UI. For example, commissions.summary accepts an optional period and returns { "total": "125.00", "currency": "USD" }. These are application-defined fields, not a built-in Fluid commissions API. Implement both the backend handler and the section’s field validation against the same contract.
2. Implement the receiving backend. Use the raw-body verifier before parsing JSON or accessing data. Dispatch only known read operations, resolve the signed company and member together, and check their permissions. Keep data-source credentials on the backend. Return the result object directly, without adding another data envelope.
3. Create or reuse the Droplet. Register the receiver as data_url, and follow the secret setup for your hosting. Use the registration recipe below for a new Droplet. For an existing Droplet, update only the requested fields and verify that its secret is already available to the backend. The embedded admin UI and lifecycle webhook URLs serve different purposes from the data receiver.
4. Author the UI. For a Droplet-owned theme extension, package fluid.extension.toml with type = "theme" and a name, plus sections/commission_summary/index.liquid. Give the section target: "section", settings and a presets entry. Use a section or app block for member pages; head/body app embeds are not injected there. Follow the extension package guide.
5. Connect each rendered placement. Use {% droplet_data_attributes %} inside a Droplet extension, or explicitly configure the known public Droplet UUID on a native/custom root, then await window.Fluid.droplets.createQueryClient(root, { dropletUuid: root.dataset.dropletUuid, onInvalidate }). Use the complete section script as the starting point. Mount each root once, give each placement its own client, and query operation names rather than backend URLs. The global loads the SDK; you still supply and load your section’s JavaScript.
6. Render and clear private content. Handle initialization, loading, empty and error states; validate the returned fields and render them with escaped output. Clear every private value in onInvalidate, and prevent an older asynchronous result from repopulating cleared content. Call client.destroy() when your application tears down the placement. Use sample data in previews; never show sample commissions as a successful live query.
7. Install the Droplet and place the UI. A Droplet extension is optional for UUID queries. When using one, follow deployment without the admin: upload the complete ZIP, wait for publication, verify an active installation in the member-site company, and retrieve the real extension_uri. For that extension, read the existing member template, then merge a literal section tag and matching schema entry using that URI and a stable placement ID. Preserve unrelated sections and settings. Push and publish through the theme workflow, then test the live account-host page.

​

Register a new Droplet for this workflow

{
  "droplet": {
    "title": "Northwind Commissions",
    "embed_url": "https://commissions.northwind.example/admin",
    "data_url": "https://commissions.northwind.example/member-data"
  }
}

​

Avoid these substitutions

• Do not fetch the Droplet backend directly from section JavaScript or add a new Fluid route for each operation. The section calls the global client; your backend dispatches operations at its registered endpoint.
• Do not use a Liquid member ID, an ID in params, or the shop header alone as authentication. Resolve identity from the verified signed body and apply backend permissions.
• Do not embed the webhook secret, an installation token or data-source credentials in Liquid, JavaScript, section settings or the ZIP. Do not store private responses in persistent browser storage or shared caches.
• Do not build a sandboxed widget package for this workflow. These UIs are Liquid sections, app blocks, native widgets or custom Liquid roots, and they share the page with other scripts.
• Do not bypass a missing global client by inventing a CDN import or sending raw private-data requests. Check deployment and flag availability, and show an unavailable state until the supported connection is available.

​

Verification and completion report

​

Reusable task brief

Create or update a Fluid Droplet and a member-page section using
/themes/member-storefront/droplet-data#instructions-for-mist-and-other-ai-agents.

Use the supplied environment, owner company, member-site company, theme,
page, backend and operation contract. Obtain missing inputs before making
assumptions about identities or permissions. Keep secret values out of output.

Build the signed read-only backend receiver and the chosen Liquid UI.
Use droplet_data_attributes inside a Droplet extension, or configure the known
public Droplet UUID explicitly on other roots. Await
window.Fluid.droplets.createQueryClient with dropletUuid for each placement. Implement private-output cleanup and preview sample states.
Install the Droplet and configure its actual public UUID. Publish a theme
extension only when using one for the UI; preserve existing page content.

Verify with real member sessions and backend permission tests. Return the
artifact identifiers, operation contracts, deployment states, test evidence
and remaining blockers. Do not mark preview-only work as live-tested.