Event: Checkout
The Checkout Event is designed to track checkout activities by capturing all items in the cart. This event plays a crucial role in analyzing customer browsing and buying behavior, and is integral to analytics in Discovery OS, focusing on SKU-level attribution and algorithm-level engagement analytics.
This event must be triggered when a customer clicks the Checkout button. Correct implementation ensures real-time analysis of cart contents, providing valuable insights into consumer purchase intent and patterns. Improper handling may lead to inaccurate data collection, affecting the overall analytics outcome.
API Endpoint
Method: POST
URL: https://<PA_END_POINT>/3.0/events/checkouts
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 Checkout event. Each Checkout event object will contain the following properties: |
event's object defination | |||
currentUrl | string | ✅ | URL where the checkout occurred. |
eventTime | dateTime | ✅ | UTC timestamp of when the search happened. |
subTotal | decimal | ✅ | Subtotal of the cart. |
discount | decimal | ❌ | Discount for the cart. |
totalPrice | decimal | ✅ | Total price of the cart. |
currencyCode | string | ✅ | Currency in which the transaction was processed. |
deliveryFee | decimal | ❌ | Shipping cost, if applicable. |
Array of products
The following properties are related to the product and are required to be sent as part of the event
object in the payload for products object and atleast one product infrmation is required. For details information please check the example payload section.
Parameter | Type | Required | Description |
---|---|---|---|
refId | string | ✅ | Product reference ID. |
quantity | integer | ✅ | Number of units of the product and it should be greater than 0. |
referralUrl | string | ❌ | URL from which the user was referred (if applicable). |
widgetId | GUID | ✅ | Identifier for the widget the slot belongs to. This information is available as part of the Recommendations API response payload from where the slot’s data was collected. |
routeId | GUID | ✅ | Route identifier that led to the widget display. This information is available as part of the Recommendations API response payload from where the slot’s data was collected. |
recommenderId | GUID | ❌ | Identifier of the recommender that populated the slot. This information is available as part of the Recommendations API response payload from where the slot’s data was collected. |
campaignId | GUID | ❌ | Identifier of the campaign that populated the slot. This information is available as part of the Recommendations API response payload from where the slot’s data was collected. |
tacticId | GUID | ❌ | Identifier of the tactic that populated the slot. This information is available as part of the Recommendations API response payload from where the slot’s data was collected. |
Route ID
, Widget ID
and Tactic ID
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
and Tactic ID
are important for tracking the performance and effectiveness of the recommendation strategies.
These 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.
Retailer Boost Campaign
The following properties are related to the Retailer Boost event tracking and are required to be sent as part of the product
object in the products
array of the event
object in the payload 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 required to be sent as part of the product
object in the products
array of the event
object in the payload 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 OR costPerAction OR costPerMille | decimal | ✅ | The cost per click/cost per action/cost per mille 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 the adSetId , hmacSalt , costPerClick (costPerAction ,costPerMille ), 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. |
The keywordId
is only required if the Retail Media slot was populated as part of the Keyword 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. :::
Example Request Payload
{
"customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
"sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
"events": [
{
"currentUrl": "https://www.example.com/",
"eventTime": "2024-03-01T14:00:00.000Z",
"products": [
{
"refId": "23123",
"quantity": 2,
"widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
"routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
"recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
"campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
"tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",
"referralUrl": "https://www.example.com/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, // OR "costPerAction": 0.5 OR "costPerMille": 10
"timeStamp": 638481477292391000,
"hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
"hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
"keywordId": "xxxxxxxxxxxxxxxxxxxxxxx"
},
{
"refId": "231673",
"quantity": 3
}
],
"subTotal": 123.21,
"discount": 11.5,
"totalPrice": 115.5,
"currencyCode": "AUD",
"deliveryFee": 5
}
]
}
Response
On Success
On successful update, 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].Products[0].RefId": [
"'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"
}
Example Usage (JavaScript)
Here’s an example code snippet using JavaScript’s Fetch API:
const url = 'https://<PA_END_POINT>/3.0/events/checkouts';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
customerId: 'xxxxxxxxxxxxxxxxxxxxxxx',
sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
events: [
{
currentUrl: "https://www.example.com/",
eventTime: "2024-03-01T14:00:00.000Z",
products: [
{
refId: "23123",
quantity: 2,
widgetId: "xxxxxxxxxxxxxxxxxxxxxxx",
routeId: "xxxxxxxxxxxxxxxxxxxxxxx",
recommenderId: "xxxxxxxxxxxxxxxxxxxxxxx",
campaignId: "xxxxxxxxxxxxxxxxxxxxxxx",
tacticId: "xxxxxxxxxxxxxxxxxxxxxxx",
referralUrl: "https://www.example.com/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, // OR "costPerAction": 0.5 OR "costPerMille": 10
timeStamp: 638481477292391000,
hmacSalt: "xxxxxxxxxxxxxxxxxxxxxxx",
hmac: "xxxxxxxxxxxxxxxxxxxxxxx",
keywordId: "xxxxxxxxxxxxxxxxxxxxxxx"
},
{
refId: "231673",
quantity: 3
}
],
subTotal: 123.21,
discount: 11.5,
totalPrice: 115.5,
currencyCode: "AUD",
deliveryFee: 5
}
]
};
fetch(url, {
method: 'POST',
headers: {
"Authorization": `Bearer ${accessToken}`,
"Content-Type": "application/json"
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(data => console.log('Checkout Recorded:', data))
.catch(error => console.error('Error recording checkout:', error));
Summary
This document is about the Checkout Event API, its design, method, URL, request body parameters, example payload, and responses.
- The Checkout Event API captures customer checkout activities for real-time analysis of cart contents.
- The method for this API is POST, and the URL is
https://<PA_END_POINT>/3.0/events/checkouts
. - Request body parameters include customer and session identifiers, checkout event details, pricing information, and optional delivery fee.
- An example payload demonstrates the structure of the request body with product details and pricing information.
- Successful update returns a status code of
202
with the status message "Accepted" and a transaction ID.