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"
    }
  ]
}

`autocomplete_click`

Sent when a shopper selects a suggestion from the autocomplete panel. search_query is the selected suggestion, and contextual_data records what the shopper typed, the 1-indexed position of the suggestion, and which section of the panel it came from.

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V7A",
      "event_type": "autocomplete_click",
      "timestamp": "2026-06-01T14:29:59Z",
      "session_id": "sess_abc123",
      "search_query": "linen midi dress",
      "contextual_data": {
        "typed_query": "linen",
        "position": 2,
        "selection_source": "query_suggestion"
      }
    }
  ]
}

If the shopper’s selection triggers a full search, follow with a search event whose contextual_data.search_source is "autocomplete" so the two events can be joined into a funnel.

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V7B",
      "event_type": "search",
      "timestamp": "2026-06-01T14:30:00Z",
      "session_id": "sess_abc123",
      "search_query": "linen midi dress",
      "contextual_data": {
        "search_source": "autocomplete"
      }
    }
  ]
}

`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"
    }
  ]
}

`content_view`

Sent when a shopper views an article or page recommended by a related content block. content_type is "article" or "page".

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0V9",
      "event_type": "content_view",
      "timestamp": "2026-06-01T14:32:00Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "content_type": "article",
      "content_id": 556677889900,
      "content_handle": "summer-style-guide"
    }
  ]
}

`content_click`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0VA",
      "event_type": "content_click",
      "timestamp": "2026-06-01T14:31:55Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "content_type": "article",
      "content_id": 556677889900,
      "content_handle": "summer-style-guide"
    }
  ]
}

`content_impression`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0VB",
      "event_type": "content_impression",
      "timestamp": "2026-06-01T14:31:50Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "content_type": "page",
      "content_id": 998877665544,
      "content_handle": "size-guide"
    }
  ]
}

`banner_impression`

Sent when a merchandising banner enters the viewport. banner_id and rule_id come straight off the banner object in the Browse response.

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0VC",
      "event_type": "banner_impression",
      "timestamp": "2026-06-01T14:30:20Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "banner_id": "01KWD5S5R50690NXFW32PXM0V2",
      "rule_id": "bd2d34eb-0d87-4299-90ee-ffeb572a12f6",
      "banner_type": "link",
      "banner_mode": "inject",
      "web_position": 1,
      "mobile_position": 1
    }
  ]
}

`banner_click`

{
  "events": [
    {
      "event_id": "01HZY8E2K3M4N5P6Q7R8S9T0VD",
      "event_type": "banner_click",
      "timestamp": "2026-06-01T14:30:35Z",
      "session_id": "sess_abc123",
      "attribution_token": "2y10smI2dB7XZXXFJsLUELltgueq8NRd",
      "banner_id": "01KWD5S5R50690NXFW32PXM0V2",
      "rule_id": "bd2d34eb-0d87-4299-90ee-ffeb572a12f6",
      "banner_type": "link",
      "banner_mode": "inject",
      "web_position": 1,
      "mobile_position": 1
    }
  ]
}

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`

`autocomplete_click`

`block_view`

`content_view`

`content_click`

`content_impression`

`banner_impression`

`banner_click`

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

​autocomplete_click

​block_view

​content_view

​content_click

​content_impression

​banner_impression

​banner_click

​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`

`autocomplete_click`

`block_view`

`content_view`

`content_click`

`content_impression`

`banner_impression`

`banner_click`

Batched events

With UTM and contextual data

App / native shopping channel