FairShare Cart API: JavaScript Methods and HTML Controls

<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>

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

<!-- Add a specific quantity -->
<button data-fluid-add-to-cart="123456" data-fluid-quantity="2">Add 2 to Cart</button>

<!-- The cart panel opens after an add by default; keep it closed -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-open-cart-after-add="false"
>
  Add Quietly
</button>

<!-- Add as a subscription -->
<button data-fluid-add-to-cart="123456" data-fluid-subscribe="true">
  Subscribe &amp; Add
</button>

<!-- Add an enrollment pack by pack ID -->
<button data-fluid-add-enrollment-pack="42">Add Enrollment Pack</button>

<!-- Several variants in one click; subscribe per item, in the same order -->
<button
  data-fluid-add-to-cart="123456,123457"
  data-fluid-subscribe="true,false"
>
  Add Both
</button>

<!-- Subscribe on a specific plan. A plan ID implies subscribe="true" -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-subscription-plan-id="7"
>
  Subscribe Monthly
</button>

<!-- A bundle product with the items the shopper chose -->
<button
  data-fluid-add-to-cart="123456"
  data-fluid-bundled-items='[{"variant_id": 2001, "quantity": 1}, {"variant_id": 2002, "quantity": 2}]'
>
  Add Bundle
</button>

<!-- An enrollment pack whose products need bundle choices -->
<button
  data-fluid-add-enrollment-pack="42"
  data-fluid-bundle-selections='[{"variant_id": 123456, "bundled_items": [{"variant_id": 2001, "quantity": 1}]}]'
>
  Join with Bundle
</button>

<!-- An enrollment pack plus extra items: "packId+variantId,variantId" -->
<button data-fluid-add-combined="42+123456,123457">Join and Add Items</button>

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

const cart = await window.FairShareSDK.whenCartSettled();
if (cart?.population_status === "complete") {
  renderLines(cart.items);
}

// Don't: this replaces the shopper's cart just to read a value.
// await window.FairShareSDK.createCart();
// const country = window.FairShareSDK.getCountryCode();

// Do: read the value directly.
const country = window.FairShareSDK.getCountryCode();
const language = window.FairShareSDK.getLanguage();

// Don't: the cart can still be filling, so it can have no items yet.
window.FairShareSDK.addCartItems(48291);
renderLines(window.FairShareSDK.getLocalCart()?.items ?? []);

// Do: use the cart the add resolves with.
const cart = await window.FairShareSDK.addCartItems(48291);
if (cart) renderLines(cart.items);

// Fetch the current cart from the server
const cart = await window.FairShareSDK.getCart();

// Read the cart from local state without a network request
const localCart = window.FairShareSDK.getLocalCart();

// Get the total number of items in the cart
const itemCount = window.FairShareSDK.getCartItemCount();

// Fetch fresh state and notify every cart widget
const refreshedCart = await window.FairShareSDK.refreshCart();

const adoptedCart =
  await window.FairShareSDK.setCartToken("7Hq2Kd9Rm4bV1nX");

// Shorthand: add one variant with optional quantity and subscription options
await window.FairShareSDK.addCartItems(123, {
  quantity: 2,
  subscribe: true,
  subscription_plan_id: 642,
});

// Array form: add a configured bundle
await window.FairShareSDK.addCartItems([
  {
    variant_id: 278318,
    quantity: 1,
    bundled_items: [
      {
        variant_id: 39325,
        quantity: 1,
        product_bundle_group_id: 3301,
        subscription: true,
        subscription_plan_id: 642,
      },
    ],
  },
]);

// Decrement an item's quantity; pass options.quantity to control the decrement amount
await window.FairShareSDK.decrementCartItem(123, { quantity: 1 });

// Remove an item by its cart item ID
await window.FairShareSDK.removeCartItemById(456);

// Replace quantities for one or more items
await window.FairShareSDK.updateCartItems([
  { variant_id: 123, quantity: 3 },
]);

// Replace the variant on one cart line
await window.FairShareSDK.updateCartItemVariant({
  itemId: 456,
  variantId: 789,
});

// Clear the SDK's local cart state
await window.FairShareSDK.clearCart();

// Create a new, empty cart. This replaces the shopper's stored cart,
// so don't call it to read data such as the country.
await window.FairShareSDK.createCart();

// Convert an existing cart item to a subscription
await window.FairShareSDK.subscribeCartItem(itemId, subscriptionPlanId);

// Remove the subscription from a cart item (keeps the item as a one-time purchase)
await window.FairShareSDK.unsubscribeCartItem(itemId);

await window.FairShareSDK.addEnrollmentPack(42);

await window.FairShareSDK.addEnrollmentPack(42, {
  bundleSelections: [
    {
      variant_id: 321,
      bundled_items: [
        {
          variant_id: 654,
          quantity: 1,
          display_to_customer: true,
          subscription: false,
        },
      ],
    },
  ],
});

// Redirect the shopper to the Fluid checkout page
await window.FairShareSDK.checkout();

// Get the checkout URL without redirecting (useful for building custom checkout buttons)
const checkoutUrl = window.FairShareSDK.getCheckoutUrl();

window.FairShareSDK.setOnCheckout(() => {
  window.location.assign("/custom-checkout");
});

const checkoutHandler = window.FairShareSDK.getOnCheckout();

window.FairShareSDK.cart.control.open();
window.FairShareSDK.cart.control.close();
window.FairShareSDK.cart.control.toggle();

window.FairShareSDK.cart.settings.set({
  hideWidget: true,        // Hide the floating cart button
  position: "top_left",   // bottom_right | bottom_left | top_right | top_left
  size: 80,               // Button diameter in pixels
  placement: "left",      // Sidebar placement: left or right
  primaryColor: "#ff6b35",
  secondaryColor: "#2d3748",
  xMargin: 20,            // Horizontal margin from screen edge (px)
  yMargin: 50,            // Vertical margin from screen edge (px)
});

const cartSettings = window.FairShareSDK.cart.settings.get();

window.FairShareSDK.cart.settings.clear();

// Fetch settings from the server and cache them
await window.FairShareSDK.fetchSettings();

// Return cached settings without a network request
const settings = window.FairShareSDK.getSettings();

// Return cached settings if available, otherwise fetch from the server
const settings = await window.FairShareSDK.getOrFetchSettings();

// Update locale settings for the current session
await window.FairShareSDK.updateLocaleSettings({ language: "en", country: "US" });

// Get the active country code
const country = window.FairShareSDK.getCountryCode();

// Get the active language code
const language = window.FairShareSDK.getLanguage();

const cartEvents = [
  "CREATE_CART",
  "ADD_TO_CART",
  "UPDATE_CART_ITEM",
  "REMOVE_FROM_CART",
];

function updateCartSummary(event) {
  const cart = event.detail?.cart ?? window.FairShareSDK.getLocalCart();
  if (!cart) return;

  document.querySelector("#cart-summary-count").textContent =
    String(window.FairShareSDK.getCartItemCount());
}

cartEvents.forEach((name) => {
  window.addEventListener(name, updateCartSummary);
});

// Remove these listeners when your page or component is torn down.
function stopListeningToCart() {
  cartEvents.forEach((name) => {
    window.removeEventListener(name, updateCartSummary);
  });
}

window.addEventListener("CART_OPERATION_SUCCESS", (event) => {
  console.log(event.detail.operation, "succeeded");
});

window.addEventListener("CART_OPERATION_ERROR", (event) => {
  console.error(event.detail.operation, event.detail.message);
});

window.addEventListener("CART_POPULATION_FAILED", (event) => {
  const { apiMessage } = event.detail;
  document.querySelector("#cart-notice").textContent =
    apiMessage ?? "We couldn't add those items. Try again.";
});

// Fire an event into the Fluid attribution pipeline. `eventName` accepts exactly
// one value, "CHECKOUT_STARTED"; any other name never reaches Fluid and raises
// no error. Returns nothing — do not await it.
window.FairShareSDK.trackFairshareEvent({
  eventName: "CHECKOUT_STARTED",
  data: { cart_token: "7Hq2Kd9Rm4bV1nX" },
});

// Track that a checkout flow has started
window.FairShareSDK.trackCheckoutStarted({ cart_token: "7Hq2Kd9Rm4bV1nX" });

// Get the attribution record resolved from the current page URL
const attribution = window.FairShareSDK.getAttribution();

// Get the current session token for cross-system correlation
const sessionToken = window.FairShareSDK.getSessionToken();

// Force all queued events to be sent immediately (e.g., before page unload)
await window.FairShareSDK.flushEvents();

// Flush buffered events using the Beacon API (safe to call during page unload)
window.FairShareSDK.flushEventsWithBeacon();

await window.FairShareSDK.captureLead({
  message: "I'm interested in the starter kit",
  contact: {
    name: "Dana Whitfield",
    email: "dana.whitfield@example.com",
  },
});