Tracking events

FounderPass surfaces analytics, most-viewed deals, claim conversion, partner-level metrics, from the events your end-user surface emits. If your community uses the FounderPass hosted app, those events are already fired for you and you instrument nothing. You only send events yourself when you build your own end-user surface against the API. There are two ways to send them:

Client-side: POST /events/track, called from the end-user surface (the hosted app, or your own browser client). No Bearer token; attribution comes from a Firebase token if present, otherwise a session_id.
Server-side: POST /v1/events/track, called from your backend with your Partner JWT. Attributes the event to one of your users without Firebase, resolving them by user_id, email, or external_user_id. See Server-side attribution below.

Client-side tracking

The FounderPass hosted app already fires these events across the user journey, so if your community lives there you can skip this section. Follow it only when you build your own end-user surface against the API: hook a single POST /events/track call into the key moments of the journey, listing impressions, detail views, instructions views, promo-code copies, and redemptions.

Sending an event

curl -X POST https://<your-slug>.perks.founderpass.com/events/track \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "deal_detail_viewed",
    "deal_id": "018e4b2a-0000-7def-abcd-000000000010",
    "session_id": "sess_abc123",
    "source": "hosted",
    "metadata": { "referrer": "homepage" }
  }'

Success returns 200 { "status": "tracked" }.

Field	Type	Required	Notes
`event_type`	enum	Yes	See list below
`session_id`	string	Yes	A stable per-session ID you generate client-side
`source`	enum	Yes	`hosted` or `iframe`. `api` is reserved for the server-side endpoint and is rejected here with `400`.
`deal_id`	uuid	No	Required for deal-scoped events
`user_id`	uuid	No	Ignored: server attributes from the Firebase token if present, never from the body
`metadata`	object	No	Free-form JSON for your own attribution

Event types

Value	When to fire
`deal_list_viewed`	A deal listing page rendered for the user
`deal_detail_viewed`	User opened the deal detail page
`instructions_viewed`	User opened the redemption instructions
`redeem_url_clicked`	User clicked the redeem CTA
`promo_code_copied`	User copied the promo code
`unique_code_claimed`	User claimed a one-time code
`deal_redeemed`	User completed redemption
`upgrade_cta_clicked`	User clicked a tier-upgrade CTA
`deal_inquiry_submitted`	User filled the “request access” form

Server-side attribution

POST /v1/events/track records an event from your backend and attributes it to one of your users, no Firebase token required. Authenticate with your Partner JWT (Bearer token), and identify the user with exactly one of user_id, email, or external_user_id (tried in that order; the first present wins). The resolved user must belong to your partner.

curl -X POST https://perks.founderpass.com/v1/events/track \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "deal_detail_viewed",
    "external_user_id": "cust_abc123",
    "deal_id": "018e4b2a-0000-7def-abcd-000000000010",
    "metadata": { "surface": "members-dashboard" }
  }'

Success returns 200 { "status": "tracked", "user_id": "…" }.

Field	Type	Required	Notes
`event_type`	enum	Yes	Same event types as the public endpoint
`user_id`	uuid	One of these three	A FounderPass user ID
`email`	string	One of these three	The user’s email, scoped to your partner
`external_user_id`	string	One of these three	The ID you set on the user via Syncing users
`deal_id`	uuid	For `deal_redeemed`, yes	Validated against your visible catalogue; required for `deal_redeemed`
`session_id`, `metadata`	string / object	No	Carried through onto the recorded event

The event is always recorded with source = "api". Resolution rules:

If none of user_id / email / external_user_id is supplied → 400.
If the identifier resolves to no user in your partner → 404.
A deal_id outside your visible catalogue (hidden, api_excluded, wrong tenant) → 404.
A deal_redeemed is deduplicated to one row per (partner, user, deal), so retries are safe.

Reading analytics back

You do not need to write any code to see your analytics: the partner portal ships a built-in analytics dashboard (totals, top deals, per-deal time series, and CSV export) that reads these same events. Use the API below when you want the raw numbers in your own systems.

This endpoint requires a Partner JWT, call it from your backend, not from the browser.

curl "https://perks.founderpass.com/v1/analytics?days=30" \
  -H "Authorization: Bearer $TOKEN"

days is a lookback window (1–365, default 30).

Response

{
  "total_users": 1240,
  "active_users": 312,
  "total_deal_views": 5821,
  "total_redemptions": 184,
  "upgrade_cta_clicks": 27,
  "top_deals": [
    { "deal_id": "...", "product_name": "Notion", "view_count": 312, "click_count": 96, "redemption_count": 41 }
  ],
  "event_counts": {
    "deal_list_viewed": 9201,
    "deal_detail_viewed": 5821,
    "deal_redeemed": 184
  }
}

For per-deal time series or CSV export, use the corresponding admin/portal endpoints in the API Reference.