B2B SaaS Wiring Guide

This guide explains how Apex derives your Activation, Retention, and Revenue dashboards. If you're running a B2B SaaS product with a product-led growth motion, this is your single source of truth for what data powers what.

The Data Model

Apex builds your dashboards from three independent data sources. Each one is optional — the more you connect, the richer the picture.

How the Activation Dashboard Works

The Activation dashboard builds a three-stage funnel:

Sign-ups → Active → Activated

• Sign-ups = contacts created in the selected time window (from their createdAt timestamp)
• Active = contacts who triggered at least one custom tracking event, or who have an activatedAt timestamp
• Activated = contacts whose lifecycle stage is activated, customer, or expanded

What to track for activation

At minimum, track the moment a user does the thing that makes them "real":

• Completed onboarding — track("onboarding_completed")
• Used a core feature — track("report_created"), track("experiment_started")
• Connected a data source — track("integration_connected", { provider: "stripe" })

The more product events you send, the more Apex can distinguish "signed up and left" from "signed up and engaged."

How the Retention Dashboard Works

The Retention dashboard tracks two related but distinct things:

Contact-based retention (lifecycle stages)

• Retention % = contacts who are still in an active lifecycle stage divided by total contacts
• Churn rate = contacts who moved to churned stage divided by total contacts
• Cohort matrix = month-by-month retention rates for each signup cohort

This requires contacts to have lifecycle stage transitions over time. Without lifecycle updates, all contacts appear permanently "active."

Revenue-based retention (Stripe)

• Net Revenue Retention (NRR) = (initial MRR + expansion − contraction − churned revenue) / initial MRR
• Powered entirely by Stripe charge data

Connecting Stripe

Stripe adds revenue data to your dashboards:

Stripe webhook automation

When you configure Stripe webhooks, Apex automatically updates contact lifecycle stages:

• invoice.paid → Contact moves to customer lifecycle stage + conversionValue is accumulated from the invoice amount
• customer.subscription.deleted → Contact moves to churned lifecycle stage

Matching works in two steps: first by externalIds.stripe_customer_id (if the contact was previously matched), then by email fallback. On a successful email match, Apex stores the Stripe customer ID for faster future lookups.

Events are idempotent — replaying the same Stripe webhook won't double-apply lifecycle changes.

Setting up Stripe webhooks

1. Set STRIPE_WEBHOOK_SECRET in your environment variables
2. In the Stripe Dashboard → Webhooks, add an endpoint pointing to https://your-apex-url/api/webhooks/stripe
3. Subscribe to invoice.paid and customer.subscription.deleted events
4. Stripe test mode (sk_test_ keys) works — use it to verify the connection first

Manual lifecycle updates

You can also update lifecycle stages manually via the API if you need more control:

POST /api/contacts/{contactId}/lifecycle
{ "stage": "customer" }

Test mode

Stripe test mode (keys starting with sk_test_) works with Apex. Use it to verify the connection before going live with production data.

The Identity Chain

For Apex to connect the dots between a website visitor, a signed-up user, and a paying customer, it needs identity:

1. Anonymous visitor — The snippet assigns a apex_vid cookie automatically
2. Known user — Call identify(userId, { email }) at signup or login
3. Paying customer — Stripe matches by email to the identified contact

If any link in this chain is missing, you'll see gaps:

Growth Reporting vs. Finance

Apex is a growth reporting tool, not a financial system. Important distinctions:

• Contact-level, not account-level — Apex tracks individual contacts. If your B2B product has team accounts, multiple contacts may belong to one billing customer. Revenue is attributed per-contact, not per-account.
• Approximate revenue — Stripe sync gives you directional revenue data for dashboards and experiment attribution. It is not a replacement for your accounting system.
• NRR is simplified — Apex calculates NRR from charge patterns, not from a full subscription management model. It's accurate enough for growth decisions but not for investor reporting.

Setup Checklist

Use this as a quick reference for wiring a new B2B SaaS project:

1. Install the tracking snippet on your marketing site and app — Snippet installation
2. Add identify() calls at signup and login — Identity docs
3. Track key product events that signal activation — Custom events
4. Connect Stripe for revenue data — Stripe connector
5. Configure Stripe webhooks to automate customer and churned lifecycle transitions — see webhook setup above
6. Update lifecycle stages as users progress (or let webhooks handle it) — Lifecycle concepts
7. Check your dashboards — Activation and Retention should start showing data within minutes

Next Steps

• Activation concepts — How the activation funnel is calculated
• Retention concepts — Cohort analysis and NRR methodology
• Lifecycle stages — The full stage model and how it affects dashboards
• Running experiments — Start testing changes against your activation and retention metrics