Identity Merge

Identity Merge is currently in closed BETA and is subject to change.

Identity Merge (ID Merge) is an updated version of Mixpanel’s identity management services. It is designed to address the challenges customers face when using previous versions of Mixpanel’s identity management. 

This article covers the improvements to Mixpanel's identity management infrastructure, how to check if your project has Identity Merge enabled, and the changes you can expect when the new system is enabled.

Benefits of the New System

All pre-authentication activity can now be mapped back to a user

Previously, Mixpanel could only map pre-sign up activity back to a user who was later identified. This only worked once.  Any activity a user did anonymously before signing in again could not be attributed to that user.  The new system makes it possible to connect all pre-authentication activity back to an authenticated user - regardless of what device they are on or when they register.

Merge data with different unique identifiers

Mixpanel can now merge events with different unique identifiers. The existing identify and alias methods along with the new $merge event can now be used to merge event streams under a single user, even after data has been ingested.

Enable ID Merge

You can see if your project has ID merge enabled by checking for the id merge toggle in Project Settings. If you wish to add an additional project to ID merge, email


For client-side implementations, make sure your SDK version is up to date so ID merge works when turned on.  ID Merge is compatible with: 

    • Javascript: 2.29.0+
    • iOS - obj: 3.4.7+
    • iOS - swift: 2.6.3+
    • Android: 5.6.3+
    • Unity: 2.0.0+

You don't need to change anything in your code if you already have a Mixpanel implementation with a functioning identity management system.  The existing Mixpanel methods start working with the new system as soon as it is enabled. 

Changes After Enabling ID Merge

The following is a list of expected changes after enabling the ID merge feature. 

New events will show up in your project

Mixpanel will track new events when the identify and alias methods are called in your implementation. These events do not count towards billing.

Unique user counts may decrease, user profile counts may decrease

Since ID Merge can merge already ingested events together under a single user, you may notice a change in the unique counts of events in your project. If a user profile exists for multiple distinct ids that are merged, Mixpanel will hide all but one of the user profiles.

Monthly Tracked User (MTU) tallies may decrease 

The MTU billing system is based on the number of users you track with Mixpanel.  Since ID Merge is able to map user activity together more effectively, you may notice a decrease in your MTU count.  Note: Previously months billing tallies will not be modified.

You can no longer control the canonical id for users in Mixpanel

The ID Merge system will now determine which distinct_id is used as the canonical id for a user in Mixpanel. Any merged id can be used to query for information about a user with our APIs, but the results of the query may return a with different distinct_id value than the one used in the query. The id that is returned is the canonical id determined by Mixpanel for that user. 

To ensure the queried id is available in the results, it is best practice to send your chosen user id in as an explicit property for events and profiles.

Avoid using non-Mixpanel generated anonymous ids

The updated identify and alias methods come with some built-in guardrails to help avoid users sharing a device from being incorrectly merged together. These guardrails rely on anonymous activity using Mixpanel generated distinct id’s.  Whenever possible use Mixpanels built-in SDKs to generate anonymous distinct id’s to allow for correct merging behavior. Note: We’ve worked Segment to ensure their anonymous ids are compatible with our new system.

User profiles will not automatically aggregate all user properties when merged 

This will mainly affect implementations that have duplicate or anonymous user profiles.  

ID merge will map events from merged ids together.  When this happens, Mixpanel will display the profile with the Mixpanel determined canonical id.  User property values will not be updated or added based on other profiles merged. To avoid losing profile properties, we recommend creating user profiles after a user has been identified.

Distinct_ids cannot be un-merged

Merged distinct IDs cannot be unmerged.

$merge Event

The $merge event will merge the event histories of two unique IDs. If one or both are already merged with data tied to other IDs, then the result will be the merge of all data of the IDs.

Note: merge is a very powerful tool, so we will only accept merge events that are sent via, which is protected by the project api secret.  In practice, this means merge calls can only be sent server-side.  See here for how to send events to Mixpanel via the import endpoint.

Event properties

Property name





A list of two distinct_ids that you would like to merge together. There must be exactly two IDs in the list.




The project token. If using an off-the-shelf SDK this should be included for you automatically.


    "event": "$merge",
    "properties": {
       "$distinct_ids": ["B55CAFBF4708C950", "12345"],    
       "token": "e3bc4100330c35722740fb8c6f5abddc"
Did this answer your question?



Please sign in to leave a comment.

Articles in this section