Tracking & events

The ingestion endpoints receive hits from the tracker (or any server-to-server sender). They do not use OAuth — they are authenticated by the site’s tracking key (tracking_key, a UUID) sent in the key body field. A hit is validated, then queued for processing, so a successful call returns 202 Accepted with an empty body. An unknown key returns 404 Not Found. All ingestion endpoints accept a text/plain body (for navigator.sendBeacon) as well as JSON. Base URL: https://clickbase.so/api.

Collect a pageview

POST /api/collect

Record a pageview. Rate limit: 600/min per IP.

Parameter	Type	Required	Description
`key`	string (uuid)	Yes	The site’s tracking key.
`hostname`	string	Yes	Max 255 chars.
`url.path`	string	Yes	Max 2048 chars.
`url.title`	string	No	Max 512 chars.
`properties`	object	No	Custom property map. Max 50 keys (key ≤ 64 chars, scalar values ≤ 500 chars).
`referrer`	string	No	Max 2048 chars.
`screen.width`	int	No	0–65535.
`screen.height`	int	No	0–65535.
`language`	string	No	Max 35 chars.
`os`	string	No	Max 50 chars.
`os_version`	string	No	Max 50 chars.
`browser.name`	string	No	Max 50 chars.
`browser.version`	string	No	Max 50 chars.
`device`	string	No	One of `desktop`, `mobile`, `tablet`.
`visitor_id`	string (uuid)	No	Client-supplied visitor id (cookieless mode).

Status: 202 Accepted (404 on unknown key).

curl -X POST https://clickbase.so/api/collect \
  -H "Content-Type: application/json" \
  -d '{
    "key": "{tracking_key}",
    "hostname": "example.com",
    "url": { "path": "/pricing", "title": "Pricing" },
    "referrer": "https://google.com"
  }'

Record a custom event

POST /api/event

Record a named custom event, optionally carrying revenue. Rate limit: 600/min per IP. Revenue sent here is reported, not verified: it counts against a matching revenue goal for attribution, but it never reaches MRR or the Revenue page. It can never attribute under the reserved names (payment, the subscription_* names) that only Clickbase writes, since no goal may claim those names. See Track revenue for the difference and for sending verified revenue via the Payments API below.

Parameter	Type	Required	Description
`key`	string (uuid)	Yes	The site’s tracking key.
`hostname`	string	Yes	Max 255 chars.
`name`	string	Yes	Event name. Max 255 chars.
`properties`	object	No	Custom property map (same limits as `/collect`).
`url.path`	string	No	Max 2048 chars.
`url.title`	string	No	Max 512 chars.
`referrer`	string	No	Max 2048 chars.
`screen.width` / `screen.height`	int	No	0–65535.
`language` / `os` / `os_version`	string	No	Device context (same limits as `/collect`).
`browser.name` / `browser.version`	string	No	Max 50 chars.
`device`	string	No	`desktop`, `mobile`, or `tablet`.
`visitor_id`	string (uuid)	No	Client-supplied visitor id.
`revenue.amount`	number	No	`> 0`. The tracker sends this under the wire field `$`; direct callers may send `revenue`. A malformed revenue shape is silently dropped, never a `422`.
`revenue.currency`	string	No	3-letter ISO 4217 code. Required with `revenue`.

Status: 202 Accepted (404 on unknown key).

Send an engagement ping

POST /api/engage

Record a scroll-depth / engaged-time delta for an existing pageview. Rate limit: 600/min per IP (its own bucket).

Parameter	Type	Required	Description
`key`	string (uuid)	Yes	The site’s tracking key.
`hostname`	string	Yes	Max 255 chars.
`url.path`	string	Yes	Max 2048 chars.
`url.title`	string	No	Max 512 chars.
`sd`	int	Yes	Scroll depth 0–100. A value above 100 is clamped to 100.
`time`	int	Yes	Engaged time (ms), 0 up to 4294967295.
`visitor_id`	string (uuid)	No	Client-supplied visitor id.

Status: 202 Accepted (404 on unknown key).

Identify a visitor

POST /api/identify

Attach a user identity to the visitor’s active session. Rate limit: 120/min, keyed by tracking key + IP (this endpoint can grow the site_users table, so it has a tighter bucket).

Parameter	Type	Required	Description
`key`	string (uuid)	Yes	The site’s tracking key.
`hostname`	string	Yes	Max 255 chars.
`identifier`	string	Yes	Your stable user identifier. Max 255 chars.
`name`	string	No	Display name. Max 255 chars.
`avatar`	string (url)	No	Max 255 chars.
`custom`	object	No	Custom trait map. Max 50 keys (key ≤ 64 chars, scalar values ≤ 500 chars).
`visitor_id`	string (uuid)	No	Client-supplied visitor id.

Status: 202 Accepted (404 on unknown key).

Payments API

The Payments API records and deletes verified revenue server-to-server. It uses the same Passport personal access token as the rest of the authenticated API — not the tracking key. Create a token on the Developers settings page or via POST /api/tokens; optionally limit it to specific sites with site_ids. See Authentication.

Authorization: Bearer {token}

Requires a workspace Admin or Owner (SitePolicy::manage) and an active subscription on the token’s workspace. A missing/invalid token returns 401; a member without manage access returns 403; a lapsed subscription returns 402. Rate limit: 60/min (same bucket as the authenticated API group). {siteKey} is the site’s UUID or domain (a domain segment may contain dots).

Record a payment

POST /api/sites/{siteKey}/payments

Idempotent on transaction_id: a replay returns the existing record with 200 instead of creating a duplicate.

Parameter	Type	Required	Description
`amount`	int	Yes	Integer minor units (cents). `> 0`. `$49.90` → `4990`.
`currency`	string	Yes	3-letter code. Must match the site’s reporting currency (enforced by `RecordPayment`).
`transaction_id`	string	Yes	Idempotency key. Max 255 chars.
`visitor_id`	string (uuid)	No	Visitor the payment is attributed to.
`session_id`	string (uuid)	No	Optional Clickbase session id (`clickbase_session_id` metadata). Visitor remains primary.
`email`	string	No	Max 255 chars.
`name`	string	No	Max 255 chars.
`customer_id`	string	No	Max 255 chars.
`renewal`	bool	No	Whether this is a renewal.
`refunded`	bool	No	Whether the payment was refunded.
`is_free_trial`	bool	No	Whether this is a free-trial conversion.
`recurring`	bool	No	Whether this payment is recurring.
`timestamp`	string (date)	No	Payment time; defaults to now.

Response: { "message": ..., "transaction_id": ... }. Status: 201 Created on a new record, 200 OK on a replay.

curl -X POST https://clickbase.so/api/sites/example.com/payments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4990, "currency": "USD", "transaction_id": "ch_123"}'

Delete a payment

DELETE /api/sites/{siteKey}/payments

Delete an API-recorded payment and its revenue row by transaction_id. Only deletes payments created through this API — never Stripe-ingested rows.

Parameter	Type	Required	Description
`transaction_id`	string	Yes	The transaction id to delete.

Response: 200 OK ({ "message": "Payment deleted." }), or 404 Not Found when no matching payment exists.

curl -X DELETE https://clickbase.so/api/sites/example.com/payments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "ch_123"}'

Stripe webhook

POST /api/stripe/webhook/{siteId}

Per-site Stripe webhook receiver. {siteId} must be a site UUID. The request is authenticated by verifying the Stripe-Signature header against the site’s configured webhook secret — a missing integration/secret returns 404, a bad signature returns 400. On success it dispatches to HandleStripeWebhook and returns 200 OK. Rate limit: 600/min. This endpoint is configured in the site’s Stripe integration, not called by hand.

Overview

Sites & tracking

Analytics

Goals & funnels

Revenue

Session replay

Collect a pageview

Record a custom event

Send an engagement ping

Identify a visitor

Payments API

Record a payment

Delete a payment

Stripe webhook

​Collect a pageview

​Record a custom event

​Send an engagement ping

​Identify a visitor

​Payments API

​Record a payment

​Delete a payment

​Stripe webhook

Collect a pageview

Record a custom event

Send an engagement ping

Identify a visitor

Payments API

Record a payment

Delete a payment

Stripe webhook