Event Collection API: Add to Cart Event

The add to cart event should be fired when a visitor adds an item to the cart from search results.

An add to cart event should be sent in the following situations:

• When a user clicks the "Add to Cart" button on a product card in a listing or search page.

• When a user clicks the "Add to Cart" button on the Product Detail Page.

Endpoint

POST https://eurekaevent.api.useinsider.com/api/v1/events

Payload Fields

The add to cart event supports the following properties:

Refer to Common Properties for further details.

Add to Cart Product Fields

The product object (singular, not an array):

Refer to Common Properties for further details.

Source-Dependent Required Fields

Event Ordering:

It is recommended to send the corresponding Product Click event before sending the Add to Cart event. If a user adds a product to the cart directly from the pop-up without going to PDP, the product-click log should also be sent alongside the add-to-cart log.

Trace ID:

If the add-to-cart action happens on the same listing page, ensure the traceId from the product-list-view event is passed through product.traceId. If the add-to-cart is triggered on the Product Detail Page (PDP), you must explicitly provide the traceId in the product payload.

Legacy Source Mapping:

The source values product-detail and other are automatically mapped to search-listing by the API.

Default Values Applied:

• product.quantity: Defaults to 1 if 0 or negative

• product.sorting: Defaults to "Relevancy" if empty

• product.traceId ↔ searchSessionId: Bidirectional fallback

Advanced Analytics (September, 01, 2025 release):

The event now retrieves currentPage from the product-level fields instead of the top-level fields, and the product object has been enriched with new fields. You may continue sending values at the event level for backward compatibility, but it is recommended to update your implementation to the new product-level structure.

Sample Requests

In the examples below, you see sample requests along with guidance on modifying the necessary fields. This will help you seamlessly integrate and make the most of the provided configuration.

Before usage, modifying the values such as x-auth-token and x-partner-config-key is essential.

Add to Cart from Search Example

curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "referrer": "https://example.com/search-results",
  "source": "search-listing",
  "userId": "user-12345",
  "platform": "ios",
  "campId": 999999,
  "variationId": 999999,
  "searchSessionId": "search-session-abc123",
  "attributionWindow": ["session", "1", "7", "30", "90"],
  "product": {
    "id": "product-001",
    "groupCode": "group-1",
    "query": "queryA",
    "price": 1299.99,
    "convertedPrice": 1199.99,
    "currency": "USD",
    "preferredCurrency": "EUR",
    "clickPosition": 3,
    "displayPosition": 3,
    "quantity": 2,
    "resultCount": 25,
    "itemsPerPage": 10,
    "totalPages": 3,
    "facets": [
      {
        "label": "Price",
        "field": "price_en",
        "values": ["500", "2000"]
      },
      {
        "label": "Brand",
        "field": "brand_en",
        "values": ["brandA"]
      }
    ],
    "sorting": "Relevancy",
    "currentPage": 1,
    "traceId": "search-session-abc123",
    "strategyId": "strategy-id-123",
    "sessionId": "session-id-123",
    "attributionWindow": ["session", "1", "7", "30", "90"]
  },
  "eventType": "add-to-cart",
  "integrationType": "api",
  "createdAt": "2025-11-25T10:40:00Z"
}'

Add to Cart from Category Listing Example

curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "referrer": "https://example.com/category/categoryA",
  "source": "category-listing",
  "userId": "user-12345",
  "platform": "desktop-web",
  "searchSessionId": "search-session-cat456",
  "attributionWindow": ["session", "7", "30"],
  "product": {
    "id": "product-001",
    "groupCode": "group-1",
    "listValue": "categoryA~categoryB",
    "price": 999.99,
    "convertedPrice": 949.99,
    "currency": "USD",
    "preferredCurrency": "EUR",
    "clickPosition": 1,
    "displayPosition": 1,
    "quantity": 1,
    "resultCount": 120,
    "itemsPerPage": 24,
    "totalPages": 5,
    "sorting": "Relevancy",
    "currentPage": 1,
    "traceId": "trace-cat-456",
    "sessionId": "session-abc123",
    "attributionWindow": ["session", "7", "30"]
  },
  "eventType": "add-to-cart",
  "integrationType": "api",
  "createdAt": "2026-01-20T14:35:00Z"
}'