---
title: "Billing Funnel Event"
method: POST
path: "/api/billing/funnel-event"
tags: ["billing", "team"]
---

# Billing Funnel Event

`POST /api/billing/funnel-event`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/billing/funnel-event`
- Auth: none declared

Record a frontend-originated conversion-funnel event (#418).

Body: {"event": str, "details": {...}}. `event` MUST be one of the four
FE-emitted CONVERSION_FUNNEL_EVENTS; anything else is 400. Anonymous
callers are allowed (paywall_impression happens pre-auth). Returns 204.

## Request body

- FunnelEventRequest: Request body for `POST /api/billing/funnel-event` (issue #418). The frontend-originated conversion-funnel sink. tier-gate.ts gates `/api/*` client-side (UX-only — no 402 reaches the backend), so paywall encounters that are client-gated never hit the server-side emit at routes/api_errors.py. This route is the missing frontend -> backend path for the four FE-only funnel events. Sent via navigator.sendBeacon as a JSON Blob. `event` is allowlisted at the route to exactly the four FE-emitted members of CONVERSION_FUNNEL_EVENTS (paywall_impression, paywall_clicked_upgrade, quota_warning_shown, cancel_reason) so an arbitrary client string can never pollute the funnel stream — that allowlist is the security-relevant bit, not this schema (which stays permissive on `details` shape by design, since each event carries a different small payload: {tier, route} / {tier} / {pct} / {reason}).
  - `event` string, required: Funnel event name; rejected with 400 unless it is one of the four FE-emitted CONVERSION_FUNNEL_EVENTS.
  - `details` object, nullable: Small event-specific payload (e.g. {tier, route}, {pct}, {reason}). Optional.

## Response `204`

Successful Response

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)