---
title: "Event Collector"
description: "The storefront analytics endpoint the SureBright SDK reports to (POST /events/api/event): payload fields, required values, event names, and when a custom storefront has to call it directly."
---

The SDK reports shopper interactions with the protection offer to SureBright's event collector. Those events feed the **Sales** analytics in the merchant portal: how many product views had an offer, how many shoppers looked at a plan, how many added to cart with and without protection, and attach-rate experiments.

If the SDK runs on your pages, it does this for you and you can stop reading. Call the collector yourself only when the SDK cannot see the interaction: a native app, a server-rendered checkout the script cannot run in, or a storefront where you render the offer with your own UI from SureBright quote data. Without these events, that traffic is invisible in Sales analytics.

## Endpoint

```text
POST https://api-external.surebright.com/events/api/event
Content-Type: application/json
```

- **Authentication: none.** The route is deliberately unauthenticated so browsers can post to it; CORS allows any origin. Do not send anything you would not put in a public page.
- The body is always a batch: `{ "eventList": [ ... ] }`. A single event still goes in a one-element array.
- Events are buffered server-side and written asynchronously; the response tells you how many were accepted, not that they were stored.

### Response

```json
{ "isError": false, "acceptedCount": 2, "rejectedCount": 0, "webhookEventsPushedCount": 0 }
```

| Status | Meaning |
| --- | --- |
| `200` with `acceptedCount` / `rejectedCount` | Rejected events failed validation (see below) and were dropped silently. |
| `200` with `{"isError": true, "message": "No events to push"}` | `eventList` was missing or empty. |
| `503` | The server could not buffer the batch. Retry later with the same events. |

## Event fields

Field names are short wire keys. The server maps them to full names; unknown keys are stored as-is under their wire name. Keys the server owns (`_id`, `userAgent`, `receivedAt`, `timestamp`, `metadata`, `productDetailMap`) are ignored if you send them.

<ParamField body="et" type="string" required>
  Event type. One of the names under [Event types](#event-types).
</ParamField>
<ParamField body="sid" type="string" required>
  Store id, as SureBright knows your store (for Shopify, the `*.myshopify.com` domain).
</ParamField>
<ParamField body="etime" type="string" required>
  When the event happened, as a strict ISO 8601 timestamp with a `Z` or `±hh:mm` offset, for example `2026-11-09T14:03:21.512Z`. Anything else (including a missing offset, or an impossible date such as `2026-02-30`) rejects the event.
</ParamField>
<ParamField body="vi" type="string">
  Visit id: a UUID you generate once per browser session and reuse on every event in it. Strongly recommended; if omitted the server stores `INVALID_VISIT` and the event cannot be joined into a funnel.
</ParamField>
<ParamField body="ps" type="string">
  Page source. One of `PRODUCT_PAGE`, `CART_PAGE`, `COLLECTION_PAGE`, `CHECKOUT_PAGE`, `THANK_YOU_PAGE`, `OTHER_PAGE`, `QUICK_VIEW_POPUP`, `CART_POPUP`, or, for events raised from a popup, the popup name (`NUDGE_POPUP`, `ADD_WARRANTY_POPUP`, `LEARN_MORE_POPUP`, `ADD_TO_CART_POPUP`, `REGISTRATION_POST_PURCHASE`). May be prefixed with the control that triggered it, separated by `#`, for example `ATC_BUTTON#PRODUCT_PAGE`; the server splits the prefix into `eventSource`. Sales analytics counts product-page funnel events by `ps = PRODUCT_PAGE`.
</ParamField>
<ParamField body="pf" type="string">
  Platform: `SHOPIFY`, `BIGCOMMERCE`, `WOOCOMMERCE`, or `CUSTOM`.
</ParamField>
<ParamField body="ct" type="string">
  Store country code, for example `US` or `CA`.
</ParamField>
<ParamField body="pr" type="string">
  Province/state the quote was priced for, when applicable.
</ParamField>
<ParamField body="sqid" type="string">
  SureBright quote id the event relates to.
</ParamField>
<ParamField body="sqiid" type="string">
  SureBright quote item id (the specific plan).
</ParamField>
<ParamField body="cid" type="string">
  Platform cart id / token, when known.
</ParamField>
<ParamField body="scaid" type="string">
  SureBright cart analytics id, when the SDK has stamped the cart with one. Omit if you do not have it.
</ParamField>
<ParamField body="tid" type="string">
  Theme id.
</ParamField>
<ParamField body="stid" type="string">
  Session treatment id, only when the store runs a SureBright experiment.
</ParamField>
<ParamField body="em" type="string">
  Error message, for `SB_ERROR` events.
</ParamField>
<ParamField body="ec" type="string">
  Error code, for `SB_ERROR` events.
</ParamField>
<ParamField body="pd" type="object">
  Product and plan details for the event. An empty string for any value is stored as `null` (that is how "no plan" is expressed).
  <Expandable title="pd fields">
    <ParamField body="p_pid" type="string">Product id.</ParamField>
    <ParamField body="p_vid" type="string">Variant id.</ParamField>
    <ParamField body="p_pp" type="string">Product price.</ParamField>
    <ParamField body="p_pq" type="number">Product quantity.</ParamField>
    <ParamField body="p_plpid" type="string">Protection (policy) product id. Sales analytics treats an add-to-cart with `p_plpid` empty/null as "added without protection".</ParamField>
    <ParamField body="p_plvid" type="string">Protection product variant id.</ParamField>
    <ParamField body="p_plq" type="number">Protection quantity.</ParamField>
    <ParamField body="p_plp" type="string">Plan price.</ParamField>
    <ParamField body="p_pt" type="string">Plan tenure, e.g. `2Y`; `0Y` when no plan.</ParamField>
    <ParamField body="p_ds" type="string">Default-selected plan tenure shown in the offer, e.g. `2Y`.</ParamField>
    <ParamField body="p_rs" type="string">Ribbon-highlighted plan tenure shown in the offer.</ParamField>
    <ParamField body="p_pvid" type="string">Price version id, for versioned pricing.</ParamField>
    <ParamField body="p_dc" type="string">Display currency.</ParamField>
    <ParamField body="p_scid" type="string">Shopify category id.</ParamField>
    <ParamField body="p_sbcid" type="string">SureBright category id.</ParamField>
    <ParamField body="isqa" type="boolean">Whether quotes were available for the product.</ParamField>
  </Expandable>
</ParamField>

The server adds `eventId` (if you did not send one), `receivedAt`, and a parsed `userAgent` from the request header.

<Note>
Events containing a `wt` (webhook topic) field are treated as webhook events, not shopper events, and are discarded. Do not use that key.
</Note>

## Event types

These are the `et` values the storefront SDK emits. Use the same names so your traffic lands in the same reports.

| `et` | When |
| --- | --- |
| `SB_FETCHED_POLICY` | Quotes were fetched for a product the shopper is viewing. Sales analytics counts this as a product view with an offer. |
| `SB_VIEWED_POLICY` | The offer became visible, or a plan popup opened (with `ps` set to the popup name). |
| `SB_VIEWED_POLICY_IMPRESSION` | A widget surface was rendered and seen. |
| `SB_VIEWED_CART` | The cart page or cart drawer was viewed. |
| `SB_CLICKED_POLICY` | The shopper selected a plan. |
| `SB_UNCLICKED_POLICY` | The shopper deselected a plan. |
| `SB_CLICKED_LEARN_MORE` | The shopper opened "what's covered". |
| `SB_CLICKED_PROTECT_MY_PURCHASE` | The shopper confirmed protection in a popup. |
| `SB_CLICKED_NO_THANKS` | The shopper declined protection in a popup. |
| `SB_CLICKED_CLOSE_POPUP_ICON` | The shopper closed a popup without choosing. |
| `SB_CLICKED_ADD_WARRANTY_BUTTON` | The shopper used an "add protection" call-to-action (cart). |
| `ADD_TO_CART` | The shopper added a product to the cart, with or without a plan. `ps` carries the triggering control (e.g. `ATC_BUTTON#PRODUCT_PAGE`) and `pd.p_plpid` says whether protection went with it. Sent immediately, not batched. |
| `SB_CLICKED_ADD_TO_CART` | Protection was added from the product-registration flow. Older SDK builds also sent it for product-page adds, and the legacy product-page funnel chart still counts it. |
| `SB_CONFIRMED_ADD_TO_CART` | The cart confirmed the add (quantities verified after the write). |
| `SB_VIEWED_EXPERIMENT` | The shopper was exposed to an experiment treatment (`stid`). |
| `SB_ERROR` | The SDK hit an error (`em`, `ec`). |

Which events the merchant portal reads: the design/experiment analytics count `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY_IMPRESSION`, `SB_CLICKED_POLICY`, `ADD_TO_CART` and `SB_VIEWED_CART` per visit; the legacy product-page funnel chart counts `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY` and `SB_CLICKED_ADD_TO_CART` with `ps` = `PRODUCT_PAGE`. The minimum set that makes a custom storefront visible is `SB_FETCHED_POLICY`, `SB_VIEWED_POLICY_IMPRESSION`, `SB_CLICKED_POLICY` and `ADD_TO_CART`, each with a shared `vi`.

## Example

A shopper on a product page adds a product together with a 2-year plan:

<CodeGroup>

```javascript fetch
const visitId = sessionStorage.getItem("sb_visit") ?? crypto.randomUUID();
sessionStorage.setItem("sb_visit", visitId);

await fetch("https://api-external.surebright.com/events/api/event", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/json" },
  keepalive: true,
  body: JSON.stringify({
    eventList: [
      {
        et: "ADD_TO_CART",
        sid: "your-store.myshopify.com",
        vi: visitId,
        pf: "SHOPIFY",
        ct: "US",
        ps: "ATC_BUTTON#PRODUCT_PAGE",
        etime: new Date().toISOString(),
        sqid: "7b9a6c31-f6c5-4110-a1f4-c69dca10ab06",
        sqiid: "047cd751-8737-45cd-b113-227312a88d51",
        pd: {
          p_pid: "6673746231399",
          p_vid: "39876543210987",
          p_pp: "649.99",
          p_pq: 1,
          p_plpid: "7080029454439",
          p_plvid: "40937702359143",
          p_plq: 1,
          p_plp: "69.00",
          p_pt: "2Y",
          p_dc: "USD",
          isqa: true
        }
      }
    ]
  })
});
```

```bash curl
curl -X POST https://api-external.surebright.com/events/api/event \
  -H "Content-Type: application/json" \
  -d '{
    "eventList": [{
      "et": "ADD_TO_CART",
      "sid": "your-store.myshopify.com",
      "vi": "3f1c9e0a-2d5b-4c7e-9a1f-0b6d8e4c2a71",
      "pf": "SHOPIFY",
      "ct": "US",
      "ps": "ATC_BUTTON#PRODUCT_PAGE",
      "etime": "2026-11-09T14:03:21.512Z",
      "sqid": "7b9a6c31-f6c5-4110-a1f4-c69dca10ab06",
      "sqiid": "047cd751-8737-45cd-b113-227312a88d51",
      "pd": {
        "p_pid": "6673746231399",
        "p_vid": "39876543210987",
        "p_pp": "649.99",
        "p_pq": 1,
        "p_plpid": "7080029454439",
        "p_plvid": "40937702359143",
        "p_plq": 1,
        "p_plp": "69.00",
        "p_pt": "2Y",
        "p_dc": "USD",
        "isqa": true
      }
    }]
  }'
```

</CodeGroup>

For an add-to-cart **without** protection, send the same `ADD_TO_CART` event with `p_plpid`, `p_plvid`, `p_plp`, `sqid` and `sqiid` as empty strings, `p_plq: 0` and `p_pt: "0Y"`. That is exactly what the SDK sends, and the empty `p_plpid` is what analytics uses to tell the two apart.

## Behaviour to copy from the SDK

- Batch up to 10 events per request; send immediately on add-to-cart, otherwise when the batch fills or the page unloads (`keepalive: true`).
- Keep events you could not send and retry them on the next page load.
- On Shopify, send nothing until the shopper's analytics consent allows it (see [Consent gating](/frontend-widget-integration/frontend-widget-kit/placements#analytics-events-and-consent)).
- Do not send events from crawlers or your own test tooling; they count as shoppers.
