Convertful Cart Integration API

This document describes how to integrate your website cart with the Convertful widget using the JavaScript API.

Overview #

The window.Convertful.cart API allows you to synchronize your website cart state with the Convertful widget. This ensures that widget behavior (e.g., targeting, triggers, personalization) correctly reflects the current cart contents.

Data Structure #

Each cart item must follow this structure:

{
  id: Number | String,     // Unique product or cart item ID
  price: Number,           // Price per single item
  quantity: Number         // Quantity of the item in the cart
}

API Methods #

1. set(items) #

Description: Replaces the entire cart with a new set of items.

Use case: Use this method when initializing or fully refreshing the cart state (e.g., on page load or after fetching cart data from backend).

Parameters:

• items (Array of objects) — list of cart items

Behavior:

• Completely overwrites previously stored cart data

Example:

<script type="text/javascript">
if (window.Convertful && window.Convertful.cart !== undefined) {
   window.Convertful.cart.set([
       { id: 143534, price: 200, quantity: 1 },
       { id: 15446, price: 150, quantity: 2 }
   ]);
}
</script>

2. add(id, price, quantity) #

Description: Adds a product to the cart.

Use case: Call this when a user adds a product to the cart.

Parameters:

• id (Number | String) — product or cart item ID
• price (Number) — price per item
• quantity (Number) — quantity to add

Behavior:

• If the item already exists, the quantity will be increased
• If the item does not exist, it will be added

Example:

<script type="text/javascript">
if (window.Convertful && window.Convertful.cart !== undefined) {
   window.Convertful.cart.add(12544, 100, 1);
}
</script>

3. remove(id, quantity) #

Description: Removes a product or decreases its quantity.

Use case: Call this when a user removes a product or decreases its quantity.

Parameters:

• id (Number | String) — required
• quantity (Number) — optional

Behavior:

• If quantity is NOT provided → removes the item completely
• If quantity is provided → decreases item quantity by that value

Examples:

Remove entire product:

<script type="text/javascript">
if (window.Convertful && window.Convertful.cart !== undefined) {
   window.Convertful.cart.remove(12544);
}
</script>

Remove specific quantity:

<script type="text/javascript">
if (window.Convertful && window.Convertful.cart !== undefined) {
   window.Convertful.cart.remove(12544, 1);
}
</script>

4. clear() #

Description: Clears the entire cart.

Use case: Call this when the cart is emptied (e.g., after checkout or manual clear).

Example:

<script type="text/javascript">
if (window.Convertful && window.Convertful.cart !== undefined) {
   window.Convertful.cart.clear();
}
</script>

Initialization Check (Required) #

Before calling any API method, always ensure that Convertful is loaded:

if (window.Convertful && window.Convertful.cart !== undefined) {
   // Safe to use API
}

Integration Guidelines #

• Use set() when initializing or fully syncing the cart
• Use add() when products are added
• Use remove() when products or quantities are removed
• Use clear() when the cart becomes empty
• Keep cart data consistent with your actual backend/cart state

Common Pitfalls #

❌ Not checking if window.Convertful exists before calling methods
❌ Passing incorrect data types (e.g., string price instead of number)
❌ Forgetting that set() overwrites all previous data
❌ Not syncing cart changes in real-time