Tracking

Track product views and browsing behavior to power abandoned browse flows and personalized recommendations. Product views are automatically linked to contacts and can trigger flow automations.

Track Product View

POST

/track/product-view

Record a product view for a contact

Name	Type	Required	Description
email	string	Optional	Contact email address. Required if contact_id is not provided.
contact_id	string (UUID)	Optional	Contact ID. Required if email is not provided.
product_id	string	Required	Your product identifier (max 100 characters)
product_name	string	Required	Product display name (max 200 characters)
product_url	string (URL)	Required	Full URL to the product page
variant_id	string	Optional	Product variant identifier (max 100 characters)
image_url	string (URL)	Optional	Product image URL
price	number	Optional	Product price (must be >= 0)
currency	string	Optional	3-letter ISO currency code (default: USD)
category	string	Optional	Product category (max 100 characters)
brand	string	Optional	Product brand name (max 100 characters)
sku	string	Optional	Stock keeping unit (max 100 characters)
session_id	string	Optional	Browser session ID for grouping views (max 100 characters)

curl -X POST https://api.topmail.so/api/v1/track/product-view \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "shopper@example.com",
    "product_id": "prod_abc123",
    "product_name": "Premium Wireless Headphones",
    "product_url": "https://yourstore.com/products/wireless-headphones",
    "image_url": "https://yourstore.com/images/headphones.jpg",
    "price": 99.99,
    "currency": "USD",
    "category": "Electronics",
    "brand": "AudioCo",
    "sku": "WH-PRO-BLK"
  }'

{
  "data": {
    "id": "view-uuid-12345",
    "contact_id": "contact-uuid-67890",
    "product_id": "prod_abc123",
    "product_name": "Premium Wireless Headphones",
    "viewed_at": "2025-01-15T14:30:00.000Z"
  }
}

Flow Triggers

Product views automatically trigger product_viewed flow automations. Use this to set up abandoned browse emails, product recommendation flows, or price drop notifications.

Contact Required

The contact must already exist in your workspace. If the email or contact_id does not match an existing contact, the API returns a 404 error. Create the contact first using the Contacts API.