Event: Purchase

The Purchase Event captures detailed anonymized transaction data when customers convert. It is triggered on the confirmation page of a website, recording all items purchased. This event is essential for analyzing customer purchase behavior for model training and is a crucial component of Analytics in Discovery OS.

API Endpoint

Method: POST
URL: https://<PA_END_POINT>/3.0/events/purchases

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 `Purchase` event. Each `Purchase` event object will contain the following properties:
event's object defination
`currentUrl`	`string`	✅	URL where the `purchase` occurred.
`eventTime`	`dateTime`	✅	UTC timestamp of when the search happened.
`orderId`	`string`	✅	Unique identifier for the order.
`paymentMethod`	`string`	✅	Payment method used (e.g., Credit Card).
`currencyCode`	`string`	✅	Currency code for the transaction.

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.
`price`	`decimal`	❌	Price of each product.
`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, Widget & Tactic

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.

note

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.

note

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 Media Keyword Targeting campaign, this field should be populated with the keywordId. The keywordId is generated as part of the search-keywords event. The search-keywords event is triggered when the Recommendations API is called with a specific keyword 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,
                    "price": 132.23,

                    // 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,
                    "price": 148.23
                }
            ],
            "orderId": "O12345678910",
            "paymentMethod": "Credit Card",
            "currencyCode": "AUD"
        }
    ]
}

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": {
        "products[0].RefId": [
            "Product must contain a RefId"
        ]
    },
    "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/purchases';
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,
                    price: 132.23,

                    // 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,
                    price: 148.23
                }
            ],
            orderId: "O12345678910",
            paymentMethod: "Credit Card",
            currencyCode: "AUD"
        }
    ]
};
fetch(url, {
    method: 'POST',
    headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(data => console.log('Purchase Recorded:', data))
  .catch(error => console.error('Error recording purchase:', error));

Summary

This document provides details about the Purchase Event API, including its method, URL, request body parameters, example payload, and response scenarios.

The Purchase Event API uses a POST method and is accessed via the URL https://<PA_END_POINT>/3.0/events/purchases.
Request body parameters include customer and session identifiers, event details such as current URL and products, order information, payment method, and currency code.
An example payload demonstrates the structure of data to be sent with the API request.
Successful updates return a status code of "202" with the message "Accepted" and a transaction ID in the payload.
In case of errors, relevant error messages are provided along with the status code and trace ID in the response.

API Endpoint​

Request Header​

Request Parameters (Body)​

Array of products​

Retailer Boost Campaign​

Retail Media​

Example Request Payload​

Response​

On Success​

On Error​

Example Usage (JavaScript)​

Summary​