Event: Checkout

The Checkout event is critical for tracking customer checkout activities, which help in analyzing purchase funnel conversion rates. This data allows for real-time analytics of customer interactions with products in the checkout process.

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 events. Each checkout event object will contain the properties defined below.

Event Object Definition

Parameter	Type	Required	Description
`currentUrl`	`string`	✅	URL where the checkout occurred.
`eventTime`	`dateTime`	✅	UTC timestamp of when the checkout happened.
`subTotal`	`decimal`		Sub-total amount of the checkout (excluding tax, shipping, etc.).
`discount`	`decimal`		Discount amount applied to the checkout.
`totalPrice`	`decimal`		Total price of the checkout (including tax, shipping, etc.).
`deliveryFee`	`decimal`		Delivery fee for the checkout.
`currencyCode`	`string`		Currency code for the checkout (3-letter ISO currency code).
`products`	`Array of objects`	✅	An array of product objects. At least one product's information is required. See Product Object for details.
`priceBeatPromotions`	`Array of objects`		An array of Price Beat promotion code objects. See Price Beat Promotion Codes for details.

Product Object

Each product in the products array contains the following properties:

Parameter	Type	Required	Description
`refId`	`string`	✅	Product reference ID.
`quantity`	`integer`	✅	Quantity of the product being checked out.
`price`	`decimal`		Unit price of the product.

Product Attribution Fields

Each product can include the following additional properties for attribution and tracking:

Parameter	Type	Description
`routeId`	`GUID`	Identifier of the route where the product was displayed.
`widgetId`	`GUID`	Identifier of the widget where the product was displayed.
`recommenderId`	`GUID`	Identifier of the recommender that displayed the product.
`campaignId`	`GUID`	Identifier of the campaign that displayed the product.
`tacticId`	`GUID`	Identifier of the tactic that displayed the product.
`clickId`	`GUID`	Identifier of the click that led to the checkout.
`referralUrl`	`string`	URL where the product was originally displayed.
`tacticLabel`	`string`	Label describing the tactic used.

Retailer Boost Campaign

The following properties are related to the Retailer Boost event tracking and can be included as part of the product object in the payload for Retailer Boost analytics and reporting.

NOTE

The Retailer Boost Campaign fields are only required when tracking products that were recommended through a Retailer Boost Campaign. For standard product checkouts not related to Retailer Boost, these fields can be omitted.

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 can be included as part of the product object in the payload for Retail Media analytics and spend calculation.

NOTE

The Retail Media fields are only required when tracking products that were recommended through a Retail Media Ad Set. For standard product checkouts not related to Retail Media, these fields can be omitted.

Parameter	Type	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 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`, any of the cost fields, `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.
`bannerId`	`GUID`	Identifier of the banner if the product was displayed in a banner slot.
`placementId`	`GUID`	Identifier of the placement where the product was displayed.

note

At least one of the cost parameters (costPerClick, costPerAction, or costPerMille) should be provided if sending Retail Media tracking data.

Price Beat Promotion Codes

If any Price Beat coupon codes are applied to the cart, they should be included in the checkout event. This information is crucial for tracking which Price Beat promotions are being used by customers.

Parameter	Type	Required	Description
`code`	`string`	✅	The Price Beat promotion code applied to the purchase.
`discount`	`decimal`	✅	The discount value of the Price Beat promotion code.

Example Request Payload

{
  "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "events": [
    {
      "currentUrl": "https://www.example.com/checkout/confirmation",
      "eventTime": "1970-01-01T14:00:00.000Z",
      "subTotal": 123.45,
      "discount": 10.00,
      "totalPrice": 145.67,
      "currencyCode": "USD",
      "deliveryFee": 10.00,
      "products": [
        {
          "refId": "product-1",
          "quantity": 2,
          "price": 9.99,
          "routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "clickId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "referralUrl": "https://www.example.com/product/product-1",
          "tacticLabel": "Personalized Recommendation",
          
          "retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
          
          "adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "adSetVersion": 1,
          "costPerClick": 0.5,
          "timeStamp": 638481477292391000,
          "hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
          "hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
          "bannerId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "placementId": "xxxxxxxxxxxxxxxxxxxxxxx"
        },
        {
          "refId": "product-2",
          "quantity": 1,
          "price": 99.99
        }
      ],
      "priceBeatPromotions": [
        {
          "code": "PB10XXXXXXXXX",
          "discount": 10.00
        }
      ]
    }
  ]
}

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].Products[0].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"
}

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/checkout/confirmation',
      eventTime: '1970-01-01T14:00:00.000Z',
      subTotal: 123.45,
      discount: 10.00,
      totalPrice: 145.67,
      currencyCode: 'USD',
      deliveryFee: 10.00,
      products: [
        {
          refId: 'product-1',
          quantity: 2,
          price: 9.99
        },
        {
          refId: 'product-2',
          quantity: 1,
          price: 99.99
        }
      ],
      // Include Price Beat promotion codes if applicable
      priceBeatPromotions: [
        {
          code: 'PB10XXXXXXXXX',
          discount: 10.00
        }
      ]
    }
  ]
};

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 provides details about the Checkout API, which is essential for tracking the checkout process in your eCommerce application:

The API is used to capture customer checkout activities for analytics and conversion tracking
The endpoint uses a POST method with URL https://<PA_END_POINT>/3.0/events/checkouts
Required parameters include customer ID, session ID, and checkout details such as prices, currency, and product information
Optional attribution fields help track which recommendations, campaigns, and tactics influenced the checkout
Retail Media and Retailer Boost fields enable detailed analytics and spend calculation
Price Beat promotion codes can be included to track which promotions are being used
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
JavaScript example demonstrates how to implement the API call in your application

API Endpoint​

Request Header​

Request Parameters (Body)​

Event Object Definition​

Product Object​

Product Attribution Fields​

Retailer Boost Campaign​

Retail Media​

Price Beat Promotion Codes​

Example Request Payload​

Response​

On Success​

On Error​

Example Usage (JavaScript)​

Summary​