Getting Started

Introduction SDK Quickstart Server-Side Tracking

Tracking Campaigns

Getting Started

Server-side tracking

Track from your backend with flowgrid-sdk/server — a Node/edge-safe client scoped to identity, feature usage, ecommerce & revenue and API / server error tracking. Same wire contract as the browser SDK, so server and browser events resolve to one identity in your dashboard.

Overview

Some of the most valuable events never happen in the browser: the OAuth callback that actually creates the account, the API route a feature runs through, the webhook that fails at 3am. FlowGridServer covers exactly that surface:

Identity — identify users, update traits, alias, reset on logout, and the auth-level events (signup / login / active-user) fired from server auth flows.
Feature usage — feature_usage events from API routes, background jobs and webhooks.
Ecommerce & revenue — purchases, refunds, order lifecycle and subscription MRR events, fired from payment webhooks where the money is actually confirmed.
Errors — server exceptions as error_events with route / method / status context.

Runs anywhere fetch runs

No window, no document, no storage, no Node built-ins — only global fetch. Works in Node ≥ 18, Next.js API routes and middleware, Vercel serverless & edge, Cloudflare Workers, Bun and Deno.

Init — once per process

Initialise in a dedicated lib file and import the instance everywhere server-side.init() is idempotent — calling it twice returns the same instance.

lib/flowgrid.server.ts

import { FlowGridServer } from "flowgrid-sdk/server";

export const fg = FlowGridServer.init({
  webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, // same site id as the browser SDK
  apiKey: process.env.FLOWGRID_API_KEY!,           // PRIVATE key — server env only
  // endpoint:    "https://core.flow-grid.xyz",    // default
  // environment: "production",                    // defaults to NODE_ENV
});

Key hygiene

The server client requires your private API key. Keep it in a server-only env var (no NEXT_PUBLIC_ prefix) — never ship it to the browser.

Identity & auth events

trackAuth() is the one-call path for server auth flows — it identifies the user (writing the identity store, so they appear as a Known visitor), fires the signup/login event, and marks them active for DAU/WAU/MAU:

app/api/auth/callback/route.ts

import { fg } from "@/lib/flowgrid.server";

// In your OAuth callback / session endpoint, once the user is known:
await fg.trackAuth({
  event:  "login",              // or "signup"
  userId: user.id,
  email:  user.email,           // email + name make the identity resolvable
  name:   user.name,
  method: "google",
});

The individual operations are all available too — same semantics as the browser SDK:

identity.ts

await fg.identifyUser(user.id, { email: user.email, plan: "pro" });
await fg.updateTraits(user.id, { plan: "enterprise" });      // after an upgrade
await fg.aliasUser("old_id", user.id);                       // ID migrations
await fg.pingActiveUser(user.id, { email: user.email });     // DAU/WAU/MAU signal
await fg.signup(user.id, "google", "pricing");               // funnel "Signed up" stage
await fg.login(user.id, "google");                           // returning-user signal
await fg.logout(user.id);                                    // reset identity on sign-out

Link the web session

Server events need a visitor_id. When you have the request, pass the visitor's real browser id so the server event links to their web session — visitorIdFromCookies() reads it from the request cookies:

app/api/auth/callback/route.ts

import { cookies } from "next/headers";
import { visitorIdFromCookies } from "flowgrid-sdk/server";
import { fg } from "@/lib/flowgrid.server";

const visitorId = visitorIdFromCookies(await cookies());

await fg.trackAuth(
  { event: "signup", userId: user.id, email: user.email, method: "google" },
  { visitorId }, // ← anonymous browsing session → known user, linked
);

No cookie available?

In jobs and webhooks there's no request cookie. Omit visitorId and the client derives a stable synthetic visitor from the userId (fg_srv_<hash>), so a user's server events always attribute to one visitor. Fully anonymous events share a per-process visitor.

Feature usage

Features that run through an API — exports, imports, integrations, AI actions — are tracked where they actually execute. Events land in the same Feature Usage dashboards as browser events (see the Feature Usage guide).

app/api/export/route.ts

import { fg } from "@/lib/flowgrid.server";

// Direct:
await fg.trackFeature({
  featureId:   "csv_export",
  featureName: "CSV Export",
  userId:      user.id,
  properties:  { rows: 12_000 },
});

// Or bind once and use semantic verbs (server twin of fg.defineFeature):
const csvExport = fg.defineFeature("csv_export", "CSV Export", { category: "reports" });
await csvExport.used({ userId: user.id, rows: 12_000 });
await csvExport.completed({ userId: user.id });
await csvExport.abandoned({ userId: user.id, reason: "timeout" });

Ecommerce & revenue

Browser purchase events are structurally lossy — ad blockers, tabs closed on the checkout redirect, interrupted payments. Your payment webhookis where money is actually confirmed, so it's the authoritative place to record revenue. Server events use the same ecommercecontract as the browser SDK and land in the same revenue & monetization dashboards.

app/api/webhooks/stripe/route.ts

import { fg } from "@/lib/flowgrid.server";

// checkout.session.completed — the purchase, recorded where it's confirmed
await fg.trackPurchase({
  order: {
    orderId: session.id,
    items,                              // CartItem[] — same shape as the browser SDK
    subtotal, discountTotal: 0, shippingTotal: 0, taxTotal,
    total: session.amount_total / 100,
    currency: "USD",
    payment: { method: "credit_card", provider: "stripe" },
  },
  userId: session.client_reference_id,
});

// charge.refunded — keeps net revenue accurate
await fg.trackRefund({
  orderId,
  refundId: refund.id,
  amount: refund.amount / 100,
  currency: "USD",
  reason: "customer_request",
  isFullRefund: true,
  userId,
});

Order lifecycle events from fulfilment systems:

fulfilment.ts

await fg.trackOrderStatus(orderId, "processing", "pending", { userId });
await fg.trackOrderShipped(orderId, { method: "express", cost: 5, trackingNumber });
await fg.trackOrderDelivered(orderId);

Subscription / MRR lifecycle — one method, discriminated on event. These power the MRR and churn dashboards, and billing state lives on your server, so emit them from your billing webhooks:

app/api/webhooks/stripe/route.ts

// customer.subscription.created
await fg.trackSubscription({
  event: "start",           // "change" | "cancel" | "renew" | "trial_converted" | "trial_expired"
  subscriptionId: sub.id,
  userId,
  plan: "professional",
  mrr: { amount: 9900, currency: "USD" }, // smallest currency unit (cents)
  billingCycle: "monthly",
  trialDays: 14,
});

// customer.subscription.deleted
await fg.trackSubscription({
  event: "cancel",
  subscriptionId: sub.id,
  userId,
  reason: sub.cancellation_details?.reason ?? "unknown",
  lostMrr: { amount: 9900, currency: "USD" },
});

Revenue attribution — Stripe & Lemon Squeezy

A payment webhook arrives with no cookies — on its own, FlowGrid can only attach a purchase to a synthetic server visitor. To attribute revenue to the real visitor (their session, landing page, UTM campaign), the visitor and session ids must round-trip through the payment provider: embed them in the checkout's metadata when you create it, read them back in the webhook. Both FlowGrid trackers mirror the ids to cookies (visitor_id / session_id, npm SDK: fg_session_id) precisely so your checkout route can read them.

Leg 1 — embed the ids at checkout creation:

app/api/checkout/route.ts

import { cookies } from "next/headers";
import { checkoutAttributionFromCookies } from "flowgrid-sdk/server";

// Stripe — goes into the checkout session's metadata
const session = await stripe.checkout.sessions.create({
  line_items, mode: "payment", success_url, cancel_url,
  metadata: { ...checkoutAttributionFromCookies(await cookies()) },
  // adds: flowgrid_visitor_id + flowgrid_session_id
});

// Lemon Squeezy — goes into checkoutData.custom
const checkout = await createCheckout(storeId, variantId, {
  checkoutData: {
    custom: { ...checkoutAttributionFromCookies(await cookies()) },
  },
});

Creating the checkout from the browser instead? The browser SDK exposes the same keys: fg.checkoutAttribution() — POST them to your checkout endpoint alongside the price id.

Leg 2 — read them back in the webhook and attach them to the revenue event. attributionFromMetadata() unwraps Stripe objects (.metadata) and Lemon Squeezy payloads (.meta.custom_data) automatically:

app/api/webhooks/stripe/route.ts

import { attributionFromMetadata } from "flowgrid-sdk/server";
import { fg } from "@/lib/flowgrid.server";

// checkout.session.completed
const { visitorId, sessionId } = attributionFromMetadata(event.data.object);

await fg.trackPurchase(
  { order, userId: session.client_reference_id },
  { visitorId, sessionId }, // ← revenue joins the real visitor's journey
);

// Works for subscriptions too:
await fg.trackSubscription(
  { event: "start", subscriptionId, userId, plan, mrr },
  { visitorId, sessionId },
);

What this buys you

With the real visitorId + sessionId on the purchase, revenue ties back to the exact session that produced it — the campaign, referrer and landing page — instead of appearing as unattributed server traffic. You can additionally pass attribution: { source, medium, campaign } to trackPurchase if you store campaign data yourself.

API & server error tracking

Thrown values of any shape become error_events. Pass route / method / statusCode so the dashboard can break failures down per endpoint:

app/api/teams/route.ts

import { fg } from "@/lib/flowgrid.server";

try {
  // …
} catch (err) {
  await fg.trackError(err, {
    route:      "/api/teams/edit/[teamId]",
    method:     "PATCH",
    statusCode: 500,
    userId:     user.id,
  });
  throw err;
}

Or wrap the whole handler — the error is tracked and rethrown unchanged, so your framework's error handling behaves exactly as before:

wrapped.ts

export const PATCH = fg.withErrorTracking(
  async (req: NextRequest) => { /* … */ },
  { route: "/api/teams/edit/[teamId]", method: "PATCH" },
);

// Opt-in process-level capture (Node only) — reports uncaughtException /
// unhandledRejection as fatal, observes only, never swallows:
const detach = fg.captureUncaught();

FlowGrid never reports itself

Internal notes (messages starting with [FlowGrid]) are filtered out before sending, so FlowGrid's own delivery hiccups never pollute your error analytics.

Delivery guarantees

Never throws. Every method resolves { ok, status?, reason? } — a tracking failure can never break your API route.
Retries. Network failures and 5xx responses retry with jittered exponential backoff (2 retries, 10s timeout by default — tunable in init).
Server context. Every event is stamped with _server: true, the runtime, and _environment (from NODE_ENV), so you can segment server vs. browser traffic.
Fire-and-forget friendly. Don't want to await? void fg.trackFeature(…) is safe — failures are debug-noted, never raised.

PreviousSDK Quickstart Next Feature Usage

On this page

Overview
Init
Identity & auth events
Link the web session
Feature usage
Ecommerce & revenue
Revenue attribution
Error tracking
Delivery guarantees
Consent & compliance

Getting Started

Tracking Campaigns

Features

Installation Guides

Custom Integrations

Server-side tracking

Overview

Init — once per process

Identity & auth events

Link the web session

Feature usage

Ecommerce & revenue

Revenue attribution — Stripe & Lemon Squeezy

API & server error tracking

Delivery guarantees

Consent & compliance