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.

• Method: POST

• URL: https://<PA_END_POINT>/3.0/events/checkouts

• 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 detailing Checkout event. Each Checkout event object will contain following properties:

    • eventTime (dateTime) [REQUIRED]: UTC timestamp of when the checkout happened.

    • products: Array of product objects in the cart.

      • refId (string) [REQUIRED]: Product reference ID.

      • quantity (integer) [REQUIRED]: Number of units of the product.

    • subTotal (decimal) [REQUIRED]: Subtotal of the cart.

    • discount (decimal): Discount for the cart.

    • totalPrice (decimal) [REQUIRED]: Total price of the cart.

    • currencyCode (string) [REQUIRED]: Currency in which the transaction was processed.

    • deliveryFee (decimal, optional): Shipping cost, if applicable.

• Here is an example 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",
            },
            {
              "refId": "231673",
              "quantity": 3
            }
          ],
        "subTotal": 123.21,
        "discount": 11.5,
        "totalPrice": 115.5,
        "currencyCode": "AUD",
        // Optional
        "deliveryFee": 5,
      }
    ]
  }

• Returned Payload

  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"
  }

  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"
  }

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"
      },
      {
        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.