# Connecting PostHog

> How to connect PostHog so the custom events you've defined there surface inside Ordinary alongside commerce data.

Source: https://help.tryordinary.com/integrations/posthog

---

> PostHog integration requires **Starter or higher**.

Connecting PostHog surfaces the **custom events and cohorts you've
defined in PostHog** inside Ordinary — the product-usage and
behavioural signals you've invested in capturing there sit
alongside Ordinary's commerce data.

**What the PostHog integration does NOT do**: it does not replace
or supplement Ordinary's session and traffic numbers. Our
first-party pixel is the single source of truth for sessions,
devices, funnel steps, and attribution. PostHog sessions will
usually differ from Ordinary (different session definitions, bot
filtering, SDK capture rules) and that's expected — we never
composite the two.


## Before you start

- You're on Starter or higher.
- You already have PostHog installed on your Shopify storefront (or
  your post-purchase flow).
- You have a **PostHog personal API key** with `project:read` scope.

## Why connect PostHog

Ordinary's first-party pixel covers Shopify storefront events well.
PostHog typically covers:

- Pre-checkout product usage (content interactions, video plays).
- Post-purchase app/account activity, if you have a customer account.
- Cross-device identity via their identify() graph.

Merging them gives you a longer session trail for attribution and
better funnel fidelity.

## Step 1 — get a PostHog personal API key

1. In PostHog, click your avatar → **Settings → Personal API keys**.
2. Click **Create personal API key**.
3. Label it "Ordinary integration".
4. Scope: **Read** on `project` is sufficient.
5. Copy the key (starts with `phx_`).

## Step 2 — paste into Ordinary

1. Settings → Integrations → **PostHog** → **Connect**.
2. Paste the API key.
3. Paste your **PostHog project ID** (find it in PostHog → Settings →
   Project → Project ID).
4. Paste your **PostHog host URL** (usually `https://us.i.posthog.com`
   or `https://eu.i.posthog.com`; self-hosted uses your own domain).
5. Click **Save and test**.

Ordinary verifies the key by pulling a single recent event. If it
fails, you'll see an error — typically wrong project ID or
insufficient scope.

## Step 3 — map events

Once connected, you'll see an event mapping screen. Decide which
PostHog events map to Ordinary's funnel stages:

- **Product viewed** ← PostHog `$pageview` where URL matches `/products/*`.
- **Added to cart** ← PostHog `product added to cart`.
- **Checkout started** ← PostHog `checkout started` (or auto-detected
  from Shopify's own events).
- **Order completed** ← always Shopify's `orders/create` webhook, not
  PostHog.

Defaults are auto-populated from common naming conventions. Override
per-event as needed.

## What flows in

- Event counts by day, broken out by event type.
- Identified-user linking — PostHog identify() events help us connect
  an anonymous Shopify session to the known customer after login.
- Autocapture events (if enabled) for clickmaps and session-level
  context.

## Refresh cadence

- Hourly pull of the last 6 hours of events, deduplicated against
  what we've already ingested.
- Full 30-day backfill on initial connection.

## Disconnecting

Settings → Integrations → PostHog → **Disconnect**. Revokes the API
key from Ordinary's side (you can also rotate it in PostHog itself
for extra hygiene).

## Troubleshooting

- **"Invalid API key"** — key may have expired or been revoked. Create
  a new one in PostHog and paste it.
- **"Project not found"** — your project ID is wrong. Copy it exactly
  from PostHog's Settings page (it's a numeric value).
- **No events showing up** — make sure the PostHog project is actively
  receiving events. Check PostHog's Live Events view first.

## Related articles

- [What is a first-party pixel?](https://help.tryordinary.com/concepts/first-party-pixel)
- [Funnel — sessions → ATC → checkout → orders](https://help.tryordinary.com/features/funnel)