Skip to main content
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 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 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:
1

Receive the install webhook

Fluid sends a signed webhook to your install_webhook_url with the company ID and a short-lived exchange token in the payload.
2

Verify the webhook signature

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.
3

Exchange the token

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_).
4

Store the credentials

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 for the Admin, direct Checkout, and FairShare SDK boundaries. For the canonical direct REST reader, use 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.
During local development, use ngrok 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 walks you through registering your Droplet, implementing the webhook handler, completing the token exchange, and testing Drop Zone embeds end to end.