Build a Shopping Cart with Fluid: Cart API and SDK Guide

Fluid gives you everything you need to build a fully functional shopping cart — a product catalog API, a cart API for managing line items, the FairShare SDK for client-side interactions, and webhooks for real-time event handling. Follow the steps below to go from fetching your first product to completing a checkout.

This guide shows two cart APIs side by side: the direct REST calls below go to the Checkout API, while the @fluid-app FairShare SDK calls the Fluid Public SDK API. Both read and write the same cart records, but their request shapes differ. Drive any one cart through a single surface. See Choosing a cart surface.

Use the built-in <fluid-cart-widget> custom element for a zero-code cart UI. Drop it anywhere in your HTML and it renders a fully styled cart drawer with no additional configuration required.

Fetch Product Details

Before adding anything to a cart, retrieve the product you want to sell. The public product read is unauthenticated — no token required — and resolves a product by its URL slug on your company subdomain:

const response = await fetch(
  'https://{company}.fluid.app/api/v202604/products/scrute-farms-beet-blend'
);

const { product } = await response.json();
console.log(product.title, product.variants);

The product is returned under a product envelope. It carries the display title, pricing, stock status, media, and a variants array — each variant has the id you pass when adding items to the cart. See the Public product by slug endpoint reference for the full response schema.

Create a Cart

Create a new cart for the current session with POST /api/checkout/v2026-04/carts. The body requires fluid_shop (your company subdomain) and country_code (an ISO country code); you can seed the cart with an items array in the same call. Creating a cart is a public operation — it needs no Bearer token.

curl -X POST https://api.fluid.app/api/checkout/v2026-04/carts \
  -H "Content-Type: application/json" \
  -d '{
    "fluid_shop": "acme",
    "country_code": "US"
  }'

The created cart is returned under a cart key, including the cart_token — store this in the user’s session or local storage, since it identifies the cart for every subsequent operation. The hosted checkout link comes back as meta.checkout_url. See the Create a cart endpoint reference for the full response schema.

Add Items to the Cart

You have two approaches for adding items to a cart.Option A — FairShare SDK (recommended for client-side apps)Call addCartItems() with an array of items — each with a variant_id and quantity:

await window.FairShareSDK.addCartItems([
  {
    variant_id: 123,
    quantity: 2
  }
]);

This method posts to the Fluid Public SDK API’s Adds items to cart operation — a different operation from the one Option C calls. See Cart API for the operation behind every SDK cart method.Option B — Declarative HTML attributeAdd a data-fluid-add-to-cart attribute to any button, setting its value to the variant ID. The SDK intercepts clicks and handles the API call automatically:

<button data-fluid-add-to-cart="123456">
  Add to Cart
</button>

Option C — Direct API callUse POST /api/checkout/v2026-04/carts/{cart_token}/items to add line items directly. This example adds one new variant. See the endpoint reference for the current authentication model and the full set of supported batch shapes.

curl -X POST https://api.fluid.app/api/checkout/v2026-04/carts/ct_7Hq2Kd9Rm4bV1nX/items \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "variant_id": 123,
        "quantity": 2
      }
    ]
  }'

See the Add items to cart endpoint reference for the full request and response schema.

Display the Cart Count

Render a live item count anywhere on the page using the fluid-cart-count element. The SDK keeps it in sync automatically as items are added or removed:

<span id="fluid-cart-count">0</span>

You can style this element freely with CSS. The SDK sets its textContent to the current total item count whenever the cart changes.

Handle Checkout

When the customer is ready to purchase, send them to checkout using the SDK or the URL returned in the cart response.Via the FairShare SDK:

// Redirect to the hosted checkout page
window.FairShareSDK.checkout();

// Or retrieve the URL to build your own checkout button
const url = await window.FairShareSDK.getCheckoutUrl();
window.location.href = url;

Via the cart response:The meta.checkout_url returned when you created the cart is always valid. Redirect the user directly to that URL at any point.

Real-Time Cart Updates

Subscribe to cart events using Fluid webhooks to trigger downstream actions — send abandonment emails, update inventory, or sync to your CRM in real time.

Register a Webhook

Create a subscription with POST /api/company/webhooks. A subscription pairs a resource with an event on that resource (the short event name, e.g. updated), the url Fluid delivers to, and an auth_token shared secret you use to verify deliveries:

curl -X POST https://api.fluid.app/api/company/webhooks \
  -H "Authorization: Bearer <your_company_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "resource": "cart",
      "event": "updated",
      "url": "https://yourapp.com/webhooks/cart",
      "active": true,
      "http_method": "post",
      "auth_token": "<a-long-random-secret>"
    }
  }'

Discover the valid resource/event pairs before you register with GET /api/company/webhooks/resources. For registering, managing, verifying, and inspecting webhooks in full, see the Register and handle webhooks guide.

Handle Incoming Events

Every delivery arrives as the envelope { id, identifier, name, timestamp, payload }, with the resource data keyed by its own name inside payload — a cart delivery carries payload.cart. Always verify the signature against your auth_token before trusting a delivery (see the webhooks guide for the exact HMAC scheme):

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/cart', (req, res) => {
  // Verify the X-Fluid-Signature header first — see the webhooks guide.
  const { name, payload } = req.body;
  const cart = payload.cart;

  console.log(`Received ${name} for cart ${cart.cart_token}`);
  // Enqueue the work and acknowledge quickly.

  res.sendStatus(200);
});

app.listen(3000);

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Build a Shopping Cart with Fluid: Cart API and SDK Guide

Real-Time Cart Updates

Register a Webhook

Handle Incoming Events

​Real-Time Cart Updates

​Register a Webhook

​Handle Incoming Events

Real-Time Cart Updates

Register a Webhook

Handle Incoming Events