Send add to cart event every time
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.
Event-Level Fields
The add to cart event supports the following properties:
Field | Required | Notes |
|---|---|---|
eventType | Yes | Must be "add-to-cart" |
source | No | One of: search-popup, search-listing, category-listing, brand-listing, other. Defaults to search-listing |
userId | No | Unique user identifier. Defaults to "default" |
platform | Yes | One of: desktop-web, mobile-web, tablet-web, ios, android, other |
integrationType | Yes | One of: api, web, sdk, app |
searchSessionId | No | Deprecated. Use product.traceId instead. Bidirectional fallback with product.traceId. No spaces. |
product | Yes | Single product object (not an array) |
referrer | Yes | Must be a valid URL |
createdAt | No | RFC 3339 timestamp. Defaults to the current time if omitted or invalid |
campId | No | Campaign identifier. Defaults to 999999 |
attributionWindow | Yes | Required. Min 1 value. Valid values: "session", "1", "7", "14", "30", "90" |
variationId | No | Variation identifier. Defaults to 999999 |
Refer to Common Properties for further details.
Product Fields
The product field is a single object (not an array).
Parameter | Required | Notes |
|---|---|---|
id | Yes | Unique product identifier. No spaces |
groupCode | No | Product group code. Needed for group-level analytics |
price | Yes | Price of the product |
convertedPrice | No | Converted price in preferred currency. Defaults to price if not provided |
currency | Yes | ISO 4217 currency code. No spaces |
preferredCurrency | No | Main currency of your site. Defaults to currency if not specified |
sorting | Yes | Sorting method. Defaults to "Relevancy" |
resultCount | Yes | Number of search results returned. Min: 1 |
itemsPerPage | Yes | Number of items per page. Min: 1 |
totalPages | Yes | Total number of pages. Min: 1 |
currentPage | Yes | Current page number. Min: 1 |
facets | No | Applied filters |
sessionId | No | Browser/app session identifier |
strategyId | No | Optional strategy identifier |
quantity | Yes | Quantity added to cart. Defaults to 1 if 0 or negative |
traceId | Yes | Must match the traceId from the originating search/listing event |
searchSessionId | No | Deprecated. Use traceId instead. Bidirectional fallback with traceId |
query | Conditional | Required when the source is search-popup, search-listing, or other. Defaults to "default" |
listValue | Conditional | Required when the source is category-listing or brand-listing. Must not be blank |
displayPosition | Yes | Position when first displayed. Min: 1 |
clickPosition | Yes | Position when clicked. Min: 1 |
attributionWindow | Yes | Time intervals for attribution at the product level |
isMerchandisedItem | No | Whether the product is a merchandised (promoted/sponsored) item |
Refer to Common Properties for further details.
Click Before Cart
You must send the product-click event first, then the add-to-cart event. The add-to-cart method does not trigger a click event automatically.
Attribution Window
The attributionWindow field is required for add-to-cart events.
Valid values: any numeric string or "session". Common: ["session", "1", "7", "14", "30", "90"].
Only include windows that encompass the event timeframe. For example, if the user searched on day 1 and added to cart on day 8, send ["14", "30", "90"].
Sample Requests
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 '{
"eventType": "add-to-cart",
"source": "search-listing",
"userId": "user-123",
"platform": "desktop-web",
"searchSessionId": "sess-abc-123",
"attributionWindow": ["session", "7", "30", "90"],
"integrationType": "api",
"referrer": "https://example.com/search?q=queryA",
"product": {
"id": "product-001",
"groupCode": "group-1",
"query": "queryA",
"price": 999.99,
"currency": "USD",
"quantity": 1,
"displayPosition": 3,
"clickPosition": 3,
"resultCount": 25,
"sorting": "Relevancy",
"traceId": "sess-abc-123",
"attributionWindow": ["session", "7", "30", "90"]
}
}'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 '{
"eventType": "add-to-cart",
"source": "category-listing",
"userId": "user-123",
"platform": "desktop-web",
"searchSessionId": "trace-cat-456",
"attributionWindow": ["session", "7", "30"],
"integrationType": "api",
"referrer": "https://example.com/category/categoryA",
"product": {
"id": "product-001",
"groupCode": "group-1",
"listValue": "categoryA~categoryB",
"price": 999.99,
"currency": "USD",
"quantity": 1,
"displayPosition": 1,
"clickPosition": 1,
"resultCount": 120,
"sorting": "Relevancy",
"traceId": "trace-cat-456",
"attributionWindow": ["session", "7", "30"]
}
}'