Add to Cart

How the "Add to Cart" button works in the Alhena chat widget across Shopify and non-Shopify platforms.

The Alhena chat widget displays product cards when your AI recommends products. These cards can include an "Add to Cart" button that lets customers add items to their cart without leaving the conversation.

How this works depends on your e-commerce platform.

---

Shopify

No custom code required. The Alhena widget automatically detects Shopify stores and handles add-to-cart natively.

When a customer clicks "Add to Cart" on a product card, the widget:

1. Calls Shopify's /cart/add.js API directly

2. Opens your store's cart drawer (or redirects to /cart on unsupported themes)

3. Records the cart event for analytics automatically

Supported themes

The widget opens the native cart drawer on the following themes:

Theme family	Themes
Shopify (Dawn)	Dawn and themes using <cart-drawer> or <cart-notification>
Shopify (2025)	Horizon, Publisher, Spotlight, Trade
Be Yours / RoarTheme	Be Yours, RoarTheme
Maestrooo	Focal, Impact, Prestige, Stretch, Warehouse
Clean Canvas	Symmetry, Pipeline, Showcase
Archetype	Impulse, Motion, Expanse, Streamline
Out of the Sandbox	Turbo, Flex, Vino
Krown	Local, Borders, Combine, Split, Highlight, Kingdom, Seventh
Vue-based	K18, custom Vue storefronts
Third-party apps	Rebuy SmartCart, Slide Cart, UpCart

For themes not listed above, the widget falls back to redirecting the customer to the /cart page.

By default, Alhena adds a hidden _alhena_fingerprint property to cart items for revenue attribution. This is invisible to customers and does not affect cart behavior. It can be disabled in the dashboard if needed.

---

Non-Shopify (SFCC, Magento, custom platforms)

For non-Shopify platforms, the "Add to Cart" button will not appear on product cards until you register an event handler. Each platform has its own cart API, so your team needs to provide the implementation.

Setup

Step 1: Make sure the Alhena widget script is installed on your site.

Step 2: Register the add-to-cart handler. Once registered, the "Add to Cart" button will automatically appear on product cards.

window.gleenWidget.on('products:added_to_cart', function(products) {
    products.forEach(function(product) {
        // Replace with your platform's cart API call
        addToCart({
            variantId: product.variantId,
            quantity: product.quantity,
            productName: product.productName,
            price: product.price,
            currency: product.currency
        });
    });
});

Callback data

Each product object in the callback contains:

Property	Type	Description
variantId	string	Product variant ID
masterProductId	string	Parent/master product ID
productName	string	Product display name
quantity	number	Number of items to add
price	number	Unit price
currency	string	Currency code (e.g. USD, EUR, GBP)
category	string	Product category
attributes	object	Additional product attributes

---

Platform examples

BigCommerce

Paste the snippet below into Storefront → Script Manager in your BigCommerce admin — the same place the Alhena widget script lives. Use Location on page: Footer and Select pages where script will be added: All pages, then wrap the code in <script>…</script> tags.

BigCommerce's Script Manager validates the pasted HTML and rejects certain characters — most notably && (it reads & as the start of an HTML entity). The snippet below is written without && or || so it pastes cleanly. If you adapt it, keep logical operators out of the Script Manager copy, or host the JS externally and reference it with <script src="…"></script>.

window.gleenWidget.on('products:added_to_cart', function(products) {
    var lineItems = products.map(function(product) {
        var item = {
            quantity: product.quantity,
            product_id: parseInt(product.masterProductId, 10)
        };
        if (product.variantId) {
            item.variant_id = parseInt(product.variantId, 10);
        }
        return item;
    });

    var baseOptions = {
        credentials: 'same-origin',
        headers: { 'Content-Type': 'application/json' }
    };
    var body = JSON.stringify({ line_items: lineItems });

    function postTo(url) {
        return fetch(url, Object.assign({ method: 'POST', body: body }, baseOptions));
    }

    fetch('/api/storefront/carts', baseOptions)
        .then(function(r) { return r.json(); })
        .then(function(carts) {
            if (carts.length) {
                return postTo('/api/storefront/carts/' + carts[0].id + '/items');
            }
            return postTo('/api/storefront/carts');
        })
        .then(function(response) {
            if (!response.ok) {
                throw new Error('BigCommerce cart add failed: ' + response.status);
            }
            return response.json();
        })
        .then(function(cart) {
            // Refresh the cart icon / preview on Cornerstone-based themes.
            var qty = 0;
            var items = cart.line_items ? cart.line_items.physical_items : null;
            if (items) {
                items.forEach(function(i) { qty += i.quantity; });
            }
            $(document.body).trigger('cart-quantity-update', qty);
        })
        .catch(function(err) { console.error(err); });
});

This uses the BigCommerce Storefront Cart API: GET /api/storefront/carts returns the session's cart (if any), then the handler either appends to /carts/{cartId}/items or creates a new cart via POST /api/storefront/carts. Omit variant_id for products without variants.

product_id and variant_id must be integers — the IDs in the callback are strings, so parse them before sending. On Cornerstone-based Stencil themes, trigger the cart-quantity-update jQuery event on document.body so the cart icon and mini-cart refresh; without it, the widget add succeeds but customers see no visible change and tend to click again.

Salesforce Commerce Cloud (SFCC)

window.gleenWidget.on('products:added_to_cart', function(products) {
    products.forEach(function(product) {
        fetch('/on/demandware.store/Sites-YOUR_SITE/default/Cart-AddProduct', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                pid: product.variantId || product.masterProductId,
                quantity: product.quantity
            })
        });
    });
});

Replace Sites-YOUR_SITE with your actual SFCC site ID.

Magento

window.gleenWidget.on('products:added_to_cart', function(products) {
    products.forEach(function(product) {
        fetch('/checkout/cart/add', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'X-Requested-With': 'XMLHttpRequest'
            },
            body: new URLSearchParams({
                product: product.masterProductId,
                qty: product.quantity,
                form_key: document.querySelector('input[name="form_key"]').value
            })
        });
    });
});

WooCommerce

See the full WooCommerce Revenue Tracking example for a complete implementation including cart events.

---

Dashboard settings

These options are available in Dashboard > Website Settings regardless of platform:

Setting	Description
Button label	Customize the "Add to Cart" button text
Hide button	Remove the add-to-cart button from product cards
Follow-up message	Show a confirmation message after a product is added
Card style	Choose between product card layouts

---

Analytics

Cart events are tracked automatically for all platforms. Every "Add to Cart" action is recorded and visible in Analytics > Revenue Impact — no additional setup required.

For Shopify stores, cart events are also tracked in the background by intercepting native Shopify cart API calls, so add-to-cart actions that happen outside the chat widget are captured too.

---

Legacy event

The single-product event product:added_to_cart is still supported for backwards compatibility but will be removed in a future release. Use products:added_to_cart for all new implementations — it receives an array and handles both single and multi-product actions.

---

Related pages

• Cart & Checkout Event API — Track cart and checkout events for revenue attribution

• Revenue Attribution — How Alhena attributes revenue to AI interactions

• Events — Complete SDK event reference