Customer organizations

Customer organizations are the B2B tenants you serve – the companies that use your product. In SaaS Tracker they are identified consistently across:

events via customer_org_id
customer organization imports via external_org_id
subscription / revenue imports via external_org_id

This page explains how these pieces fit together.

Event-side identifier: customer_org_id

Every event sent to the Ingest API must include customer_org_id:

this is your identifier for the customer organization in your own systems
it is stored on each event and used to build organization-level metrics

Example (from the event schema):

{
  "event": "page_view",
  "user_hash": "…",
  "customer_org_id": "org_456",
  "path": "/dashboard"
}

Organizations first appear in analytics when events arrive with a given customer_org_id. They show up in Analytics → Organizations and receive health scores if your plan includes them.

Imported organizations: external_org_id

For revenue analytics and more reliable naming, you can import a master list of customer organizations.

In the Customer organizations CSV, the primary key is external_org_id.
This should match the customer_org_id you send in events.
The CSV also includes display_name, which is how the organization appears in the UI.

Example row:

external_org_id,display_name
org-456,Acme Corporation

When an imported organization’s external_org_id matches event customer_org_id:

Revenue and usage line up for the same customer.
The Organizations list shows the display_name instead of a raw ID.

Revenue subscriptions and organizations

Subscriptions are imported via the Revenue subscriptions CSV. Each row links revenue back to the organization using external_org_id:

the same external_org_id as in the organizations import
the same logical ID as customer_org_id in events

Example:

external_org_id,product_code,mrr,currency,start_at
org-456,pro,99.00,EUR,2024-01-15

This allows SaaS Tracker to compute:

MRR per customer organization
Revenue by health (using health scores from event data)
Revenue × Health segments
revenue-aware Signals (e.g. Revenue at risk, Inactive paying)

Imported organizations vs active organizations

There are two useful views of organizations:

Imported organizations – all rows you have imported via the Customer organizations CSV.
Active organizations – organizations that have had recent usage (events with customer_org_id).

Key points:

Imported organizations can exist before any events are received.
Revenue analytics (e.g. Revenue, Revenue × Health) can include imported organizations with subscriptions even if they have not yet generated usage events.
The Organizations list in analytics focuses on organizations with recent activity by default; you can use filters such as “Show all orgs” to also see imported-but-inactive orgs.

Best practices

To keep your data consistent:

Use one canonical ID per organization.
- In events: customer_org_id
- In organization import: external_org_id
- In subscriptions import: external_org_id
Normalize IDs. Use a stable, URL-safe identifier (e.g. acme_corp) rather than display names.
Import organizations before subscriptions. This ensures that subscription imports can resolve each external_org_id to a known customer organization.
Avoid special cases per environment. Prefer a single ID per real-world organization; if you need separate sandboxes, use the environment field in events instead of encoding environment into the org ID.