{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sdk/sidebars.yaml"},"props":{"codeGuideFiles":[],"dynamicMarkdocComponents":[],"metadata":{"type":"markdown"},"seo":{"title":"Cart Operation Events","description":"Fluid is the open e-commerce platform built for direct-sales."},"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cart-operation-events"},"children":["Cart Operation Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every public cart mutation emits a uniform ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["success"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["error"]}," window event, so a storefront can react to ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["any"]}," cart change from one place. The CDN bundle can also render a built-in toast for these events and show a loading spinner on add-to-cart buttons — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both are opt-in (off by default)"]},", so existing storefronts see no change until they turn them on."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before this, a failed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addCartItems"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addEnrollmentPack"]}," could fail silently — the shopper saw nothing. Now the failure always surfaces as an event, and — once enabled — as a toast."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Opt-in switches"]}," (on the Fluid script tag): ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast=\"true\""]}," enables the toast, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-button-loading=\"true\""]}," enables the button spinner. The events fire regardless."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-events"},"children":["The Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These functions emit the events:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Function"},"children":["Function"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Category"},"children":["Category"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"On success"},"children":["On success"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"On failure"},"children":["On failure"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/addcartitems"},"children":["addCartItems"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (still resolves ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/addenrollmentpack"},"children":["addEnrollmentPack"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (rethrows)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/updatecartitems"},"children":["updateCartItems"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (rethrows)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/decrementcartitem"},"children":["decrementCartItem"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (still resolves ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/updatecartitemvariant"},"children":["updateCartItemVariant"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (rethrows)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/removecartitembyid"},"children":["removeCartItemById"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_SUCCESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]}," (rethrows)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These events are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["additive"]}," — the SDK's existing lower-level events (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ADD_TO_CART"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPDATE_CART_ITEM"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REMOVE_FROM_CART"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_LOADING_START"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_LOADING_END"]},") still fire. Cart operation events are the single, uniform signal that covers all six mutations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listening"},"children":["Listening"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"window.addEventListener(\"CART_OPERATION_SUCCESS\", (e) => {\n  console.log(e.detail.operation, \"succeeded\", e.detail.cart);\n});\n\nwindow.addEventListener(\"CART_OPERATION_ERROR\", (e) => {\n  console.log(e.detail.operation, \"failed:\", e.detail.message);\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-detail"},"children":["Event Detail"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both events carry a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," object with the same shape:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When"},"children":["When"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The function that ran, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"addCartItems\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"add\" | \"update\" | \"remove\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Coarse bucket used to pick the default toast message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["toast"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," when the call passed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ toast: false }"]}," — the built-in toast skips it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO timestamp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cart"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cart"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["success"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resulting cart, when the operation returned one"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["unknown"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The raw thrown value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Best-effort human-readable message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["variantIds"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number[]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["when known"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Variant IDs the operation acted on"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["itemId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["when known"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cart item ID (for item-scoped operations)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enrollmentPackId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["when known"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enrollment pack ID (for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addEnrollmentPack"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Example error detail\n{\n  operation: \"addCartItems\",\n  category: \"add\",\n  toast: true,\n  timestamp: \"2026-07-13T20:00:00.000Z\",\n  error: Error,\n  message: \"Something went wrong\",\n  variantIds: [11111]\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"built-in-toast"},"children":["Built-in Toast"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CDN bundle can render a toast for these events. It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["opt-in (off by default)"]}," — add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast=\"true\""]}," to the Fluid script tag to turn it on. Nothing else is required; it renders in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["light DOM"]},", so your CSS applies to it directly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once enabled, the toast has a variant icon, the message, and a close button; it slides in, auto-dismisses after 4s, pauses on hover, and honors ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["prefers-reduced-motion"]},". Success toasts are suppressed while the cart drawer is open (an open cart is its own confirmation); error toasts always show."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script\n  id=\"fluid-cdn-script\"\n  src=\"https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js\"\n  data-fluid-shop=\"your-shop-id\"\n  data-fluid-toast=\"true\"\n></script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-at-runtime--configurecartfeedback-"},"children":["Configure at runtime (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configureCartFeedback"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you can't edit the Fluid script tag — e.g. it's injected as a global embed, which is the usual case for themes — enable and configure the toast (and the button spinner) at runtime instead:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"window.addEventListener(\"DOMContentLoaded\", () => {\n  window.FairShareSDK?.configureCartFeedback({\n    toast: true,\n    buttonLoading: true,\n    position: \"bottom-right\",\n    class: \"my-toast\",\n    duration: 5000,\n    messages: { add: \"Added! 🎉\", error: \"Couldn't add that — try again.\" },\n  });\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ toast, buttonLoading, position, class, duration, icon, successIcon, errorIcon, closeIcon, messages }"]}," — all optional. It ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merges over"]}," the script-tag attributes below (precedence: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["configureCartFeedback()"]}," > attributes > defaults) and is read lazily, so it applies whenever you call it. Call it once the SDK is attached (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOMContentLoaded"]}," is reliable for the deferred embed); the optional chaining makes it a safe no-op otherwise. Theme authors: see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/themes/cart-feedback"},"children":["Cart Feedback"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-script-tag-attributes"},"children":["Configuration (script-tag attributes)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["do"]}," control the script tag, configure it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-*"]}," attributes on the Fluid ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["script tag"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#fluid-cdn-script"]},"), read at show time:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"true\""]}," to enable the built-in toast"]}," (events still fire either way)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-class"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your class name on the toast element; style it (and its variants) in CSS"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-position"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bottom-center"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bottom-center"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bottom-left"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bottom-right"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["top-center"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["top-left"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["top-right"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-duration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Auto-dismiss delay in milliseconds"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-icon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["shown"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"false\""]}," to hide the icon"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-success-icon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✓ icon"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom success icon — emoji, text, or SVG markup"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-error-icon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["! icon"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom error icon — emoji, text, or SVG markup"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-close-icon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["✕"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom close-button glyph or markup"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-msg-add"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Added to cart"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add"]}," operations"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-msg-update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cart updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}," operations"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-msg-remove"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Removed from cart"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remove"]}," operations"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-msg-error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Something went wrong. Please try again."]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message for any failure"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script\n  id=\"fluid-cdn-script\"\n  src=\"https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js\"\n  data-fluid-shop=\"your-shop-id\"\n  data-fluid-toast=\"true\"\n  data-fluid-toast-class=\"my-toast\"\n  data-fluid-toast-position=\"top-right\"\n  data-fluid-toast-msg-add=\"Added! 🎉\"\n></script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"styling"},"children":["Styling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Give the toast one class with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-toast-class"]},", then style it — and each variant — in CSS. The toast element exposes state as data attributes you can target:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values"},"children":["Values"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use"},"children":["Use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-variant"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Style success vs. error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-position"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["the configured position"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Position-specific tweaks"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["open"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enter/exit styling"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","header":{"controls":{"copy":{}}},"source":".my-toast {\n  border-radius: 12px;\n  font-family: var(--brand-font);\n}\n.my-toast[data-variant=\"success\"] {\n  background: #0f9d58;\n}\n.my-toast[data-variant=\"error\"] {\n  background: #d93025;\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is a single class hook by design — per-variant styling is done in CSS via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-variant"]},", not with separate attributes."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"per-call-suppression"},"children":["Per-call suppression"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every mutation accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ toast: false }"]}," to silence its toast for one call. The event still fires, so your own UI can react."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"await window.FairShareSDK.addCartItems(11111, { quantity: 1, toast: false });\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"button-loading-indicator"},"children":["Button Loading Indicator"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add-to-cart interactions can show a spinner on the clicked button until the request settles."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declarative-opt-in"},"children":["Declarative (opt-in)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["off by default"]},". Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-button-loading=\"true\""]}," to the Fluid script tag to make declarative ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-add-to-cart"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-add-enrollment-pack"]}," buttons spin automatically — no per-button JavaScript needed. Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-loading-text"]}," to swap the label while loading:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<!-- Enable the spinner globally -->\n<script id=\"fluid-cdn-script\" src=\"…\" data-fluid-shop=\"…\" data-fluid-button-loading=\"true\"></script>\n\n<!-- Any declarative button then spins on click -->\n<button data-fluid-add-to-cart=\"11111\" data-fluid-loading-text=\"Adding…\">\n  Add to cart\n</button>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Can't edit the script tag? Enable it at runtime instead — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FairShareSDK.configureCartFeedback({ buttonLoading: true })"]}," (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#configure-at-runtime-configurecartfeedback"},"children":["above"]},")."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"custom-calls"},"children":["Custom calls"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you drive a mutation from your own JavaScript (custom payloads, bundles), wrap it so the spinner is managed for you. These helpers work ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["regardless"]}," of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-button-loading"]}," flag — that flag only controls the automatic declarative spinner above. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withButtonLoading"]}," turns it on and clears it in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finally"]},", whether the call resolves or throws:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"button.addEventListener(\"click\", (e) => {\n  window.FairShareSDK.withButtonLoading(e.currentTarget, () =>\n    window.FairShareSDK.addCartItems(11111, { quantity: 1 }),\n  );\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For full manual control, toggle it yourself (idempotent; also sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aria-busy"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const btn = e.currentTarget;\nwindow.FairShareSDK.setButtonLoading(btn, true);\ntry {\n  await window.FairShareSDK.addCartItems(11111, { quantity: 1 });\n} finally {\n  window.FairShareSDK.setButtonLoading(btn, false);\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API"},"children":["API"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withButtonLoading(el, fn)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Runs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fn"]}," with the button loading; clears in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finally"]},". Returns/rethrows whatever ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fn"]}," does"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setButtonLoading(el, on)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manually toggle the spinner. Idempotent; sets/clears ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aria-busy"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-fluid-loading-text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional label shown on the button while loading"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"behavior-note"},"children":["Behavior Note"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addCartItems"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decrementCartItem"]}," previously swallowed API failures and resolved ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},". They still resolve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]}," on failure (their caller-visible contract is unchanged) — but now they also emit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CART_OPERATION_ERROR"]},", so the failure is no longer invisible. The other mutations continue to reject on failure while also emitting the error event."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related"},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart"},"children":["Cart Overview"]}," — all cart operations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/addcartitems"},"children":["addCartItems"]}," — add one or more items"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/cart/addenrollmentpack"},"children":["addEnrollmentPack"]}," — add an enrollment pack"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/sdk/fairshare/installation"},"children":["Installation"]}," — the Fluid script tag and its attributes"]}]}]},"headings":[{"value":"Cart Operation Events","id":"cart-operation-events","depth":1},{"value":"The Events","id":"the-events","depth":2},{"value":"Listening","id":"listening","depth":3},{"value":"Event Detail","id":"event-detail","depth":2},{"value":"Built-in Toast","id":"built-in-toast","depth":2},{"value":"Configure at runtime ( configureCartFeedback )","id":"configure-at-runtime--configurecartfeedback-","depth":3},{"value":"Configuration (script-tag attributes)","id":"configuration-script-tag-attributes","depth":3},{"value":"Styling","id":"styling","depth":3},{"value":"Per-call suppression","id":"per-call-suppression","depth":3},{"value":"Button Loading Indicator","id":"button-loading-indicator","depth":2},{"value":"Declarative (opt-in)","id":"declarative-opt-in","depth":3},{"value":"Custom calls","id":"custom-calls","depth":3},{"value":"Behavior Note","id":"behavior-note","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":"Cart Operation Events"}},"lastModified":"2026-07-14T00:46:43.000Z"},"slug":"/docs/sdk/fairshare/cart/cart-operation-events","userData":{"isAuthenticated":false,"teams":["anonymous"]}}