App guides
The PostHog app sends your store's orders, payments, refunds and subscription changes to PostHog as they happen. Events come from Swell, not the shopper's browser, so ad blockers can't drop them, and each one is tied to the customer's PostHog profile.
The app works with PostHog Cloud, in the US or EU, and with self-hosted PostHog.
| When | What the app does |
| A customer places an order | Sends Order Completed, with the totals, discount, coupon, currency and products. |
| An order is canceled or fully fulfilled | Sends Order Cancelled, or Order Delivered if you turn it on. |
| A payment is captured | Sends Payment Completed with the amount as revenue, for orders, invoices and subscriptions alike. |
| A refund succeeds | Sends Order Refunded with the amount as negative revenue, for partial refunds too. |
| A subscription starts, renews, fails to pay or is canceled | Sends Subscription Started, Renewed, Payment Failed or Cancelled. |
| A subscription is paused or resumed | Sends Subscription Paused or Resumed, if you turn them on. |
- A PostHog project, on PostHog Cloud or self-hosted.
- For the test environment, a separate PostHog project, so test orders stay out of your live data.
Install PostHog from the Swell App Store, and set it up in your test environment before the live one.
Copy your project API key
In PostHog, open Project settings and copy the Project API key, which starts with phc_. This key can only send events. It can't read your PostHog data.
Add it to the app
In Swell, go to Apps > PostHog > Settings and paste the key in Project API key. Under PostHog region, choose US Cloud or EU Cloud to match your PostHog project. For self-hosted PostHog or a proxy, choose Self-hosted or proxy and enter its full address, including https://, in PostHog URL. Click Save settings. Events are sent from then on.
Send a test event
Click Send test event. A Swell Test Event appears in PostHog under Activity, from a person named swell-test- and your store ID, which you can delete. If the key, region or address is wrong, the message says what to fix.
Check the key this way: events sent with a wrong project API key are accepted by PostHog and then dropped, so nothing else shows the mistake.
Choose the events
Under Orders, Revenue and Subscriptions, turn on the events to send, and click Save settings. Order Delivered, Subscription Paused and Subscription Resumed are off at first. The rest are on.
Set up revenue analytics
This step is optional. In PostHog, go to Data management > Revenue and choose Add Revenue Event. Pick Payment Completed as the event, revenue as the Revenue Property and currency as the Dynamic Currency Property, and turn on Values are in cents. Do the same for Order Refunded.
Place a test order
Place a test order and pay for it. Within a few seconds, PostHog shows Order Completed under Activity, on the customer's profile, and Payment Completed once the payment is captured.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 to 4 with the key of your live PostHog project, and step 5 in that project.
Each event carries the properties below, plus swell_store_id. Properties without a value in Swell are left out, except guest and trial, which are always true or false.
| Event | Sent when | Properties |
| Order Completed | A customer places an order. | order_id, order_number, total, subtotal, shipping, tax, discount, coupon, currency, guest, products. Each product has product_id, variant_id, name, variant, price and quantity. |
| Order Cancelled | An order is canceled. | The same as Order Completed. |
| Order Delivered | An order is fully fulfilled. Off at first. | order_id, order_number |
| Payment Completed | A payment succeeds. Payments authorized first are sent when they're captured. Gift card and store credit payments aren't sent. | revenue, currency, order_id, invoice_id, subscription_id, payment_id, payment_method |
| Order Refunded | A refund succeeds, partial ones included. Refunds of gift card and store credit payments aren't sent. | revenue (negative), currency, order_id, subscription_id, refund_id, payment_id, reason |
| Subscription Started | A customer starts a subscription, trials included. Draft subscriptions aren't sent. | subscription_id, plan_id, plan, product_id, product, variant, price, recurring_total, currency, interval, interval_count, trial |
| Subscription Renewed | A subscription is charged for a new period. The first payment, made with the order, isn't a renewal. | The same as Subscription Started. |
| Subscription Payment Failed | A subscription charge fails. | The same as Subscription Started. |
| Subscription Cancelled | A subscription is canceled. | The same as Subscription Started, plus cancel_reason. |
| Subscription Paused | A subscription is paused. Off at first. | The same as Subscription Started. |
| Subscription Resumed | A paused subscription is resumed. Off at first. | The same as Subscription Started. |
Each event's person in PostHog is the Swell customer, identified by their Swell customer ID. Every event also sets the person's email, and their name when the customer has one, so PostHog shows them by email. Orders from guest checkouts have guest set to true.
Only Payment Completed and Order Refunded carry revenue, in the currency's smallest unit, such as cents. Every charge is one payment, whatever it pays for, so revenue is counted once. Orders and subscription events have totals and prices but no revenue.
Gift card and store credit payments aren't counted, because that money was counted when the gift card was bought or the credit was earned.
Each event has the time it happened in Swell, not the time it was sent. When Swell sends an event again after an error, it has the same event ID, so PostHog keeps only one.
| Where | What it's for |
| Apps > PostHog > Settings | The project API key, the region or address, Send test event, and the events to send. |
Settings are in Apps > PostHog > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Project API key | From PostHog > Project settings. Starts with phc_. Required. | None |
| PostHog region | US Cloud, EU Cloud, or Self-hosted or proxy. | US Cloud |
| PostHog URL | For Self-hosted or proxy only. The full address of your PostHog, including https://. | None |
| Send test event | Sends one Swell Test Event to check the connection. Save the settings first. | |
| Orders | Order completed, Order cancelled, Order delivered. | On, on, off |
| Revenue | Payment completed, Refund. | On, on |
| Subscriptions | Subscription started, renewed, payment failed, cancelled, paused, resumed. | On, on, on, on, off, off |
- Events are sent from when you save the project API key. Past orders, payments and subscriptions aren't imported.
- The app sends store events only. To see storefront visits and page views, add PostHog's own snippet to your storefront.
- Events are sent from Swell's servers, so PostHog doesn't add a location to them.
- Event names are fixed.
- If PostHog is down or rate-limits the app, Swell sends the event again later. Other errors are logged and the event isn't sent again.
- PostHog accepts events sent with a wrong project API key and then drops them, so the app can't report it. Use Send test event to check the key.
- If PostHog keeps failing for about 4 days, Swell turns off the app's event function and emails the store's admins. Reinstall the app to turn it back on.
The app logs each event PostHog rejects. In the Swell dashboard, the logs are under Developer > Console > Logs.
Copy the key again from Project settings in PostHog. It starts with phc_. A personal API key doesn't work here. Also check that PostHog region matches your project: a key from a US Cloud project is rejected by EU Cloud.
PostHog didn't answer, or answered with a server error or a rate limit. For self-hosted PostHog or a proxy, check that PostHog URL is the full address, including https://. Otherwise, try again in a few minutes.
Enter the key, and for self-hosted PostHog a full address in PostHog URL, then click Save settings before Send test event.
Click Send test event to check the key and region. Then check that the event is turned on in the app settings. Events are sent only for changes made after the key was saved, and Payment Completed only once a payment is captured.
The app sends revenue in cents. In PostHog, turn on Values are in cents for Payment Completed and Order Refunded under Data management > Revenue.
Uninstalling the app stops sending events to PostHog. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Events and person profiles already in PostHog stay there.
| Function | Runs on | What it does |
| posthog-capture | order.submitted, order.canceled, order.delivered, payment.succeeded, payment.refund.succeeded, subscription.created, subscription.paid, subscription.payment_failed, subscription.canceled, subscription.paused and subscription.resumed | Reads the record and the customer, and sends one event to PostHog. |
| posthog-test | The Send test event button | Checks the key and sends a Swell Test Event. |
Events go to the PostHog capture API at /i/v0/e/ on the chosen host. The distinct_id is the Swell account ID, and each event has $set with the customer's email and name, $geoip_disable set to true, and swell_store_id. The uuid is derived from the Swell event ID and the timestamp comes from it, so a retried delivery is deduplicated. Network errors, timeouts, 429 and 5xx responses, and Swell API errors other than 404, make Swell retry the event. Other 4xx responses are logged and not retried, and records deleted since the event are skipped.
Swell builds and maintains the PostHog app. For help with the app, email support@swell.is. For questions about your PostHog account or project, contact PostHog.