Cart

The FairShare SDK provides a complete set of cart management functions for adding items, managing quantities, handling subscriptions, and processing checkout.

Quick Start

// Add item to cart
await window.FairShareSDK.addCartItems(12345, { quantity: 1 });

// Open the cart drawer
window.FairShareSDK.openCart();

// Proceed to checkout
await window.FairShareSDK.checkout();

Or use HTML data attributes without JavaScript:

<button data-fluid-add-to-cart="12345">Add to Cart</button>
<button data-fluid-cart="open">View Cart</button>

Control the cart drawer/widget programmatically:

// Open cart
window.FairShareSDK.openCart();
// or: window.FairShareSDK.cart.control.open();

// Close cart
window.FairShareSDK.closeCart();
// or: window.FairShareSDK.cart.control.close();

// Toggle cart
window.FairShareSDK.toggleCart();
// or: window.FairShareSDK.cart.control.toggle();

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>

Adding Items

JavaScript API

// Add single item
await window.FairShareSDK.addCartItems(12345, { quantity: 1 });

// Add with subscription
await window.FairShareSDK.addCartItems(12345, {
  quantity: 1,
  subscribe: true
});

// Add multiple items
await window.FairShareSDK.addCartItems([
  { variant_id: 12345, quantity: 2 },
  { variant_id: 67890, quantity: 1 }
]);

// Add a dynamic bundle with bundled items
await window.FairShareSDK.addCartItems(278318, {
  quantity: 1,
  bundled_items: [
    { variant_id: 39325, quantity: 1 },
    { variant_id: 35376, quantity: 1 },
    { variant_id: 11311, quantity: 1 },
  ]
});

HTML Data Attributes

<!-- Basic add to cart -->
<button data-fluid-add-to-cart="12345">Add to Cart</button>

<!-- With quantity -->
<button data-fluid-add-to-cart="12345" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- With subscription -->
<button data-fluid-add-to-cart="12345" data-fluid-subscribe="true">
  Subscribe
</button>

<!-- With specific subscription plan -->
<button
  data-fluid-add-to-cart="12345"
  data-fluid-subscription-plan-id="99"
>
  Subscribe with Plan
</button>

<!-- Add multiple items -->
<button data-fluid-add-to-cart="12345,67890">Add Both</button>

<!-- Dynamic bundle with bundled items -->
<button
  data-fluid-add-to-cart="278318"
  data-fluid-bundled-items='[{"variant_id":39325,"quantity":1},{"variant_id":35376,"quantity":1},{"variant_id":11311,"quantity":1}]'
>
  Add Bundle to Cart
</button>

<!-- Control cart opening after add -->
<button
  data-fluid-add-to-cart="12345"
  data-fluid-open-cart-after-add="false"
>
  Add Silently
</button>

Enrollment Packs

Add enrollment/starter packs to the cart:

// Simple enrollment pack
await window.FairShareSDK.addEnrollmentPack(539);

// Enrollment pack with bundle selections
await window.FairShareSDK.addEnrollmentPack(539, {
  bundleSelections: [
    {
      variant_id: 278318,
      bundled_items: [
        { variant_id: 39325, quantity: 1 },
        { variant_id: 35376, quantity: 1 },
        { variant_id: 11311, quantity: 1 },
      ]
    }
  ]
});

HTML

<button data-fluid-add-enrollment-pack="100">Add Enrollment Pack</button>

<!-- Enrollment pack with bundle selections -->
<button
  data-fluid-add-enrollment-pack="539"
  data-fluid-bundle-selections='[{"variant_id":278318,"bundled_items":[{"variant_id":39325,"quantity":1},{"variant_id":35376,"quantity":1},{"variant_id":11311,"quantity":1}]}]'
>
  Add Enrollment Pack
</button>

<!-- Combined: Enrollment Pack + Items -->
<button data-fluid-add-combined="100+12345,67890">Add Pack + Items</button>

Data Attributes Reference

All available data attributes for no-code HTML integration:

Attribute	Type	Description
`data-fluid-add-to-cart`	string	Variant ID(s), comma-separated for multiple
`data-fluid-quantity`	string	Quantity (default: 1)
`data-fluid-subscribe`	string	`"true"` or `"false"`, comma-separated for multiple
`data-fluid-subscription-plan-id`	string	Subscription plan ID
`data-fluid-bundled-items`	JSON string	Array of `{ variant_id, quantity }` for dynamic bundles
`data-fluid-open-cart-after-add`	string	Set to `"false"` to prevent cart from opening
`data-fluid-add-enrollment-pack`	string	Enrollment pack ID
`data-fluid-bundle-selections`	JSON string	Array of `{ variant_id, bundled_items }` for enrollment pack bundles

Managing Cart Items

Update Quantities

await window.FairShareSDK.updateCartItems([
  { variant_id: 12345, quantity: 5 }
]);

Decrease Quantity

await window.FairShareSDK.decrementCartItem(variantId, { quantity: 1 });

Remove Item

await window.FairShareSDK.removeCartItemById(itemId);

Clear Cart

await window.FairShareSDK.clearCart();

Subscriptions

Manage subscription status for cart items:

// Add subscription to item
await window.FairShareSDK.subscribeCartItem(itemId, subscriptionPlanId);

// Remove subscription from item
await window.FairShareSDK.unsubscribeCartItem(itemId);

Reading Cart Data

Get Cart from API

const cart = await window.FairShareSDK.getCart();
console.log('Items:', cart.items.length);
console.log('Total:', cart.total);

Get Cached Cart (No API Call)

const localCart = window.FairShareSDK.getLocalCart();

Get Item Count

const count = window.FairShareSDK.getCartItemCount();

Auto-Updating Item Count Display

The SDK automatically updates any element with id="fluid-cart-count":

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

Checkout

Standard Checkout

await window.FairShareSDK.checkout();

Get Checkout URL

const url = window.FairShareSDK.getCheckoutUrl();
window.open(url, '_blank');

Custom Checkout Handler

Override the default checkout behavior:

window.FairShareSDK.setOnCheckout(async () => {
  const cart = await window.FairShareSDK.getCart();

  if (cart.items.length === 0) {
    alert('Your cart is empty!');
    return;
  }

  // Custom checkout logic
  window.location.href = '/custom-checkout';
});

// Get current handler
const handler = window.FairShareSDK.getOnCheckout();

Cart Loading Events

Listen for cart loading states in your application:

window.addEventListener("CART_LOADING_START", (e) => {
  console.log("Loading started:", e.detail);
  // Show loading spinner
});

window.addEventListener("CART_LOADING_END", (e) => {
  console.log("Loading ended:", e.detail);
  // Hide loading spinner
});

Cart Operation Events

Every cart mutation also emits a uniform CART_OPERATION_SUCCESS / CART_OPERATION_ERROR window event. The CDN can render a built-in toast for them and show a loading spinner on add-to-cart buttons — both are opt-in (off by default), enabled with data-fluid-toast="true" and data-fluid-button-loading="true" on the Fluid script tag. The events fire regardless.

window.addEventListener("CART_OPERATION_ERROR", (e) => {
  console.log(e.detail.operation, "failed:", e.detail.message);
});

See Cart Operation Events for the event payloads, the built-in toast's data-fluid-toast-* configuration, and the button loading helpers.

External Cart Handoff

Adopt a cart created by an external system (e.g., a companion app or backend service):

URL Parameter (Recommended for Redirects)

No JavaScript needed — redirect users with a cart_token query parameter:

https://shop.example.com/?cart_token=TOKEN

The SDK automatically detects the parameter, validates the cart, saves it, and cleans the token from the URL.

Programmatic API

const cart = await window.FairShareSDK.setCartToken("TOKEN");

Both methods validate the token via API, subscribe to Pusher realtime updates, and dispatch events so cart widgets react immediately.

Cart Settings

Customize cart widget behavior:

// Set cart settings
window.FairShareSDK.setCartSettings({
  // your settings
});

// Get current settings
const settings = window.FairShareSDK.getCartSettings();

// Clear settings
window.FairShareSDK.clearCartSettings();

API Reference

Cart Operations

Function	Description
getCart	Fetch cart from API
refreshCart	Fetch cart from API and update all widgets
getLocalCart	Get cart from cache (no API call)
createCart	Create new empty cart
clearCart	Remove all items from cart
getCartItemCount	Get total item count
setCartToken	Adopt an externally-created cart

Adding Items

Function	Description
addCartItems	Add one or more items to cart
addEnrollmentPack	Add enrollment pack to cart

Updating Items

Function	Description
updateCartItems	Update item quantities
updateCartItemVariant	Change item variant
decrementCartItem	Decrease item quantity
removeCartItemById	Remove item from cart

Subscriptions

Function	Description
subscribeCartItem	Add subscription to item
unsubscribeCartItem	Remove subscription from item

Checkout

Function	Description
checkout	Proceed to checkout
getCheckoutUrl	Get checkout URL without redirecting
setOnCheckout	Set custom checkout handler

Function	Description
openCart	Open the cart drawer
closeCart	Close the cart drawer
toggleCart	Toggle cart open/closed

Cart Settings

Function	Description
setCartSettings	Set cart widget settings
getCartSettings	Get current cart settings
clearCartSettings	Clear cart settings

Cart

Quick Start

Cart Widget Control

HTML Controls

Adding Items

JavaScript API

HTML Data Attributes

Enrollment Packs

HTML

Data Attributes Reference

Managing Cart Items

Update Quantities

Decrease Quantity

Remove Item

Clear Cart

Subscriptions

Reading Cart Data

Get Cart from API

Get Cached Cart (No API Call)

Get Item Count

Auto-Updating Item Count Display

Checkout

Standard Checkout

Get Checkout URL

Custom Checkout Handler

Cart Loading Events

Cart Operation Events

External Cart Handoff

URL Parameter (Recommended for Redirects)

Programmatic API

Cart Settings

API Reference

Cart Operations

Adding Items

Updating Items

Subscriptions

Checkout

Cart Widget Control

Cart Settings

Was this helpful?