widgets

Fluid SDK API Documentation (0.0.6)

OpenAPI documentation for Fluid's SDK API

Download OpenAPI description
public.json
public.yaml
Overview
E-mail support@fluid.app
License MIT
Languages
Servers
Mock server
https://docs.fluid.app/_mock/docs/apis/public/
Production API server
https://api.fluid.app/
Local development server
https://api.fluid.test/

Orders

Operations

affiliate

Operations

carts

Operations

checkout

Operations

enrollment-packs

Operations

events

Operations

lead

Operations

page

Operations

url

Operations

fingerprint

Operations

media

Operations

playlist

Operations

product

Operations

session

Operations

settings

Operations

widgets

Operations

Retrieve banner widget

Request

Bodyapplication/json
urlstringrequired
Example: "https://example.com/products/123"
metadataobject(RequestMetadata)required
metadata.​fluid_shopstringrequired
Example: "myshop"
metadata.​fluid_sessionstring(/\Afs_[0-9A-Za-z&&[^0OIl]]{22}\z/)required
Example: "fs_szwdDuRbqEe7AV7sXk7vVq"
metadata.​fluid_localestring(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​fluid_journeystring
metadata.​attributionAttributionEmail (object) or AttributionUsername (object) or AttributionSharedGuid (object) or AttributionFluidRepId (object) or AttributionExternalId (object)(Attribution)
Any of:
curl -i -X POST \
  https://docs.fluid.app/_mock/docs/apis/public/api/public/v2025-06/widgets/banners \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/products/123",
    "metadata": {
      "fluid_shop": "myshop",
      "fluid_session": "fs_szwdDuRbqEe7AV7sXk7vVq",
      "fluid_locale": "en_US",
      "fluid_journey": "string",
      "attribution": {
        "email": "salesrep@example.com"
      }
    }
  }'

Responses

banner widget found

Bodyapplication/json
statusnumberrequired
Example: 200
bannerBannerWidget (object) or nullrequired
One of:

A banner widget

banner.​placementstringrequired

Where the banner appears on the page

Enum"top""bottom"
banner.​behaviorstringrequired

How the banner behaves on the page

Enum"persistent""dismissible""sticky"
banner.​contentobjectrequired
banner.​content.​banner_textstring
Example: "Welcome to our site!"
banner.​content.​button_textstring
Example: "Learn More"
banner.​content.​button_urlstring(uri)
Example: "https://example.com/learn"
banner.​stylesobjectrequired
banner.​styles.​background_colorstring
Example: "#ffffff"
banner.​styles.​text_colorstring
Example: "#000000"
banner.​styles.​border_radiusstring
Example: "8px"
metadataobject(ResponseMetadata)required
metadata.​fluid_shopstringrequired
metadata.​fluid_sessionstringrequired
metadata.​fluid_localestring or null(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​request_uuidstring(uuid)required
metadata.​timestampstringrequired
Response
application/json
{
  "status": 200,
  "banner": {
    "placement": "top",
    "behavior": "persistent",
    "content": { … },
    "styles": { … }
  },
  "metadata": {
    "fluid_shop": "string",
    "fluid_session": "string",
    "fluid_locale": "en_US",
    "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
    "timestamp": "string"
  }
}

Retrieve cart widget

Request

Bodyapplication/json
urlstringrequired
Example: "https://example.com/products/123"
metadataobject(RequestMetadata)required
metadata.​fluid_shopstringrequired
Example: "myshop"
metadata.​fluid_sessionstring(/\Afs_[0-9A-Za-z&&[^0OIl]]{22}\z/)required
Example: "fs_szwdDuRbqEe7AV7sXk7vVq"
metadata.​fluid_localestring(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​fluid_journeystring
metadata.​attributionAttributionEmail (object) or AttributionUsername (object) or AttributionSharedGuid (object) or AttributionFluidRepId (object) or AttributionExternalId (object)(Attribution)
Any of:
curl -i -X POST \
  https://docs.fluid.app/_mock/docs/apis/public/api/public/v2025-06/widgets/carts \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/products/123",
    "metadata": {
      "fluid_shop": "myshop",
      "fluid_session": "fs_szwdDuRbqEe7AV7sXk7vVq",
      "fluid_locale": "en_US",
      "fluid_journey": "string",
      "attribution": {
        "email": "salesrep@example.com"
      }
    }
  }'

Responses

cart widget found

Bodyapplication/json
statusnumberrequired
Example: 200
cartCartWidget (object) or nullrequired
One of:

A cart widget

cart.​placementstringrequired

Which side of the screen the cart slides out from

Enum"right""left"
cart.​contentobjectrequired
cart.​stylesobjectrequired
cart.​triggerobjectrequired
metadataobject(ResponseMetadata)required
metadata.​fluid_shopstringrequired
metadata.​fluid_sessionstringrequired
metadata.​fluid_localestring or null(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​request_uuidstring(uuid)required
metadata.​timestampstringrequired
Response
application/json
{
  "status": 200,
  "cart": {
    "placement": "right",
    "content": {},
    "styles": {},
    "trigger": {}
  },
  "metadata": {
    "fluid_shop": "string",
    "fluid_session": "string",
    "fluid_locale": "en_US",
    "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
    "timestamp": "string"
  }
}

Retrieve chat widget

Request

Bodyapplication/json
urlstringrequired
Example: "https://example.com/products/123"
metadataobject(RequestMetadata)required
metadata.​fluid_shopstringrequired
Example: "myshop"
metadata.​fluid_sessionstring(/\Afs_[0-9A-Za-z&&[^0OIl]]{22}\z/)required
Example: "fs_szwdDuRbqEe7AV7sXk7vVq"
metadata.​fluid_localestring(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​fluid_journeystring
metadata.​attributionAttributionEmail (object) or AttributionUsername (object) or AttributionSharedGuid (object) or AttributionFluidRepId (object) or AttributionExternalId (object)(Attribution)
Any of:
curl -i -X POST \
  https://docs.fluid.app/_mock/docs/apis/public/api/public/v2025-06/widgets/chats \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/products/123",
    "metadata": {
      "fluid_shop": "myshop",
      "fluid_session": "fs_szwdDuRbqEe7AV7sXk7vVq",
      "fluid_locale": "en_US",
      "fluid_journey": "string",
      "attribution": {
        "email": "salesrep@example.com"
      }
    }
  }'

Responses

chat widget found

Bodyapplication/json
statusnumberrequired
Example: 200
chatChatWidget (object) or nullrequired
One of:

A chat widget

chat.​contentobjectrequired
chat.​stylesobjectrequired
chat.​triggerobjectrequired
chat.​lead_captureobjectrequired
metadataobject(ResponseMetadata)required
metadata.​fluid_shopstringrequired
metadata.​fluid_sessionstringrequired
metadata.​fluid_localestring or null(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​request_uuidstring(uuid)required
metadata.​timestampstringrequired
Response
application/json
{
  "status": 200,
  "chat": {
    "content": {},
    "styles": {},
    "trigger": {},
    "lead_capture": {}
  },
  "metadata": {
    "fluid_shop": "string",
    "fluid_session": "string",
    "fluid_locale": "en_US",
    "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
    "timestamp": "string"
  }
}

Retrieve popup widget

Request

Bodyapplication/json
urlstringrequired
Example: "https://example.com/products/123"
metadataobject(RequestMetadata)required
metadata.​fluid_shopstringrequired
Example: "myshop"
metadata.​fluid_sessionstring(/\Afs_[0-9A-Za-z&&[^0OIl]]{22}\z/)required
Example: "fs_szwdDuRbqEe7AV7sXk7vVq"
metadata.​fluid_localestring(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​fluid_journeystring
metadata.​attributionAttributionEmail (object) or AttributionUsername (object) or AttributionSharedGuid (object) or AttributionFluidRepId (object) or AttributionExternalId (object)(Attribution)
Any of:
curl -i -X POST \
  https://docs.fluid.app/_mock/docs/apis/public/api/public/v2025-06/widgets/popups \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/products/123",
    "metadata": {
      "fluid_shop": "myshop",
      "fluid_session": "fs_szwdDuRbqEe7AV7sXk7vVq",
      "fluid_locale": "en_US",
      "fluid_journey": "string",
      "attribution": {
        "email": "salesrep@example.com"
      }
    }
  }'

Responses

popup widget found

Bodyapplication/json
statusnumberrequired
Example: 200
popupPopupWidget (object) or nullrequired
One of:

A popup widget

popup.​placementstringrequired

Where the popup should be displayed

Value"modal"
popup.​contentobjectrequired
popup.​stylesobjectrequired
popup.​behaviorstringrequired

When the popup should be displayed

Value"timer"
popup.​lead_captureobjectrequired

Lead capture configuration for the popup

metadataobject(ResponseMetadata)required
metadata.​fluid_shopstringrequired
metadata.​fluid_sessionstringrequired
metadata.​fluid_localestring or null(/\A[a-z]{2}_[A-Z]{2}\z/)
Example: "en_US"
metadata.​request_uuidstring(uuid)required
metadata.​timestampstringrequired
Response
application/json
{
  "status": 200,
  "popup": {
    "placement": "modal",
    "content": {},
    "styles": {},
    "behavior": "timer",
    "lead_capture": {}
  },
  "metadata": {
    "fluid_shop": "string",
    "fluid_session": "string",
    "fluid_locale": "en_US",
    "request_uuid": "a699086b-c336-457e-9191-0c825d6efbc8",
    "timestamp": "string"
  }
}