Event: Add to Cart

The Add to Cart event is used to track customer cart addition activities. This event is important for understanding purchase intent and abandoned cart analysis, which are critical for conversion optimization and personalization.

API Endpoint

Method: POST
URL: https://<PA_END_POINT>/3.0/events/add-to-carts

Request Header

Name	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer ACCESS_TOKEN`

Request Parameters (Body)

Parameter	Type	Required	Description
`customerId`	`GUID`	✅	Unique identifier for the customer, obtained from the Config API. This identifier persists throughout the customer's lifetime on the platform. For details on retrieving a customer ID, please refer to the Config API documentation.
`sessionId`	`GUID`	✅	Unique identifier for the session, consistent throughout the session's duration. For information on obtaining a session ID, please refer to the Config API documentation.
`events`	`Array of objects`	✅	Array of objects detailing add to cart events. Each add to cart event object contains the following properties:

Event Object Definition

Parameter	Type	Required	Description
`currentUrl`	`string`	✅	URL of the page where the product was added to cart.
`eventTime`	`dateTime`	✅	UTC timestamp of when the product was added to cart.
`product`	`object`	✅	Object containing product information.
`product.refId`	`string`	✅	Unique identifier for the product added to cart.
`product.quantity`	`integer`	✅	Quantity of the product added to cart.
`product.price`	`number`	❌	Price of the product added to cart.
`referralUrl`	`string`	❌	URL that referred the user to the page where they added the product.
`clickId`	`GUID`	❌	Unique identifier for the click event that led to this add to cart.
`widgetId`	`GUID`	❌	Identifier for the widget a slot belongs to. This information is available as part of the Recommendations API response payload.
`routeId`	`GUID`	❌	Route identifier that led to the widget display. This information is available as part of the Recommendations API response payload.
`recommenderId`	`GUID`	❌	Identifier of the recommender that populated the slot.
`campaignId`	`GUID`	❌	Identifier of the campaign that populated the slot.
`tacticId`	`GUID`	❌	Identifier of the tactic that populated the slot.
`tacticLabel`	`string`	❌	Human-readable label for the tactic that populated the slot.
`bannerId`	`GUID`	❌	Identifier of the banner if the add to cart is related to a banner element.
`placementId`	`GUID`	❌	Identifier for the placement position where the add to cart occurred.
`keywordId`	`GUID`	❌	Identifier for the keyword that triggered the recommendation leading to the add to cart.

Route, Widget & Tactic

Route ID, Widget ID and Tactic ID are important for tracking the performance and effectiveness of the recommendation strategies. These are available as part of the Recommendations API response payload from where the slot's data was collected. Please refer to the Recommendations API documentation and Personalization Overview page for more information.

Retailer Boost Campaign

The following properties are related to the Retailer Boost event tracking and are used for Retailer Boost analytics and reporting.

Parameter	Type	Required	Description
`retailBoostCollectionCampaignId`	`GUID`	❌	The identifier of the `Retailer Boost Collection Campaign`. This is provided as part of the slot data for the product in the Recommendations API response payload.

Retail Media

The following properties are related to the Retail Media event tracking and are used for Retail Media analytics and spend calculation.

Parameter	Type	Required	Description
`adSetId`	`GUID`	❌	The identifier of the `Ad Set`. This is provided as part of the slot data for the product in the Recommendations API response payload.
`adSetVersion`	`integer`	❌	The version of the `Ad Set`. This is provided as part of the slot data for the product in the Recommendations API response payload.
`costPerClick`	`decimal`	❌	The cost per click on a sponsored slot. This is provided as part of the slot data for the product in the Recommendations API response payload.
`costPerAction`	`decimal`	❌	The cost per action on a sponsored slot, if applicable. This is provided as part of the slot data for the product in the Recommendations API response payload.
`costPerMille`	`decimal`	❌	The cost per mille on a sponsored slot, if applicable. This is provided as part of the slot data for the product in the Recommendations API response payload.
`timeStamp`	`timestamp`	❌	The timestamp provided as part of the product's slot data in the Recommendations API response payload. This is the timestamp when the slot was populated.
`hmacSalt`	`string`	❌	String of 16 random characters generated by recommender. Used for calculating and validating HMAC field. This is provided as part of the slot data for the product in the Recommendations API response payload.
`hmac`	`string`	❌	The hash-based message authentication code (HMAC) generated using the `adSetId`, `hmacSalt`, `costPerClick`, `timeStamp`. This is used to validate the authenticity of the slot impression event. This is provided as part of the slot data for the product in the Recommendations API response payload.
`supplierId`	`GUID`	❌	The identifier of the supplier associated with the retail media campaign.

note

If sending Retail Media tracking data, the cost parameters, timestamp, and HMAC-related fields are recommended to be included for proper analytics.

The keywordId is only needed if the Retail Media slot was populated as part of a Keyword Targeting campaign.

Example Request Payload

{
  "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "events": [
    {
      "currentUrl": "https://www.example.com/products/product-123",
      "eventTime": "2024-03-01T14:00:00.000Z",
      "product": {
        "refId": "product-123",
        "quantity": 2,
        "price": 49.99
      },
      "referralUrl": "https://www.example.com/category/clothing",
      "clickId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "tacticLabel": "Featured Products",
      
      // Retailer Boost event tracking
      "retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
      
      // Retail Media event tracking
      "adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "adSetVersion": 1,
      "costPerClick": 0.5,
      "costPerAction": 1.0,
      "costPerMille": 0.25,
      "timeStamp": 638481477292391000,
      "hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
      "hmac": "xxxxxxxxxxxxxxxxxxxxxxx"
    }
  ]
}

Response

On Success

On successful post, the returned status code will be 202, and the payload will contain the status message "Accepted" and a transaction ID.

{
  "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "status": "Accepted"
}

On Error

If there are any errors, the response status code will not be 202, and the relevant error messages will be provided as part of "errors" in the returned message. Here is an example:

{
  "errors": {
    "events[0].Product.RefId": [
      "'RefId' must not be empty."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "xxxxxxxxxxxxxxxxxxx"
}

Example Usage (JavaScript)

Here's an example code snippet using JavaScript's Fetch API:

const url = 'https://<PA_END_POINT>/3.0/events/add-to-carts';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
  customerId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  events: [
    {
      currentUrl: 'https://www.example.com/products/product-123',
      eventTime: '2024-03-01T14:00:00.000Z',
      product: {
        refId: 'product-123',
        quantity: 2,
        price: 49.99
      },
      widgetId: 'xxxxxxxxxxxxxxxxxxxxxxx',
      routeId: 'xxxxxxxxxxxxxxxxxxxxxxx',
      recommenderId: 'xxxxxxxxxxxxxxxxxxxxxxx',
      
      // Retail Media tracking
      adSetId: 'xxxxxxxxxxxxxxxxxxxxxxx',
      adSetVersion: 1,
      costPerClick: 0.5,
      timeStamp: 638481477292391000,
      hmacSalt: 'xxxxxxxxxxxxxxxxxxxxxxx',
      hmac: 'xxxxxxxxxxxxxxxxxxxxxxx'
    }
  ]
};

fetch(url, {
  method: 'POST',
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(data => console.log('Add to Cart Recorded:', data))
  .catch(error => console.error('Error recording Add to Cart:', error));

Summary

This document provides details about the Add to Cart API, which is essential for tracking user purchase intent in your eCommerce application:

The API is used to capture customer add to cart activities for analytics, personalization, and abandoned cart analysis
The endpoint uses a POST method with URL https://<PA_END_POINT>/3.0/events/add-to-carts
Required parameters include customer ID, session ID, current URL, event time, and product information (refId and quantity)
Optional parameters allow for more detailed tracking, including widget, route, and campaign information
Special parameters for retail media and retailer boost provide comprehensive attribution
The API returns a 202 status code with a transaction ID on successful recording
Error responses include relevant error messages and a 400 status code

API Endpoint​

Request Header​

Request Parameters (Body)​

Event Object Definition​

Retailer Boost Campaign​

Retail Media​

Example Request Payload​

Response​

On Success​

On Error​

Example Usage (JavaScript)​

Summary​