Payload examples

Every example below is a full POST https://cl.uselayers.com/beacon body. Swap the session_id, event_id, product_id, and attribution_token values for the real ones from your storefront. The event_id should be a fresh ULID or UUID per event. Generate one with crypto.randomUUID() in the browser, or any ULID library.

Single event

`product_view`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V1",
      "event_type": "product_view",
      "timestamp": "2026-06-01T14:30:00Z",
      "session_id": "sess_abc123",
      "customer_id": "shopify-customer-987654321",
      "product_id": 7003338965178,
      "variant_id": 41234567890123,
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd"
    }
  ]
}

`product_click`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V2",
      "event_type": "product_click",
      "timestamp": "2026-06-01T14:30:05Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 3
    }
  ]
}

`product_impression`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V3",
      "event_type": "product_impression",
      "timestamp": "2026-06-01T14:30:02Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 3
    }
  ]
}

`add_to_cart`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V4",
      "event_type": "add_to_cart",
      "timestamp": "2026-06-01T14:31:18Z",
      "session_id": "sess_abc123",
      "customer_id": "shopify-customer-987654321",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "variant_id": 41234567890123
    }
  ]
}

`collection_view`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V5",
      "event_type": "collection_view",
      "timestamp": "2026-06-01T14:29:45Z",
      "session_id": "sess_abc123",
      "collection_handle": "summer-collection"
    }
  ]
}

`search`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V6",
      "event_type": "search",
      "timestamp": "2026-06-01T14:30:00Z",
      "session_id": "sess_abc123",
      "search_query": "linen midi dress",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd"
    }
  ]
}

`autocomplete`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V7",
      "event_type": "autocomplete",
      "timestamp": "2026-06-01T14:29:58Z",
      "session_id": "sess_abc123",
      "search_query": "linen"
    }
  ]
}

`block_view`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V8",
      "event_type": "block_view",
      "timestamp": "2026-06-01T14:30:15Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "block_id": "blk_recommended_for_you"
    }
  ]
}

Batched events

Group everything that happened in the last few seconds into one request. The worker dispatches each event independently to its configured pipeline.

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W1",
      "event_type": "collection_view",
      "timestamp": "2026-06-01T14:29:45Z",
      "session_id": "sess_abc123",
      "collection_handle": "summer-collection"
    },
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W2",
      "event_type": "product_impression",
      "timestamp": "2026-06-01T14:29:47Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 1
    },
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W3",
      "event_type": "product_impression",
      "timestamp": "2026-06-01T14:29:47Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965179,
      "position": 2
    },
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W4",
      "event_type": "product_click",
      "timestamp": "2026-06-01T14:30:05Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "position": 1
    },
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W5",
      "event_type": "product_view",
      "timestamp": "2026-06-01T14:30:06Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178
    },
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0W6",
      "event_type": "add_to_cart",
      "timestamp": "2026-06-01T14:31:18Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "product_id": 7003338965178,
      "variant_id": 41234567890123
    }
  ]
}

With UTM and contextual data

Use marketing_* for attribution and contextual_data for any structured extras (A/B bucket, locale, page template).

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0X1",
      "event_type": "product_view",
      "timestamp": "2026-06-01T14:30:00Z",
      "session_id": "sess_abc123",
      "product_id": 7003338965178,
      "marketing_source": "google",
      "marketing_medium": "cpc",
      "marketing_campaign": "summer-sale-2026",
      "contextual_data": {
        "locale": "en-US",
        "page_template": "product.alt-gallery",
        "ab_bucket": "ranking_v3"
      }
    }
  ]
}

App / native shopping channel

Send shopping_channel: "app" explicitly when you can’t rely on User-Agent inference. The worker also auto-detects Tapcart and Fuego via the X-Requested-With header.

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0Y1",
      "event_type": "product_view",
      "timestamp": "2026-06-01T14:30:00Z",
      "session_id": "sess_app_xyz789",
      "shopping_channel": "app",
      "product_id": 7003338965178
    }
  ]
}

Getting Started

Reference

Guides

Payload examples

Single event

`product_view`

`product_click`

`product_impression`

`add_to_cart`

`collection_view`

`search`

`autocomplete`

`block_view`

Batched events

With UTM and contextual data

App / native shopping channel

​Single event

​product_view

​product_click

​product_impression

​add_to_cart

​collection_view

​search

​autocomplete

​block_view

​Batched events

​With UTM and contextual data

​App / native shopping channel

Single event

`product_view`

`product_click`

`product_impression`

`add_to_cart`

`collection_view`

`search`

`autocomplete`

`block_view`

Batched events

With UTM and contextual data

App / native shopping channel