API reference

Revenue requestCopy Anchor Link

POST /api/ingest HTTP/1.1
Host: supapulse.app
Content-Type: application/json
X-API-Token: sec_your_secret_token

{
  "type": "revenue",
  "data": {
    "customer_id": "user_123",
    "amount": 49.90,
    "currency": "USD",
    "transaction_id": "in_1Q8xYz",
    "event_type": "renewal",
    "payment_processor": "stripe"
  }
}

Revenue needs the secret token. A public token gets 422, because revenue isn't an allowed type for it.

FieldsCopy Anchor Link

Fields not listed are ignored.

Event typesCopy Anchor Link

Send amount as a positive number. For refund, Supapulse stores it as negative so revenue is net of refunds. mrr_impact signs are fixed for you: send the size of the change.

IdempotencyCopy Anchor Link

A revenue event is identified by the site, transaction_id and event_type. Sending the same combination again returns 202 and stores nothing, so retries are safe. The same transaction_id with a different event_type is a different event.

AttributionCopy Anchor Link

Supapulse resolves the visit in this order: visitor_fingerprint, session_id, then the touch stored for the customer_id. See Attribution.

Responses from /api/ingestCopy Anchor Link

Identify requestCopy Anchor Link

POST /api/ingest HTTP/1.1
Host: supapulse.app
Content-Type: text/plain;charset=UTF-8

{
  "type": "identify",
  "token": "pub_your_public_token",
  "data": { "customer_id": "user_123", "session_id": "6f1c2e9a-…" }
}

Identify works with the public or the secret token. With a public token, visitor_fingerprint and source_customer_id are discarded and the fingerprint is built from the request's IP address and user agent. Identify events never count toward usage.

Fingerprint requestCopy Anchor Link

POST /api/fingerprint HTTP/1.1
Host: supapulse.app
Content-Type: text/plain;charset=UTF-8

{ "token": "pub_your_public_token" }

{ "visitor_fingerprint": "9b74c9897bac770ffc029102a200c5de…" }

The value is the same hash Supapulse stores on the visitor's pageviews. Call it from the browser: it's built from the caller's IP address and user agent. It returns 401, 403 and 402 like /api/ingest, but is never limited by the monthly event quota.

Stripe webhookCopy Anchor Link

POST https://supapulse.app/api/webhooks/stripe/{publicToken}

Stripe calls this endpoint. It needs a signing secret saved in the site's settings.

See the Stripe guide for what each event becomes.

The @supapulse/revenue SDKCopy Anchor Link

import { Revenue, type RevenueConfig, type RevenueData } from '@supapulse/revenue';

const revenue = new Revenue(config: RevenueConfig);
await revenue.track(data: RevenueData);

track() validates its input, then posts the same request as above with the token in both the X-API-Token header and the body. It retries network errors, 5xx and 429 responses up to maxRetries times, then throws. Other 4xx responses, including 402 and 422, throw immediately with the status and body.

What track() validatesCopy Anchor Link

visitor_fingerprint and session_id are optional.

TypesCopy Anchor Link

interface RevenueConfig {
  apiToken: string;
  endpoint?: string;
  debug?: boolean;
  maxRetries?: number;
  retryBackoff?: number;
}

interface RevenueData {
  visitor_fingerprint?: string;
  session_id?: string;
  customer_id: string;
  amount: number;
  currency?: string;
  transaction_id: string;
  payment_processor?: string;
  event_type?: 'purchase' | 'subscription' | 'renewal' | 'upgrade' | 'downgrade' | 'churn' | 'refund';
  occurred_at?: Date | string;
  subscription_id?: string;
  /** @deprecated Use `subscription_id`. */
  customer_subscription_id?: string;
  mrr_impact?: number;
  is_recurring?: boolean;
  metadata?: Record<string, any>;
}