Posthog Integration allows your WooCommerce store to automatically capture, enrich, and send high‑fidelity customer behavior and ecommerce events to PostHog, without writing any custom tracking code.
Installation
↑ Back to top- Upload the Plugin. In WordPress admin, go to Plugins → Add New → Upload Plugin
- Activate the Plugin. Ensure WooCommerce is active; otherwise, you’ll see an admin notice.
- Open the Settings Page. Go to WooCommerce → Settings → Advanced → Posthog (new “Posthog” section).
- Configure Core Settings.
- Project API Key: paste your PostHog project API key.
- API Host: enter your PostHog API host, e.g. https://us.i.posthog.com or https://eu.i.posthog.com (must be HTTPS).
- Configure Tracking Options
- Autocapture Events
- Capture PageView / PageLeave / Dead Clicks
- Track Product / Shop / Category / Tag / Cart / Post Views
- Identify on Checkout Email
- Do Not Track Admins
- Anonymize User Data
- Debug Mode (only for testing)
Setup and Configuration
↑ Back to topProject API Key
↑ Back to topThe Project API Key connects your WooCommerce store to the correct PostHog project. Paste the client-side project key from your PostHog Project Settings. If this is empty or incorrect, no events will reach PostHog.
API Host
↑ Back to topThe API Host is the base URL of your PostHog instance, for example, https://us.i.posthog.com, https://eu.i.posthog.com, or your self‑hosted domain. It must use HTTPS and match the instance where your project lives; otherwise, the browser cannot send events.
Autocapture Events
↑ Back to topAutocapture Events turns on PostHog’s automatic tracking of clicks, form submissions, and other UI interactions. When enabled, the plugin initializes the PostHog JS SDK with autocapture enabled, but the corresponding autocapture feature must also be active in your PostHog project to see these events.
Capture PageView
↑ Back to topCapture PageView controls whether PostHog automatically sends $pageview events on every page load. Enable this if you want standard web analytics style page view tracking; PostHog also needs pageview/autocapture behavior enabled for these events to appear.
Capture PageLeave
Capture PageLeave records when visitors leave a page, so you can see where users drop off. The plugin sets the appropriate flag in the PostHog JS configuration; PostHog must support and allow pageleave events for them to show up.
Capture Dead Clicks
↑ Back to topCapture Dead Clicks detects clicks on non-interactive or non‑responding elements, which helps you identify UX issues and confusing UI. This option tells PostHog’s JS to capture dead clicks, but you also need dead-click capture enabled in PostHog’s settings or not disabled in your project config.
Track Product Views
Track Product Views sends a custom “View Product” event whenever someone views a single product page. The event includes product details like ID, SKU, price, category, and URLs. This is a plugin-defined event and will appear in PostHog as a normal custom event with no extra configuration.
Track Shop Views
↑ Back to topTrack Shop Views sends a “View Shop” event when visitors land on your main WooCommerce shop page. It tells you how often shoppers reach your product listing and is useful for building funnels such as “Shop → Product → Cart → Checkout”.
Track Category Views
↑ Back to topTrack Category Views records “View Category” events on product category archive pages. Each event includes the category ID, slug, and name, so you can compare performance of different product categories inside PostHog.
Track Tag Views
↑ Back to topTrack Tag Views sends “View Tag” events whenever a product tag archive is viewed. This helps you understand the performance of collections built with tags (for example, “Sale”, “New Arrivals”, or campaign-specific tags).
Track Cart Views
↑ Back to topTrack Cart Views captures “Cart Viewed” events when customers open the cart page. The event contains totals, currency, item count, and a detailed list of products, giving you visibility into pre‑checkout behavior and cart abandonment.
Track Post Views
↑ Back to topTrack Post Views emits a “View Post” event on single blog posts. Use this if your content marketing and blog are part of your acquisition funnel and you want to connect content engagement to ecommerce outcomes.
Identify on Checkout Email
Identify on Checkout Email identifies visitors in PostHog as soon as they enter a valid email address during checkout. This allows you to tie the entire checkout funnel (and earlier browsing) to a single user profile, even for guest checkouts. If anonymization is enabled, the email is hashed before being sent.
Do Not Track Admins
Do Not Track Admins prevents tracking for WordPress administrators and shop managers. When enabled, the plugin skips PostHog initialization and events for those roles, so internal testing and back‑office work does not pollute your analytics.
Anonymize User Data
Anonymize User Data is a privacy and GDPR‑oriented option that hashes email addresses and strips user names from all tracking payloads. You still get consistent user identifiers (the same email always hashes to the same value), but PostHog never sees the raw email or full name. In some events, order IDs are omitted when anonymization is on.
Debug Mode
↑ Back to topDebug Mode is a development and troubleshooting switch. When enabled, the plugin logs detailed information about tracking to the browser console and WordPress error log, so you can see exactly what is being sent. This is intended for staging and debugging environments and should usually be disabled in production.
Events
↑ Back to topView Product
↑ Back to topView Product fires when a visitor opens a single product page. The event includes the visitor’s email (or its hash when anonymization is enabled), the main product category, and a detailed products array describing the viewed item (and its variations for variable products). Each product entry contains the product ID, SKU (or product ID if no SKU is set), name, price, quantity (1 for views), position, category, product URL, image URL, and optionally a variant field with the variation ID. A products_string field is also sent as a pipe‑separated list of SKUs or IDs in the form |SKU1|SKU2|SKU3|, plus the store currency.
View Shop
↑ Back to topView Shop fires when someone visits the main WooCommerce shop page. The event carries the visitor’s email (or hashed email), a page_type of shop, the shop page title, and the store currency. This lets you see how often users reach your main product listing and how that page performs in funnels.
View Category
↑ Back to topView Category fires on WooCommerce product category archive pages. It includes the visitor’s email (or hashed email), a page_type of category, and full category metadata: the term ID, name, and slug. The event also contains the store currency so you can compare category performance across regions or storefronts.
View Tag
↑ Back to topView Tag fires on product tag archive pages. The event contains the visitor’s email (or hashed email), a page_type of tag, and the tag’s term ID, name, and slug, along with the current store currency. Use it to measure how well tag‑based collections (e.g. “Sale”, “New”, campaign tags) attract and convert traffic.
Cart Viewed
↑ Back to topCart Viewed fires when the cart page is opened. It includes the visitor’s email (or hashed email), a page_type of cart, the raw cart total, the store currency, and the total number of items in the cart. A products array describes each cart line with product ID, SKU, name, price, quantity, category, URL, and image URL, plus a products_string field that condenses the SKUs/IDs into a pipe‑delimited string for easy segmentation in PostHog.
Add to Cart
↑ Back to topAdd to Cart fires whenever a product is added to the cart, including standard buttons, AJAX add‑to‑cart, and URL‑based add‑to‑cart links. The event includes the visitor’s email (or hashed email), the product ID, a product_sku field (SKU or ID fallback), the product name, a normalized product price, the quantity added, the variation ID (if any), and the variation attributes array. The current store currency is also attached so you can analyze add‑to‑cart behavior across markets.
Checkout Started
Checkout Started fires when a visitor reaches the checkout page and a valid cart is present. It records the visitor’s email (or hashed email), total, subtotal, shipping amount, tax amount, discount amount, applied coupon codes (as a single comma‑separated string), and the store currency. It also includes a products array with all cart items and a products_string list, allowing you to see exactly which products and baskets are making it to checkout.
Purchase Completed
↑ Back to topPurchase Completed fires on the thank‑you page after a successful order, including FunnelKit and custom order‑received flows. The event carries the customer’s billing email (or its hash when anonymization is enabled), the full set of order financials (total, subtotal, shipping, tax, and discount), any applied coupon codes, and the order currency. When anonymization is off, an order_id field is also sent; when it is on, the order ID is omitted for privacy. A products array describes each purchased item with product ID, SKU or fallback ID, name, price, quantity, category, URL, image URL, and position, and products_string summarizes the SKUs/IDs for quick funnel and cohort definitions.
View Post
↑ Back to topView Post fires on single blog posts when post tracking is enabled. It does not require WooCommerce context and sends core content metadata: the post_id, post title, slug, and full post URL. This event lets you tie content engagement (blog views) to downstream ecommerce activity inside PostHog.
Coupon Applied (via coupon data endpoint)
Coupon Applied is tracked from the frontend using the coupon data provided by the plugin’s coupon AJAX endpoint. When a coupon is applied, the plugin exposes a payload that includes the coupon_id (the actual coupon code), a human‑readable coupon_name (the coupon description or the code if no description is set), the numeric discount amount attributed to that coupon, a cart_id (cart hash) for correlation, and the store currency. This data is designed to be captured as a custom PostHog event so you can measure how different coupons impact conversion and revenue.
Native PostHog Events (pageview, pageleave, autocapture, dead clicks)
In addition to the custom ecommerce events above, the plugin can configure PostHog’s JavaScript SDK to emit core PostHog events such as $pageview, $pageleave, generic autocapture events (clicks, form submissions, etc.), and dead‑click events. These events follow PostHog’s own schema and depend on the corresponding features being enabled in your PostHog project; the plugin’s role is to pass the correct flags during initialization so that, once enabled on the PostHog side, they start flowing automatically.
FAQs
↑ Back to top
Do I need a PostHog account to use this plugin?
Yes. The plugin is a bridge between WooCommerce and PostHog. You must have a PostHog project (cloud or self‑hosted) and provide its Project API Key and API Host in the plugin settings.
Where do I find the Project API Key and API Host?
In your PostHog project go to Project Settings → Project API keys and copy the client‑side key. The API host is usually https://us.i.posthog.com, https://eu.i.posthog.com, or your self‑hosted domain.
Which events does the plugin track out of the box?
It tracks ecommerce events like View Product, View Shop, View Category, View Tag, Cart Viewed, Add to Cart, Checkout Started, Purchase Completed, and optionally View Post. It can also enable PostHog’s native pageview, pageleave, autocapture, and dead‑click events depending on your settings.
Do I need to write any custom JavaScript to track WooCommerce events?
No. All core WooCommerce events (product views, cart, checkout, orders, coupons) are tracked automatically once the plugin is configured. You only need custom code if you want to send completely custom events.
What is the difference between plugin events and PostHog’s “autocapture”?
Plugin events are ecommerce‑aware (they know about products, prices, coupons, etc.) and are defined entirely by this plugin. Autocapture is a PostHog feature that records generic UI interactions (clicks, form submits, etc.). The plugin can toggle autocapture on/off, but autocapture behavior is ultimately controlled by your PostHog project settings.
How does the plugin handle logged‑in vs guest users?
Logged‑in users are identified by their WordPress account email (hashed if anonymization is on). Guests are identified from billing email in the cart/checkout or from order data on the thank‑you page. Optionally, you can enable “Identify on Checkout Email” to identify guests as soon as they type a valid email in checkout.
What does “Anonymize User Data” actually do?
When enabled, the plugin hashes email addresses with wp_hash() and removes names from user payloads. PostHog sees only the hash as the user’s identifier, so you can still track behavior and funnels without storing real emails or names in PostHog.
Can I exclude store admins and staff from tracking?
Yes. With “Do Not Track Admins” enabled, WordPress administrators and shop managers are not tracked at all. PostHog won’t receive events from those roles, which keeps your analytics clean from internal testing.
Does it work with FunnelKit (WooFunnels) and custom thank‑you pages?
Yes. The plugin includes specific logic to detect orders from FunnelKit using the wfocu-key parameter and still sends Purchase Completed events with full order details from those flows.
Does it support Elementor popups and forms?
Yes. When Elementor is active, the plugin loads an additional script that hooks into Elementor popups/forms so those interactions can be tracked and tied into your PostHog events.
Can I customize the event properties that are sent?
Yes. There are multiple WordPress filters such as phi_user_data, phi_order_tracking_data, phi_checkout_tracking_data, phi_product_tracking_data, phi_shop_tracking_data, phi_category_tracking_data, and phi_tag_tracking_data. You can hook into these to add, remove, or modify properties before they are sent.
Is this plugin compatible with WooCommerce HPOS (High‑Performance Order Storage)?
Yes. The plugin proactively declares compatibility with WooCommerce’s custom order tables / HPOS feature and uses the official APIs, so it works with both the legacy and HPOS storage engines.
Will this plugin slow down my store?
It is designed to minimize overhead: data is cached, scripts are loaded only where needed, and tracking runs mostly on the frontend. Enabling Debug Mode adds extra logging overhead and should be used only in staging or for short debugging sessions.
How can I check what exactly is being sent to PostHog?
Turn on Debug Mode in the settings. The plugin will log detailed information to the browser console and WordPress error log, including event names and payloads, so you can verify tracking before turning debug back off. You can also check the PostHog Activity tab.
