Event: Add To Cart
The Add To Cart event is essential for tracking all ‘Add to Cart’ activities. This includes interactions with native Add To Cart buttons as well as with Add To Cart call-to-action (CTA) buttons on Particular Audience widgets, especially those in bundle displays.
This event is crucial for capturing data on user purchase intent and plays a significant role in the analytics provided by Discovery OS.
-
Method:
POST
-
URL:
https://<PA_END_POINT>/3.0/events/add-to-carts
-
Headers:
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
-
Request Body Parameters:
-
customerId (GUID)
[REQUIRED]: 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)
[REQUIRED]: 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 detailingAdd To Cart
event. EachAdd To Cart
event object will contain following properties:-
currentUrl (string)
: URL where theAdd To Cart
event occurred. -
eventTime (dateTime)
[REQUIRED]: UTC timestamp when the item was added to the cart. -
product
: Object containing product details.-
refId (string)
[REQUIRED]: Product reference ID. -
quantity (integer)
[REQUIRED]: Quantity of the product added to the cart.
-
-
referralUrl (string)
: URL from which the user was referred (if applicable).infoThe following information is optional but recommended for tracking purposes. 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.
Widget ID
,Route ID
andTactic ID
are important for tracking the performance and effectiveness of the recommendation strategies.noteThese are only relevant if the product was displayed in a widget (e.g. Recommendation panel, Bundle, Search Result etc.), and the user added the product from the widget.
-
widgetId (GUID)
: Identifier for the widget from which the product was added (if applicable). -
routeId (GUID)
: Identifier of the route where the widget was displayed (if applicable). -
recommenderId (GUID)
: Identifier of the recommender that populated the slot (if applicable). -
campaignId (GUID)
: Identifier of the campaign that populated the slot (if applicable). -
tacticId (GUID)
: Identifer of the tactic that populated the slot (if applicable).
Retailer Boost CampaignThe following properties are related to the Retailer Boost event tracking and are required to be sent as part of the
event
object in the payload for Retailer Boost analytics and reporting.retailBoostCollectionCampaignId (GUID)
: The identifier of theRetailer Boost Collection Campaign
. This is provided as part of the slot data for the product in the Recommendations API response payload.
Retail MediaThe following properties are related to the Retail Media event tracking and are required to be sent as part of the
event
object in the payload for Retail Media analytics and spend calculation.-
adSetId (GUID)
: The identifier of theAd Set
. This is provided as part of the slot data for the product in the Recommendations API response payload. -
adSetVersion (integer)
: The version of theAd 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 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 theadSetId
,hmacSalt
,costPerClick
,timeStamp
. This is used to validate the authenticity of the click event. This is provided as part of the slot data for the product in the Recommendations API response payload.noteThe
keywordId
is only required if the Retail Media slot was populated as part of theKeyword Targeting
campaign. -
keywordId (GUID)
: Client generated Id. If a slot was displayed as part of the Retail MediaKeyword Targeting
campaign, this field should be populated with thekeywordId
. ThekeywordId
is generated as part of thesearch-keywords
event. Thesearch-keywords
event is triggered when theRecommendations API
is called with a specifickeyword
to retrieve the Retail Media slots for that keyword.
-
-
-
Here is an example payload:
{
"customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
"sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
"events": [
{
"currentUrl": "https://www.example.com/",
"eventTime": "1970-01-01T14:00:00.000Z",
"product": {
"refId": "1234",
"quantity": 2
},
"referralUrl": "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
"widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
"routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
"recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
"campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
"tacticId": "xxxxxxxxxxxxxxxxxxxxxxx"
// The following are only relevant to the Retailer Boost event tracking
"retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
// The following are only relevant to the Retail Media event tracking
"adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
"adSetVersion": 1,
"costPerClick": 0.5,
"timeStamp": 638481477292391000,
"hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
"hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
"keywordId": "xxxxxxxxxxxxxxxxxxxxxxx"
}
]
} -
Returned Payload
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"
}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": [
"'Product Ref Id' 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"
}
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/",
eventTime: "1970-01-01T14:00:00.000Z",
product: {
refId: "1234",
quantity: 2
},
referralUrl: "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
widgetId: "xxxxxxxxxxxxxxxxxxxxxxx",
routeId: "xxxxxxxxxxxxxxxxxxxxxxx",
recommenderId: "xxxxxxxxxxxxxxxxxxxxxxx",
campaignId: "xxxxxxxxxxxxxxxxxxxxxxx",
tacticId: "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 is about the Add To Cart API, including its method, URL, request body parameters, example payload, and responses.
-
The method for this API is POST with a URL of
https://<PA_END_POINT>/3.0/events/add-to-carts
. -
Request body parameters include customer ID, session ID, and an array of objects detailing each add-to-cart action.
-
An example payload is provided in JSON format, demonstrating the structure of the request body.
-
On successful update, the returned status code will be ‘202’, and the payload will contain the status message "Accepted" and a transaction ID.
-
If there are any errors, the response status code will not be ‘202’, and relevant error messages will be provided as part of "errors" in the returned message.