Event: Purchase

The Purchase event is used to track successful purchase completions. Recording these events is crucial for analytics, including purchase conversion analysis and tracking customer buying patterns.

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 events. Each purchase event object will contain the following properties:

Event Object Definition

Parameter	Type	Required	Description
`currentUrl`	`string`	✅	URL where the purchase was completed.
`eventTime`	`dateTime`	✅	UTC timestamp of when the purchase occurred.
`orderNumber`	`string`	✅	Order number or reference for the purchase.
`subTotal`	`decimal`	✅	Sub-total amount of the purchase (excluding tax, shipping, etc.).
`totalPrice`	`decimal`	✅	Total price of the purchase (including tax, shipping, etc.).
`currencyCode`	`string`	✅	Currency code for the purchase (3-letter ISO currency code).
`deliveryFee`	`decimal`	❌	Delivery fee for the purchase.
`taxAmount`	`decimal`	❌	Tax amount for the purchase.
`products`	`Array of objects`	✅	An array of product objects. At least one product's information is required. Each product object will contain the following properties: `refId (string)` [REQUIRED]: Product reference ID. `quantity (integer)` [REQUIRED]: Quantity of the product purchased. `unitPrice (decimal)` [REQUIRED]: Unit price of the product. `totalPrice (decimal)` [REQUIRED]: Total price for this product (quantity × unit price). `isOnSale (boolean)` [OPTIONAL]: Indicates if the product was purchased on sale. `discount (decimal)` [OPTIONAL]: Discount amount applied to the product. `couponCode (string)` [OPTIONAL]: Coupon code applied to the product.
`PriceBeatPromotionCodes`	`Array of objects`	❌	An array of Price Beat promotion code objects. See Price Beat Promotion Codes for details.

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 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 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`	`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.
`keywordId`	`GUID`	❌	Client generated Id. Required if the Retail Media slot was populated as part of a Keyword Targeting campaign. Generated as part of the search-keywords event.

note

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

The keywordId is only needed if the Retail Media slot was populated as part of a Keyword Targeting campaign. The keywordId is generated as part of the search-keywords event triggered when the Recommendations API is called with a specific keyword.

Price Beat Promotion Codes

If any Price Beat coupon codes are applied to the purchase, they should be included in the purchase event. This information is crucial for tracking which Price Beat promotions are being converted into actual purchases.

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

note

When using Price Beat promotion codes in a purchase event, it's important to mark the coupon as used after the purchase is completed. This prevents the same customer from reusing the same coupon. See Mark Coupon as Used API for details.

If you're using our JavaScript tag on your purchase confirmation page, we will automatically handle marking the coupon as used, and you don't need to make the additional API call.

Example Request Payload

{
  "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
  "events": [
    {
      "currentUrl": "https://www.example.com/purchase/confirmation",
      "eventTime": "1970-01-01T14:00:00.000Z",
      "orderNumber": "ORD-12345",
      "subTotal": 123.45,
      "totalPrice": 145.67,
      "currencyCode": "USD",
      "deliveryFee": 10.00,
      "taxAmount": 12.22,
      "products": [
        {
          "refId": "product-1",
          "quantity": 2,
          "unitPrice": 9.99,
          "totalPrice": 19.98,
          "isOnSale": true,
          "discount": 2.00,
          "couponCode": "SAVE10",
          
          "retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
          
          "adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
          "adSetVersion": 1,
          "costPerClick": 0.5,
          "timeStamp": 638481477292391000,
          "hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
          "hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
          "keywordId": "xxxxxxxxxxxxxxxxxxxxxxx"
        },
        {
          "refId": "product-2",
          "quantity": 1,
          "unitPrice": 99.99,
          "totalPrice": 99.99
        }
      ],
      "PriceBeatPromotionCodes": [
        {
          "Code": "PB10XXXXXXXXX",
          "Value": 10
        }
      ]
    }
  ]
}

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/purchases';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
  customerId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  events: [
    {
      currentUrl: 'https://www.example.com/purchase/confirmation',
      eventTime: '1970-01-01T14:00:00.000Z',
      orderNumber: 'ORD-12345',
      subTotal: 123.45,
      totalPrice: 145.67,
      currencyCode: 'USD',
      deliveryFee: 10.00,
      taxAmount: 12.22,
      products: [
        {
          refId: 'product-1',
          quantity: 2,
          unitPrice: 9.99,
          totalPrice: 19.98,
          isOnSale: true,
          discount: 2.00,
          couponCode: 'SAVE10'
        },
        {
          refId: 'product-2',
          quantity: 1,
          unitPrice: 99.99,
          totalPrice: 99.99
        }
      ],
      // Include Price Beat promotion codes if applicable
      PriceBeatPromotionCodes: [
        {
          Code: 'PB10XXXXXXXXX',
          Value: 10
        }
      ]
    }
  ]
};

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));

Mark Coupon as Used API

After recording a purchase with Price Beat promotion codes, you need to mark the coupon as used to prevent reuse. This step is only necessary if you don't have our JavaScript tag on your purchase confirmation page.

API Endpoint

Method: GET
URL: https://extension.api.similarinc.com/b2b/coupon/mark_as_used

Query Parameters

Parameter	Type	Required	Description
`code`	`string`	✅	The Price Beat promotion code to mark as used.
`client`	`string`	✅	Your client website ID.

Example Usage (JavaScript)

// After recording the purchase with a Price Beat promotion code
const couponCode = 'PB10XXXXXXXXX';
const clientId = 'eab34b0a-47ed-ec11-aae9-02dca44cceec'; // Your client website ID

fetch(`https://extension.api.similarinc.com/b2b/coupon/mark_as_used?code=${encodeURIComponent(couponCode)}&client=${encodeURIComponent(clientId)}`, {
  method: 'GET'
})
.then(response => {
  if (response.ok) {
    console.log('Coupon marked as used successfully');
  } else {
    console.error('Failed to mark coupon as used');
  }
})
.catch(error => console.error('Error marking coupon as used:', error));

Summary

This document provides details about the Purchase API, which is essential for tracking successful transactions in your eCommerce application:

The API is used to capture customer purchase activities for analytics and conversion tracking
The endpoint uses a POST method with URL https://<PA_END_POINT>/3.0/events/purchases
Required parameters include customer ID, session ID, and purchase details such as order number, prices, currency, and product information
Price Beat promotion codes can be included to track which promotions are being converted to purchases
After recording a purchase with Price Beat promotion codes, you need to mark the coupon as used via the Mark Coupon as Used API
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 examples demonstrate how to implement the API calls in your application

API Endpoint​

Request Header​

Request Parameters (Body)​

Event Object Definition​

Retailer Boost Campaign​

Retail Media​

Price Beat Promotion Codes​

Example Request Payload​

Response​

On Success​

On Error​

Example Usage (JavaScript)​

Mark Coupon as Used API​

API Endpoint​

Query Parameters​

Example Usage (JavaScript)​

Summary​

API Endpoint

Request Header

Request Parameters (Body)

Event Object Definition

Retailer Boost Campaign

Retail Media

Price Beat Promotion Codes

Example Request Payload

Response

On Success

On Error

Example Usage (JavaScript)

Mark Coupon as Used API

API Endpoint

Query Parameters

Example Usage (JavaScript)

Summary