Moonrat Setup Guide

1. Creating a PostHog Personal API Key

To connect Moonrat with your PostHog account, you'll need to create a Personal API Key with specific permissions.

1.1 Step-by-Step Instructions

1. Navigate to PostHog Settings:
   Go to PostHog API Keys Settings (for US region) or EU region
2. Create New Personal API Key:
   Click "Create personal API key" button
3. Configure Key Name:
   Enter a descriptive name like "Moonrat Stripe Integration"
4. Set Required Scopes:
   Select the following permissions (all are required):

1.2 Required API Key Permissions

1.3 Security & Storage

Your PostHog Personal API Key is:

• Stored securely in Stripe's encrypted secret storage system
• Never logged or cached by Moonrat
• Only used to fetch session recordings and user data from PostHog
• Revocable at any time through your PostHog settings

2. Selecting PostHog Region, Organization & Project

After validating your API key, you'll need to select the correct PostHog region, organization, and project for the integration.

2.1 Choosing the Right Region

PostHog offers two hosting regions:

• US Region: https://us.posthog.com
  Choose this if your PostHog URL starts with "us.posthog.com" or just "posthog.com"
• EU Region: https://eu.posthog.com
  Choose this if your PostHog URL starts with "eu.posthog.com"

2.2 Organization Selection

Organizations in PostHog represent your company or team account. Most users belong to one organization, but some may have access to multiple.

• Select the organization that contains the project with your customer data
• This is typically your company's main PostHog organization
• The organization name will be displayed in your Moonrat configuration

2.3 Project Selection

Projects within PostHog contain your actual analytics data, events, and session recordings.

• Choose the project that tracks your users and customers
• Typically named after your product, website, or main application
• Contains the session recordings you want to view in Stripe
• Must have user properties that can be matched to Stripe customers

3. Understanding Customer Matching Strategies

Customer matching is how Moonrat connects your Stripe customers to PostHog users. This is the most important configuration step as it determines which session recordings you'll see.

3.1 What is Customer Matching?

Customer matching links Stripe payment data with PostHog behavioral data by finding common identifiers between the two systems:

• Stripe side: Customer email addresses and customer IDs
• PostHog side: User properties like email, customer ID, or other identifiers
• Moonrat: Finds PostHog users whose properties match Stripe customer data

3.2 Two Matching Options

Option 1: Stripe Customer ID Matching (Recommended)

Option 2: Email Domain Matching

3.3 PostHog Property Configuration

For matching to work, you need to specify which PostHog user property contains the matching identifier:

For Email Domain Matching:

• Property name: Usually "email" (default)
• Contains: Full email addresses like john@company.com
• Moonrat extracts: The domain part (@company.com) for matching

For Customer ID Matching:

• Property name: Usually "stripeCustomerId" (default)
• Contains: Stripe customer IDs like cus_ABC123
• Must match exactly: The Stripe customer ID in your billing system

3.4 Person Identifier Property

This property is used to display a human-readable identifier for users in the Moonrat interface:

• Default: "email"
• Purpose: Shows recognizable names/emails in session recording lists
• Examples: email, name, username, or any property that helps identify the user

4. User Identification: Customer ID vs Email Domain

Choosing the right identification method is crucial for getting relevant session recordings. Here's how to decide:

4.1 When to Use Stripe Customer ID (Recommended)

Requirements for Customer ID matching:

• Your application must send Stripe customer IDs to PostHog as user properties
• Typically done when a user signs up or makes their first purchase
• Property is usually named "stripeCustomerId" or similar

4.2 When to Use Email Domain Matching

Limitations of email domain matching:

• Less precise: May match unrelated users with same domain
• Generic domains: Doesn't work for gmail.com, yahoo.com, etc. (too broad)
• Privacy considerations: May show personal information from multiple users
• No team control: Can't control which users are included in the match

4.3 Implementation Examples

Customer ID Implementation (Recommended):

// For team member 1
posthog.identify('user_1', {
  email: 'john@company.com',
  stripeCustomerId: 'cus_ABC123', // ← Same customer ID for all team members
  name: 'John Doe'
});

// For team member 2  
posthog.identify('user_2', {
  email: 'sarah@company.com',
  stripeCustomerId: 'cus_ABC123', // ← Same customer ID enables team tracking
  name: 'Sarah Smith'
});

Email Domain Implementation:

// Standard user identification
posthog.identify(user.id, {
  email: 'john@company.com', // ← This enables email domain matching
  name: user.name,
  company: 'Acme Corp'
});

4.4 Troubleshooting Common Issues

5. Getting Help

If you need assistance with your Moonrat setup:

This guide covers the complete Moonrat setup process. For the most up-to-date information, please refer to the in-app onboarding flow when installing Moonrat from the Stripe App Marketplace.