Skip to main content
Sends a purchase event to Constructor.io’s API. This tracks when a user completes an order, typically fired on the order confirmation page. This is one of the most important tracking events for measuring search and recommendation effectiveness.

​
Method Signature

constructorio.tracker.trackPurchase(parameters, networkParameters?)

​
Parameters

​
parameters
object
required
Parameters for the purchase event
​
networkParameters
object
Optional parameters for the network request

​
Returns

Returns true on success, false if the order was already tracked, or an Error object if validation fails.

​
Examples

​
Basic Example

import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';

const constructorio = new ConstructorIOClient({
  apiKey: 'YOUR_API_KEY',
});

// Track purchase
constructorio.tracker.trackPurchase({
  items: [
    { itemId: 'KMH876', price: 29.99, count: 1 },
    { itemId: 'KMH140', price: 19.99, count: 2 },
  ],
  revenue: 69.97,
  orderId: 'ORDER-12345',
});

​
Complete Example

// Track purchase with all item details
constructorio.tracker.trackPurchase({
  items: [
    {
      itemId: 'KMH876',
      itemName: 'Red T-Shirt',
      variationId: 'KMH876-RED-L',
      price: 29.99,
      count: 1,
    },
    {
      itemId: 'KMH140',
      itemName: 'Blue Jeans',
      variationId: 'KMH140-BLUE-32',
      price: 49.99,
      count: 1,
    },
  ],
  revenue: 79.98,
  orderId: 'ORDER-12345',
  section: 'Products',
});

​
Example with Analytics Tags

// Track purchase with custom analytics data
constructorio.tracker.trackPurchase({
  items: [
    { itemId: 'SHOE-001', price: 89.99, count: 1 },
  ],
  revenue: 89.99,
  orderId: 'ORDER-67890',
  analyticsTags: {
    channel: 'web',
    device: 'mobile',
    paymentMethod: 'credit_card',
    shippingMethod: 'express',
  },
});

​
Integration Example

// Track on order confirmation page
window.addEventListener('load', () => {
  const orderData = window.orderConfirmation; // From your backend
  
  if (orderData) {
    const items = orderData.items.map(item => ({
      itemId: item.id,
      itemName: item.name,
      variationId: item.variant_id,
      price: item.price,
      count: item.quantity,
    }));
    
    constructorio.tracker.trackPurchase({
      items: items,
      revenue: orderData.subtotal,
      orderId: orderData.order_id,
    });
  }
});

​
E-commerce Platform Example

// Example with Shopify checkout
function trackShopifyPurchase(checkout) {
  const items = checkout.line_items.map(item => ({
    itemId: item.variant_id.toString(),
    itemName: item.title,
    price: parseFloat(item.price),
    count: item.quantity,
  }));
  
  constructorio.tracker.trackPurchase({
    items: items,
    revenue: parseFloat(checkout.subtotal_price),
    orderId: checkout.order_id.toString(),
    analyticsTags: {
      currency: checkout.currency,
      discount: checkout.total_discount,
    },
  });
}

​
When to Use

Call trackPurchase() when:
  • A user completes checkout and reaches the order confirmation page
  • An order is successfully processed
  • Payment is confirmed
Important: Only call this method once per order. The SDK automatically tracks order IDs to prevent duplicates.

​
Important Notes

​
Revenue Calculation

  • revenue should be the order subtotal (sum of item prices)
  • Exclude taxes, shipping costs, and fees
  • Use the actual purchase price, not the original/MSRP price

​
Item Limits

  • The items array can contain up to 100 items
  • Items beyond 100 are automatically truncated

​
Duplicate Prevention

The SDK automatically prevents duplicate purchase tracking: 
// First call - tracked successfully
constructorio.tracker.trackPurchase({
  items: [{ itemId: 'ITEM-1', price: 10, count: 1 }],
  revenue: 10,
  orderId: 'ORDER-123',
});
// Returns: true

// Second call with same orderId - skipped
constructorio.tracker.trackPurchase({
  items: [{ itemId: 'ITEM-1', price: 10, count: 1 }],
  revenue: 10,
  orderId: 'ORDER-123',
});
// Returns: false (already tracked)

​
Item Object Format

Each item in the items array should have: 
{
  itemId: string;        // Required: Product identifier
  price: number;         // Required: Item price
  count: number;         // Required: Quantity purchased
  itemName?: string;     // Optional: Product name
  variationId?: string;  // Optional: Variant identifier
}

​
Order ID Best Practices

  • Always include an orderId to prevent duplicate tracking
  • Use your system’s unique order identifier
  • Ensure the ID is consistent across your systems
  • The SDK stores tracked order IDs in browser storage

​
Relationship with Conversions

Track both conversions and purchases:
  1. trackConversion - When item is added to cart
  2. trackPurchase - When order is completed (this method)
This helps measure conversion funnel performance.

​
API Endpoint

This method sends a POST request to: 
/v2/behavioral_action/purchase

Build docs developers (and LLMs) love

Get started for freeTalk to us