Tracking API overview

The Tracking API is a REST API for sending customer events and properties directly to Bloomreach from your server. Use it when you need to track events outside the browser — for example, to include sensitive data such as order costs and margins in a purchase event, or to track events triggered by backend processes that have no browser context.

The JavaScript SDK uses this same API internally. If you're tracking from a web browser, use the Bloomreach Web SDK instead of calling the API directly.

API endpoint and authentication

All requests follow the following endpoint format:

POST https://TARGET_BASE_URL/track/u/v1/batch?stream_id=YOUR_STREAM_ID

• Replace TARGET_BASE_URL with your Bloomreach API Target URL. Find it in Data Hub > Workspace settings > Access Management > API > API Credentials.
• The stream_id parameter identifies which event stream your data is sent to. Find your stream_id in Data Hub > Event streams > select your stream > Access security.

For authentication setup, including how to create API groups and generate API keys, see Data Hub API prerequisites.

Required headers for server-side tracking

When tracking from your server, it intercepts the original HTTP request from the visitor's browser. That request contains the visitor's IP address and User-Agent string. Pass these through to the Tracking API so Bloomreach can use them for geolocation and device-based audience targeting.

📘

Note

Discovery requires the client IP address and User-Agent for accurate geolocation of conversion events. Omitting these headers degrades Discovery's location-based reporting and device audience segmentation.

Include the following headers in every server-side request:

The X-Forwarded-For header is the standard way to pass the original client IP address through a proxy. Bloomreach parses the client IP from this header — it cannot infer it from the server's IP address.

Request format

All Tracking API requests use a batch command structure. The request body is a JSON object with a single commands array. Each item in the array is a command object with a name and a data payload.

{
  "commands": [
    {
      "name": "customers/events",
      "data": { ... }
    }
  ]
}

The name field identifies the type of operation. The two supported command names are:

• customers/events: tracks a customer event with properties
• customers: updates customer properties

You can include multiple commands in a single batch request. For the full request and response schema for each command type, see the individual endpoint references in the API reference.

API request example

The following example tracks a purchase event using server-side tracking. The metadata block includes _br_uid_2, which is required when tracking purchases server-side. The Bloomreach Web SDK adds this automatically for browser-side tracking, but your server must explicitly pass it.

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": {
          "email_id": "[email protected]"
        },
        "type": "purchase",
        "properties": {
          "purchase_id": "ID123",
          "purchase_status": "created",
          "total_price": 107.72,
          "local_currency": "EUR",
          "price_local_currency": 99.98,
          "product_list": [
            {
              "title": "Yellow wide sweater with turtleneck",
              "product_id": "119479",
              "variant_id": "MJ12199-0400",
              "price": 53.86,
              "price_local_currency": 49.99,
              "quantity": 2
            }
          ],
          "location": "https://www.pacific.com/en/order_complete",
          "referrer": "https://www.pacific.com/en/checkout"
        },
        "metadata": {
          "_br_uid_2": "uid=7080827054609:v=cde-v3.38.0:ts=1741771054202:hc=6",
          "domain_key": "Pacific",
          "view_id": "en_US"
        },
        "timestamp": 1749545984.278
      }
    }
  ]
}

What's next?

• API reference: Full endpoint reference for all Tracking API commands
• Required events: Event schemas, property references, and additional API request examples
• Bloomreach Web SDK: Use the SDK for browser-side tracking instead of calling the API directly