The first time a client showed me a revenue report in Mixpanel that was roughly double their Stripe total, I assumed the worst. It turned out to be the simplest thing: the purchase event was firing from the browser and from the server, and nothing told Mixpanel they were the same purchase.
That’s what $insert_id is for. It’s a small property that does a lot of quiet work, and when it’s wrong, it’s wrong in both directions: duplicates you don’t want, or real events that disappear.
Why duplicates happen
Duplicate events are normal. They come from:
- Network retries. A request times out, the SDK sends it again, and both copies arrive.
- Client-side batching that resends a batch after a partial failure.
- Multiple sources sending the same event, the classic case being a hybrid browser + server setup.
Mixpanel expects this and has a deduplication system built in. You just have to feed it correctly.
How Mixpanel decides two events are the same
Mixpanel compares four fields:
- Event name
distinct_id- Timestamp (
time) $insert_id
If all four match, the events are duplicates and reports show just one. Every other property is ignored for this check. Two events with matching keys but a different $city are still duplicates.
An important edge case: if you send an event to the ingestion API without an $insert_id, Mixpanel generates one, but that event is not eligible for deduplication. The client SDKs add one for you; server code often doesn’t.
Two layers of deduplication
Mixpanel deduplicates in two places, and they behave differently.
Query-time deduplication happens immediately whenever you run a report. Matching events collapse to one, generally the most recently ingested version. But this only affects what you see in the UI. Raw event exports still contain every copy, exactly as ingested. Mixpanel also notes it doesn’t guarantee upsert behavior, so don’t use resends as a way to “update” an event.
Compaction-time deduplication runs in the background, usually after a few hours and again after about 20 days. It matches on event name, distinct ID and insert ID within the same calendar day, without needing an exact timestamp match. Mixpanel is explicit that its timing isn’t guaranteed and it may not always run, so treat it as cleanup, not a feature to build on.
Using $insert_id in a hybrid setup
This is where deduplication earns its keep. If you send a conversion from both the browser and the server during a migration or for redundancy, both copies need identical values for all four keys.
In practice that means:
- Generate the
$insert_idonce, at the moment the event happens, and pass it to both senders. For a purchase, deriving it from the order ID works well. - Use the same
distinct_idon both sides. If the server has a different ID for the user (see post 2 on identity), the events won’t match. - Use the same timestamp. Don’t let the server stamp its own receive time. Pass the original event time through.
- Keep the event name identical, including capitalization.
If any of these four differ, Mixpanel counts two events.
Rules for a good $insert_id
- Unique per event occurrence. One click, one purchase, one ID.
- Never reuse a user-level value. Mixpanel specifically warns against using something like the distinct ID as the insert ID, because every event from that user can collapse into one. You’ll lose data and not notice.
- Short and simple. Mixpanel’s import validation limits insert IDs to 36 bytes using letters, numbers and hyphens, so a standard UUID fits. Check the import API reference for current limits.
Exporting data? Deduplicate it yourself
This one trips up data teams. Because raw exports skip query-time deduplication, your warehouse can contain duplicates that never appear in Mixpanel’s UI. Mixpanel recommends applying the same four-key logic to exported data. If you sync Mixpanel to BigQuery or Snowflake, add that dedup step to your pipeline, or your warehouse numbers will run higher than Mixpanel’s.
Mistakes to avoid
- Sending server-side events with no
$insert_id, so retries become duplicates. - Different timestamps on browser and server copies of the same event.
- Using an order-level ID across multiple different events with the same name and user on the same day. Make it specific to the event.
- Relying on compaction to fix duplicates in a report you’re presenting tomorrow.
- Assuming the warehouse matches the UI.
How to check if you have a problem
Compare a business total you trust (orders in your store, payments in Stripe) with the matching Mixpanel event count for the same period. If Mixpanel is higher by a consistent percentage, look for an event firing from two places. If it’s lower, look for insert IDs being reused.
Final thoughts
Deduplication isn’t something you set up once and forget. It’s a contract between every system that sends events to Mixpanel. Agree on how insert IDs are created, pass them through every path, and your counts will hold up when someone checks them against finance.
Sources
- Mixpanel: Event Deduplication
- Mixpanel: Identifying Users (Simplified)
- Mixpanel docs on GitHub: Import Events reference
