Overview

Overview

This guide covers tracking events for shopping platform interactions: cart modifications, product page views, shopper authentication, and order transactions.

Shopping platform events track core e-commerce activities outside of search and recommendations. All events require a context object (see Context Object Guide) and event-specific data.

Base URL: https://analytics.searchspring.net/beacon/v2/{siteId}/[module]/[event]

Cart Events

Track cart additions and removals via cart page or slideout cart.

Cart Add

Endpoint: POST /{siteId}/cart/add
When to send: Shopper adds item or increases quantity in cart

Required data fields:

• results - Array of products being added
• cart - Full updated cart state after addition

Product object:

{
  "parentId": "0987611111",
  "uid": "0987654321",
  "qty": 1,
  "price": 39,
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "results": [
      {
        "parentId": "0987611111",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ],
    "cart": [
      {
        "parentId": "0987622222",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      },
      {
        "parentId": "0987633333",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ]
  }
}

Cart Remove

Endpoint: POST /{siteId}/cart/remove
When to send: Shopper removes item or decreases quantity in cart

Required data fields:

• results - Array of products being removed
• cart - Full updated cart state after removal

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "results": [
      {
        "parentId": "0987633333",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ],
    "cart": [
      {
        "parentId": "0987622222",
        "uid": "0987654321",
        "qty": 1,
        "price": 39
      }
    ]
  }
}

Product Events

Product Pageview

Endpoint: POST /{siteId}/product/pageview
When to send: Shopper lands on a product detail page (PDP)

Required data fields:

• result - Object containing product identifiers

Result object:

{
  "parentId": "1234511111",
  "uid": "1234567890",
  "sku": "SKU-123"        // optional
}

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "result": {
      "parentId": "1234511111",
      "uid": "1234567890"
    }
  }
}

Shopper Events

Shopper Login

Endpoint: POST /{siteId}/shopper/login
When to send: Shopper successfully authenticates/logs into account

Special requirement: shopperId is required in context (not optional)

No data object required - only context is sent.

Example:

{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/login",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "user123456",
    "initiator": "searchspring/custom/1.0",
    "currency": { "code": "USD" }
  }
}

Order Events

Order Transaction

Endpoint: POST /{siteId}/order/transaction
When to send: Shopper completes an order/purchase

Required data fields:

• orderId - Unique order identifier
• transactionTotal - Subtotal before discounts, taxes, shipping
• total - Final total including discounts, taxes, shipping
• results - Array of products in order

Optional data fields:

• vat - Value added tax rate as decimal (e.g., 0.20 for 20%)
• city - Shipping address city
• state - Shipping address state
• country - Shipping address 2-letter country code

Example:

{
  "context": { /* see context guide */ },
  "data": {
    "orderId": "order1337",
    "transactionTotal": 75,
    "total": 100,
    "vat": 0.2,
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "results": [
      {
        "parentId": "8128331911111",
        "uid": "8128331907370",
        "qty": 2,
        "price": 39
      },
      {
        "parentId": "8128331922222",
        "uid": "8128021070122",
        "qty": 1,
        "price": 22
      }
    ]
  }
}

Implementation Tips

Cart Events:

• Fire on cart page or slideout cart interactions
• Always include full cart state in cart field
• results contains only the items being added/removed
• Track quantity changes as additions or removals

Product Pageview:

• Send once per PDP load
• Essential for attribution and conversion tracking
• No API response needed - product IDs from page data

Shopper Login:

• Only fires on successful authentication
• Must include shopperId in context
• No data object required
• Links shopper identity for personalization

Order Transaction:

• Fire on order confirmation/thank you page
• Include complete order details for revenue reporting
• Use transactionTotal for pre-discount amount
• Use total for final amount charged

Content Type: Both text/plain and application/json accepted.

Quick Reference