Event Collector
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#
POST https://api-external.surebright.com/events/api/event
Content-Type: application/jsonAuthentication: 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#
{ "isError": false, "acceptedCount": 2, "rejectedCount": 0, "webhookEventsPushedCount": 0 }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.
Event type. One of the names under Event types.
Store id, as SureBright knows your store (for Shopify, the *.myshopify.com domain).
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.
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.
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.
Platform: SHOPIFY, BIGCOMMERCE, WOOCOMMERCE, or CUSTOM.
Store country code, for example US or CA.
Province/state the quote was priced for, when applicable.
SureBright quote id the event relates to.
SureBright quote item id (the specific plan).
Platform cart id / token, when known.
SureBright cart analytics id, when the SDK has stamped the cart with one. Omit if you do not have it.
Theme id.
Session treatment id, only when the store runs a SureBright experiment.
Error message, for SB_ERROR events.
Error code, for SB_ERROR events.
Product and plan details for the event. An empty string for any value is stored as null (that is how "no plan" is expressed).
The server adds eventId (if you did not send one), receivedAt, and a parsed userAgent from the request header.
Events containing a wt (webhook topic) field are treated as webhook events, not shopper events, and are discarded. Do not use that key.
Event types#
These are the et values the storefront SDK emits. Use the same names so your traffic lands in the same reports.
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:
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
}
}
]
})
});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).
Do not send events from crawlers or your own test tooling; they count as shoppers.