mongo-ai/posthog-billing-diagnosis

Billing & account diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search("billing plans pricing {specific symptom}")
2. Run docs-search("support options plan features")
3. If plan-specific: check contents/docs/billing/ in PostHog/posthog.com repo
4. Use the fetched docs as your primary reference

Goal

Determine whether the issue is caused by:

• Feature not available on customer's current plan
• Plan upgrade not fully applied
• Payment method failure or billing cycle issue
• Entitlement mismatch (plan says X but UI shows Y)
• Permissions / role issue within the organization
• Actual billing bug (overcharge, double charge, wrong amount)

Step 1: Classify the billing issue

| Symptom | Likely cause | Handle or escalate? | |---------|-------------|-------------------| | "Can't access [feature]" | Plan doesn't include it, or role restrictions | Handle — check plan tier + feature matrix | | "I upgraded but nothing changed" | Upgrade not propagated, or feature needs config | Handle — verify plan, guide setup | | "Charged wrong amount" | Billing calculation issue | Escalate to billing team | | "Double charged" | Payment processing issue | Escalate to billing team | | "Can't upgrade/downgrade" | UI bug or payment method issue | Handle first, escalate if stuck | | "My trial expired" | Expected behavior or timing question | Handle — explain trial terms | | "Invoice/receipt question" | Administrative | Escalate to billing team |

Step 2: Check plan and org details (if PostHog MCP available)

organization-details-get → plan, billing status, member count
projects-get → project settings, enabled features

If PostHog MCP is not available, ask the customer:

• "What plan are you on? You can check at Settings → Organization → Billing"
• "How many team members are in your organization?"
• "When did you upgrade?"

Step 3: Feature entitlement matrix

Run docs-search("pricing plans feature comparison") to get the current matrix.

Common feature gates by plan (verify against live docs — these change):

| Feature | Free | PAYG | Scale | Enterprise | |---------|------|------|-------|------------| | Group analytics | Limited | Yes | Yes | Yes | | Multivariate experiments | No | Yes | Yes | Yes | | Advanced paths | No | Yes | Yes | Yes | | Correlation analysis | No | Yes | Yes | Yes | | SSO/SAML | No | No | No | Yes | | Priority support | No | No | Yes | Yes | | Custom data retention | No | No | No | Yes |

IMPORTANT: Always verify this against live docs. PostHog changes pricing frequently.

Step 4: Check permissions vs plan

If the customer says "I can't access X" — distinguish between:

• Plan limitation: Feature not included in their tier → suggest upgrade
• Role restriction: Feature exists but their user role can't access it → check org member roles at Settings → Organization → Members
• Configuration: Feature available but not enabled → guide through setup

Step 5: Check for known billing bugs

Search GitHub:

• gh search issues --repo PostHog/posthog "billing {symptom}" --limit 10
• gh search issues --repo PostHog/posthog "plan upgrade {symptom}" --limit 10

Step 6: Escalation decision

Handle in support when:

• Customer is on the wrong plan and needs guidance on what to pick
• Feature exists on their plan but needs to be configured
• Role/permission issue within their org
• Question about how billing works (metered, per-event, etc.)

Escalate to billing team when:

• Incorrect charges or double billing
• Payment method failures that the customer can't resolve
• Plan changes not reflected after 24 hours
• Invoice or receipt requests
• Refund requests
• Enterprise contract or custom pricing questions
• Credits not applied correctly

Billing team escalation: Route to the billing team in Zendesk. PostHog handbook says billing is led by the billing engineering team. Add the billing engineer as a follower on the ticket and leave an internal note with what you've already investigated.

Common resolution patterns

• "Feature X not available" → Check plan tier against feature matrix, guide upgrade if needed
• "Upgraded but can't see feature" → Hard refresh, check project vs org settings, verify the right project is selected
• "Usage spike in bill" → Help them check event volume in PostHog, identify which events are high-volume, suggest event filtering
• "How do I reduce my bill?" → Guide through billing settings, show how to set billing limits, suggest event sampling
• "Free tier limits" → Explain the generous free tier limits, show what counts toward quota

Response tone

Billing conversations require extra care:

• Money is personal — be empathetic even if it's a simple misunderstanding
• Never say "you chose the wrong plan" — say "it looks like feature X requires the Scale plan"
• If there's a genuine billing error, take ownership immediately
• Always link to the pricing page for transparency