Skip to main content
POST
/
beacon
Tracking API: Capture Events
curl --request POST \
  --url https://cl.uselayers.com/beacon \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "events": [
    {
      "event_type": "<string>",
      "timestamp": "<string>",
      "session_id": "<string>",
      "device_id": "<string>",
      "attribution_token": "<string>",
      "product_id": 123,
      "variant_id": 123,
      "collection_handle": "<string>",
      "query": "<string>",
      "position": 123
    }
  ]
}
'
POST https://cl.uselayers.com/beacon

{
  "events": [
    {
      "event_type": "product_click",
      "timestamp": "2025-01-15T14:30:00Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 3
    },
    {
      "event_type": "collection_view",
      "timestamp": "2025-01-15T14:29:45Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "collection_handle": "summer-collection"
    },
    {
      "event_type": "block_view",
      "timestamp": "2025-01-15T14:30:15Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd"
    }
  ]
}

​
Authorization

​
X-Storefront-Access-Token
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

​
Headers

​
Content-Type
string
default:"application/json"
required
​
Accept
string
default:"application/json"
required

​
Body

​
events
array
required
Each object in the array represents a single storefront event.

​
Behavior

  • Returns HTTP 204 (No Content) on success
  • Events are batched and processed asynchronously
  • Invalid events within a batch are silently skipped without affecting valid events
  • The beacon endpoint is optimized for low-latency ingestion
If you are using the Storefront Pixel, events are automatically captured and sent to this endpoint. You only need to call this API directly if you are building a custom integration without the pixel.
POST https://cl.uselayers.com/beacon

{
  "events": [
    {
      "event_type": "product_click",
      "timestamp": "2025-01-15T14:30:00Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 3
    },
    {
      "event_type": "collection_view",
      "timestamp": "2025-01-15T14:29:45Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "collection_handle": "summer-collection"
    },
    {
      "event_type": "block_view",
      "timestamp": "2025-01-15T14:30:15Z",
      "session_id": "abc123",
      "device_id": "device-uuid",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd"
    }
  ]
}