Overview
The Add-to-Cart feature enables customers to add a product and/or a specific item (SKU) directly from the Sensefuel search layer, and potentially from product recommendation slots.
To support this feature, up to three integrations are required:
- Add-to-Cart Action
A function provided by your website that performs the actual add-to-cart operation. - Cart Content Retrieval
A function, variable, or data layer that allows Sensefuel to read the current cart contents. - (Optional) Open Cart Action
A function or URL that opens the shopping cart when the user clicks the cart icon in the search layer.
Once configured, product tiles can display an Add-to-Cart button. When clicked, the add-to-cart function you provide is executed.
1. Add-to-Cart Function
Description
This function executes the add-to-cart logic on your platform. It can be synchronous or asynchronous.
Signature
- function(<id_article>, <quantity>) : <code>
- function(<id_article>, <quantity>) : <Promise<code>>
If the function is asynchronous, the return code must be resolved via a Promise.
Sensefuel may pass additional arguments to this function, dynamically populated from catalog or offer feed attributes, to meet your JavaScript function requirements.
Return Codes
Your function must return one of the following values (directly or via a Promise):
"success"– product successfully added to cart"error"– add-to-cart action failed"information_required"– user action required before completing the add-to-cart
Example (JavaScript)
async function addToCart(id, quantity) {
try {
await fetch("/php_process/cart_engine.php", {
method: "POST",
body: {
id,
quantity,
loose
}
});
window.sensefuelDatalayer.articles[id] = { quantity };
return "success";
} catch (err) {
return "error";
}
}Add-to-Cart Modes
Sensefuel supports multiple add-to-cart interaction modes:
1. Simple Add-to-Cart (Unit Mode)
- Adds one unit per click.
2. Advanced Add-to-Cart (Quantity Management)
- Fixed or dynamic quantity increment (based on an attribute defining the increment value)
- Plus (+) and minus (–) buttons
- Quantity input field (manual input)
- Quantity dropdown list selection
- Optional “remove from cart” icon
- Minimum and maximum quantity constraints
3. Input Mode for Loose / Bulk Products
- Allows manual quantity entry
- Typically bounded by minimum and maximum quantity attributes
4. Variant Selection
If product variants exist in your feed, the user must select a variant before adding to cart.
This selection can occur:
- In a modal
- Directly from the product tile
Both options are customizable.
Post Add-to-Cart Behaviors
Based on the return code, Sensefuel can trigger different UI behaviors.
On success
- Display a confirmation message on the product tile
- Display a confirmation message in a modal with 2 buttons
- "continue shopping" (closes the modal)
- "see my cart" (redirect to the cart URL or execute the function to open the cart)
- Close or keep the search layer open
- Redirect to the cart page
- Open a mini-cart by executing a function
On error
- Display a customizable error message (same UI options as success)
On information_required
- The search layer can close automatically
- Enables you to manage a user flow that requires an additional action (login, postal code, etc.)
- The layer can automatically reopen by listening to a variable exposed on your site
Availability
The add-to-cart function must be available across the entire website.
Configuration
To activate or configure the add-to-cart function, please contact your Customer Success Manager.
2. Retrieving Cart Contents
Purpose
When add-to-cart is activated, Sensefuel retrieves the current cart contents in order to:
- Correctly display products already in the cart with the right quantity
- Display the number of items in the cart
You can configure:
- Whether this feature is enabled or disabled
- Whether the cart count is based on:
- Number of items
- Sum of quantities
⚠️ If you want to support quantity management, cart content retrieval is mandatory.
Sensefuel only reads this information. No data is stored or modified.
Signature
- <data>
- function() : <data>
- function() : <Promise<data>>
You can provide:
- A synchronous or asynchronous function
- Or a variable (global variable, data layer, local storage, or cookie)
Parameters
<id_article>(String): SKU identifier from your Sensefuel catalog<quantity>(Number): Quantity added to the cart
The add-to-cart data structure may be merged with other data structures (add-to-list, store context, anonymized customer data).
To keep the object lightweight, items with quantity = 0 should be removed.
Data Structure
{
articles : {
<id>: {
quantity: <number>
}
}
}Example
{
articles:{
97 : {quantity: 3}
1217 : {quantity: 1}
1451 : {quantity: 1}
7899 : {quantity: 1}
}
}Availability
The cart content retrieval function or variable must be available throughout the entire website.
Configuration
To activate or configure this feature, please contact your Customer Success Manager.
3. Opening the Shopping Cart from the Search Layer
Description
Sensefuel can display a shopping cart icon in the search layer.
When clicked, it allows customers to access their cart.
This interaction can be handled in two ways:
- Execute a function
- Redirect to a URL
Function Signature
- <url>
- function() : undefined
The function can be synchronous or asynchronous. Alternatively, you can provide a direct cart URL
Behavior
When the cart action is executed:
- The search layer closes automatically
- Your website displays the cart (current page, mini-cart, or cart page)
Availability
The function (if used) must be available across the entire website.
Configuration
To activate or configure the cart opening behavior, please contact your Customer Success Manager.