PostHog

In the Analytics section within Integrations, you can connect your PostHog account to Superwall.

Required fields

Fill out the following fields and click the Enable PostHog button at the bottom right to save your changes:

• Region: Data residency region for your PostHog instance (US or EU).
• API Key: Your PostHog project API key (starts with phc_). Found in PostHog under Project Settings.
• Sales Reporting: Which revenue value to report. Choose between Revenue (gross) or Proceeds (after store taxes and fees).

Features

• Automatic Event Mapping: Converts Superwall events to PostHog events with the sw_ prefix
• Minor-Unit Revenue Tracking: Converts amounts to cents (minor units) for PostHog revenue analytics
• User Profile Enrichment: Sets user properties for store, environment, and bundle ID
• Multi-Region Support: Works with US and EU data residency
• Sandbox Isolation: Separate tracking for production and sandbox events
• Custom Event Names: Override default event names with your own mappings
• Zero-Decimal Currency Handling: Correctly handles currencies like JPY and KRW that do not use minor units

Configuration

Required settings

Optional settings

Example configuration

{
  "integration_id": "posthog",
  "region": "US",
  "api_key": "phc_your_production_api_key_here",
  "sandbox_api_key": "phc_your_sandbox_api_key_here",
  "sales_reporting": "Revenue",
  "anonymous_user_behavior": "send"
}

Event Mapping

Superwall events are transformed into PostHog events with the sw_ prefix. You can optionally override any event name with a custom mapping in your configuration.

Trial events

Intro offer events

Subscription events

Other events

Event Properties

Every PostHog event includes all fields from the Superwall webhook data object as top-level event properties.

Core properties

• distinct_id: User identifier (uses originalAppUserId or falls back to originalTransactionId)
• timestamp: Event timestamp in ISO format

User properties ($set)

The following user properties are set on each event:

• store: The store the transaction originated from (APP_STORE, PLAY_STORE, STRIPE)
• environment: Production or sandbox
• bundle_id: The app bundle identifier

Webhook data properties

All fields from the webhook are included as event properties:

• id, name, cancelReason, exchangeRate
• isSmallBusiness, periodType, countryCode
• price, proceeds, priceInPurchasedCurrency
• taxPercentage, commissionPercentage, takehomePercentage
• offerCode, isFamilyShare, expirationAt
• transactionId, originalTransactionId, originalAppUserId
• store, purchasedAt, currencyCode, productId
• environment, isTrialConversion, newProductId
• bundleId, ts

Payload format

Events are sent to PostHog using the Batch API:

{
  "api_key": "phc_your_api_key",
  "batch": [
    {
      "event": "sw_subscription_start",
      "properties": {
        "distinct_id": "user_123",
        "$set": {
          "store": "APP_STORE",
          "environment": "production",
          "bundle_id": "com.example.app"
        },
        "revenue": 999,
        "currency": "USD",
        "product": "Premium Monthly",
        "product_id": "com.example.premium",
        "subscription_id": "1000000123456789"
      },
      "timestamp": "2025-01-15T12:00:00.000Z"
    }
  ]
}

Revenue Tracking

PostHog requires revenue amounts in minor units (cents). The integration automatically handles this conversion.

Minor-unit conversion

For most currencies, amounts are multiplied by 100 to convert to minor units:

• A $9.99 USD transaction is sent as 999
• A 4.99 EUR transaction is sent as 499

Zero-decimal currencies (such as JPY, KRW, VND, and others) are already in their smallest unit and are sent as-is:

• A 980 JPY transaction is sent as 980
• A 14900 KRW transaction is sent as 14900

Revenue properties

The following properties are included on revenue events:

Revenue reporting options

The sales_reporting setting determines which value is converted to minor units:

Revenue examples

Subscription purchase ($9.99 USD):

• Revenue setting: "Revenue"
• Sent to PostHog: revenue: 999, currency: "USD"

Japanese purchase (980 JPY):

• Revenue setting: "Revenue"
• Sent to PostHog: revenue: 980, currency: "JPY"

Refund (-$9.99 USD):

• Sent to PostHog: revenue: -999, currency: "USD"

User Identification

The integration uses the following hierarchy for user identification:

1. Primary: originalAppUserId (if available)
2. Fallback: originalTransactionId (always present)

Anonymous user behavior

The anonymous_user_behavior setting controls what happens when no originalAppUserId is available:

This ensures consistent user tracking across:

• Multiple devices
• App reinstalls
• Legacy users without app user IDs

Sandbox Handling

With sandbox API key

If sandbox_api_key is configured:

• Production events are sent to PostHog with the production api_key
• Sandbox events are sent to PostHog with the sandbox_api_key

Without sandbox API key

If sandbox_api_key is empty:

• Production events are sent to PostHog with the production api_key
• Sandbox events are skipped (not sent)

This prevents test data from polluting production analytics.

Data Residency

PostHog supports two data residency regions:

Choose based on:

• Where your PostHog instance is hosted
• Your data privacy requirements
• Regional compliance needs (e.g., GDPR)

Testing the Integration

1. Trigger sandbox events

• iOS: Use TestFlight with a sandbox Apple ID. StoreKit Configuration files do not generate App Store Server Notifications, so webhooks and downstream integrations won't fire.
• Google Play: Use license test accounts to perform sandbox purchases.
• Stripe: Use Stripe Test Mode to create sandbox transactions.

2. Verify in PostHog

Check your PostHog project:

1. Activity tab: Verify events are arriving with sw_ prefix
2. Persons: Confirm user properties (store, environment, bundle_id) are set
3. Events: Check that revenue properties are in minor units (cents)

3. Test different scenarios

• Purchase event: Positive revenue in minor units
• Refund event: Negative revenue in minor units
• Trial start: Event without revenue properties
• Cancellation: Event without revenue properties
• Zero-decimal currency: Revenue sent without multiplication

Best Practices

1. Use Consistent User IDs: Send originalAppUserId to app stores for reliable user identification across events
2. Separate Environments: Configure a sandbox_api_key to test the full pipeline without affecting production data
3. Revenue Model: Choose between gross (Revenue) and net (Proceeds) consistently across all your integrations
4. Minor-Unit Awareness: Remember that revenue values in PostHog are in cents -- divide by 100 when building dashboards for standard currencies
5. Custom Event Names: Use custom event name mappings if your PostHog project already has established naming conventions
6. Anonymous Users: Set anonymous_user_behavior to "dontSend" if you only want events tied to known users

Common Use Cases

Revenue analytics

Events: sw_subscription_start, sw_renewal
Metric: Sum of revenue (remember values are in minor units)
Segment by: currency, product_id, countryCode

Conversion funnel

1. sw_trial_start
2. sw_trial_converted
Conversion Rate: Step 2 / Step 1

Churn analysis

Events: sw_subscription_cancelled
Segment by: cancelReason, periodType, countryCode

Refund monitoring

Events: sw_refund
Metric: Count and sum of revenue
Segment by: product_id, store

Troubleshooting

Events not appearing

1. Check API Key: Verify the key starts with phc_ and is correct for your project
2. Check Region: Ensure the region (US or EU) matches where your PostHog instance is hosted
3. Check Environment: Sandbox events require a sandbox_api_key to be sent
4. Check Distinct ID: User must have a valid originalAppUserId or originalTransactionId
5. Check Anonymous Behavior: If set to "dontSend", events for users without originalAppUserId are skipped

Revenue values look incorrect

1. Minor Units: Revenue is in cents (minor units). A value of 999 represents $9.99
2. Zero-Decimal Currencies: JPY, KRW, and similar currencies are not multiplied -- a value of 980 means 980 JPY
3. Check Sales Reporting: Verify whether you are reporting Revenue (gross) or Proceeds (net)
4. Negative Values: Refunds appear as negative minor-unit amounts

User properties not updating

1. Check $set: User properties are sent via the $set mechanism on each event
2. Properties Set: Only store, environment, and bundle_id are set as user properties
3. Verify in Persons: Check the Persons tab in PostHog for the specific distinct_id

Sandbox events not arriving

1. Check Sandbox Key: A separate sandbox_api_key must be configured
2. Missing Key: If no sandbox key is set, sandbox events are silently skipped
3. Key Format: Sandbox key should also start with phc_