Sends a conversion event to Constructor.io’s API. This tracks when a user performs an action indicating interest in a product, such as adding to cart, adding to wishlist, or any custom conversion type.
Method Signature constructorio . tracker . trackConversion ( term ? , parameters , networkParameters ? )
Parameters Optional search query term that led to this conversion. Use null if the conversion didn’t originate from search.
Parameters for the conversion event Unique identifier of the product item
Sale price if available, otherwise the regular price of the item
Variation identifier if the item has variants
type
string
default: "add_to_cart"
Type of conversion (e.g., “add_to_cart”, “add_to_wishlist”, “like”)
Set to true if using a custom conversion type
Display name for custom conversion types
Optional parameters for the network request Request timeout in milliseconds
Returns Returns true on success or an Error object if validation fails.
Examples Basic Add to Cart Example import ConstructorIOClient from '@constructor-io/constructorio-client-javascript' ; const constructorio = new ConstructorIOClient ({ apiKey: 'YOUR_API_KEY' , }); // Track add to cart (conversion without search term) constructorio . tracker . trackConversion ( null , { itemId: 'KMH876' , revenue: 29.99 , } );
Conversion from Search // Track conversion that originated from a search constructorio . tracker . trackConversion ( 'T-Shirt' , { itemId: 'KMH876' , revenue: 29.99 , itemName: 'Red T-Shirt' , variationId: 'KMH876-RED-L' , type: 'add_to_cart' , section: 'Products' , } );
Custom Conversion Type // Track a custom conversion type (e.g., "like") constructorio . tracker . trackConversion ( 'running shoes' , { itemId: 'SHOE-001' , itemName: 'Ultra Runner Pro' , type: 'like' , isCustomType: true , displayName: 'Product Liked' , section: 'Products' , } );
Add to Wishlist Example // Track add to wishlist constructorio . tracker . trackConversion ( null , { itemId: 'KMH876' , revenue: 29.99 , itemName: 'Red T-Shirt' , type: 'add_to_wishlist' , } );
Integration Example // Track when user clicks "Add to Cart" button const addToCartButton = document . querySelector ( '.add-to-cart' ); addToCartButton . addEventListener ( 'click' , () => { const itemId = addToCartButton . dataset . itemId ; const itemName = addToCartButton . dataset . itemName ; const price = parseFloat ( addToCartButton . dataset . price ); const variationId = document . querySelector ( '.variant-select' ). value ; // Get search term if this came from search const searchTerm = sessionStorage . getItem ( 'lastSearchTerm' ); constructorio . tracker . trackConversion ( searchTerm , { itemId: itemId , itemName: itemName , revenue: price , variationId: variationId , type: 'add_to_cart' , } ); // Add item to cart... });
When to Use Call trackConversion() when:
A user adds an item to their shopping cart
A user adds an item to their wishlist
A user “likes” or “favorites” a product
Any custom action indicating product interest
Standard Conversion Types Common conversion types include:
"add_to_cart" (default) - Item added to shopping cart"add_to_wishlist" - Item added to wishlist"add_to_favorites" - Item favorited
Custom Conversion Types You can track custom conversion types:
constructorio . tracker . trackConversion ( null , { itemId: 'ITEM-123' , type: 'requested_info' , isCustomType: true , displayName: 'Requested More Info' , } );
Important Notes
The itemId parameter is required
Include the search term if the conversion originated from search results
Set term to null for conversions from browse, recommendations, or direct navigation
The revenue should be the price at the time of conversion
Default conversion type is "add_to_cart"
Relationship with Purchase Conversions track interest, while purchases track completed orders:
trackConversion - When item is added to cart (this method)trackPurchase - When order is completed
API Endpoint This method sends a POST request to:
/v2/behavioral_action/conversion
