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.

• Method: POST

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

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

    • currentUrl (string): The URL where the Purchase event occurred.

    • 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.

      • price (decimal) [REQUIRED]: Price of each product.

    • orderId (string) [REQUIRED]: Unique identifier for the order.

    • paymentMethod (string) [REQUIRED]: Payment method used (e.g., Credit Card).

    • currencyCode (string) [REQUIRED]: Currency code for the transaction.

• 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,
                      "price": 132.23
                  },
                  {
                      "refId": "231673",
                      "quantity": 3,
                      "price": 148.23
                  }
              ],
              "orderId": "O12345678910",
              "paymentMethod": "Credit Card",
              "currencyCode": "AUD",
          }
      ]
  }

• 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": {
          "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"
  }

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