kapa.ai I am trying to merge two different distinct IDs. When I use the alias API, the response code is 200 and response is '1', but there's no change in the user profile. The same issue occurs when I try to modify the distinct ID through the web console. Is there a solution for this?
The issue you're experiencing is likely due to the type of identity management system your Mixpanel project is using. The alias API (i.e., the $create_alias event) only works for projects using the Original ID Merge or Legacy ID Management systems. It has no effect in projects using the Simplified ID Merge system, which is the default for new organizations created from April 2024. In Simplified ID Merge, sending an alias event will return a 200 response, but it will not actually merge the IDs or affect user profiles—this is expected behavior and documented by Mixpanel:
The $create_alias event payload is only useful for projects using the Original ID Merge system and the Legacy ID Management System; it has no functionality in the Simplified ID Merge system.
Mixpanel Identity API: Create Alias
To merge two distinct IDs in Mixpanel, you must use the correct method for your project's identity management system:
- Original ID Merge: Use the $merge event via the Import API to merge two distinct IDs.
Example payload:
{
"event": "$merge",
"properties": {
"$distinct_ids": [
"user_id_1",
"user_id_2"
],
"token": "YOUR_PROJECT_TOKEN"
}
}
This must be sent to the /import endpoint and is irreversible.
Mixpanel Docs: Identifying Users (Original)
- Simplified ID Merge: You cannot merge two $user_ids. The only supported merge is between a $device_id (anonymous ID) and a $user_id (identified user). If you need to merge two identified users, this is not supported in Simplified ID Merge.
Mixpanel Docs: Identifying Users (Simplified) FAQ
What you should do:
- Check which identity management system your project is using.
- If you are on Simplified ID Merge, you cannot merge two identified users (two $user_ids or two non-anonymous distinct_ids).
- If you are on Original ID Merge, use the $merge event via the Import API as shown above.
Modifying the distinct ID through the web console will also not merge users; Mixpanel does not support changing a user's distinct_id directly in the UI.
If you need to merge two identified users and are on Simplified ID Merge, the only workaround is to ensure you always use a single, unchanging user ID for each user going forward. If you need more advanced merging, you may need to use a project with Original ID Merge enabled.
For more details, see:
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Let me check the knowledge base for you again. One moment! 📚
In Mixpanel projects using the Simplified ID Merge API, you cannot merge two identified users (i.e., two $user_ids or two non-anonymous distinct_ids). The only supported merge is between an anonymous user ($device_id) and an identified user ($user_id).
How merging works in Simplified ID Merge:
- When a user is anonymous, events are sent with a $device_id.
- When the user logs in or registers, you call identify(<user_id> ), and events are sent with both $device_id and $user_id.
- When an event contains both a $device_id and a $user_id for the first time, Mixpanel automatically merges the anonymous and identified states into a single user profile. All previous events with that $device_id are retroactively attributed to the $user_id moving forward.
You cannot merge two $user_ids or change a $user_id in Simplified ID Merge. If you attempt to do so, Mixpanel will treat them as separate users, and there is no supported method to combine them into a single profile in this API version Identifying Users (Simplified) FAQ Considerations when Migrating.
Summary:
- You can merge a $device_id (anonymous) with a $user_id (identified) by sending an event with both properties.
- You cannot merge two $user_ids or two identified distinct_ids in Simplified ID Merge.
If you need to merge two identified users, this is only possible in projects using the Original ID Merge API.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Let me check the knowledge base for you again. One moment! 📚
In the Simplified ID Merge API, once an anonymous device ID (C, via $device_id) has been associated (merged) with a user ID (A, via $user_id), that association is permanent. If you later try to associate the same $device_id (C) with a different user ID (B), Mixpanel will treat $user_id B as a new, separate user and will not merge C with B. The original association between C and A remains, and B will not inherit any of the events or history from C.
This is because each $device_id can only be merged with one $user_id, and once that mapping is established, it cannot be changed or reassigned to another user ID. Attempting to do so will result in the creation of a new user profile for B, without the history of C Identifying Users (Simplified) FAQ Considerations when Migrating.
Summary:
- C (device ID) + A (user ID): merged, all events unified.
- Later, C + B: B is treated as a new user, not merged with C or its history.
If you need to support scenarios where a device is shared among multiple users, you should generate a new $device_id (typically by calling reset() in the SDK) when a user logs out, so that each user gets a unique device ID and their histories remain separate Identifying Users (Simplified) Example User Flows.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Let me check the knowledge base for you again. One moment! 📚
In Mixpanel's SDKs, both alias() and identify() methods exist, but their behavior depends on which identity management system your project uses:
- identify():
This method is supported and should be used in all projects. In the Simplified ID Merge API, you use identify() to associate a known user ID ($user_id) with the current device's anonymous ID ($device_id). This triggers the merge between anonymous and identified states.
Identifying Users (Simplified)
- alias():
The alias() method is present in the SDKs for backward compatibility, but in projects using the Simplified ID Merge API, calling alias() (or sending $create_alias events) has no effect—it will not merge IDs or affect user profiles. The method only works in projects using the Original ID Merge or Legacy ID Management systems.
Mixpanel Identity API: Create Alias
Migrating to Simplified ID Merge
Summary:
- Use identify() in all projects to associate a user ID with a device.
- Do not use alias() in Simplified ID Merge projects; it will not work.
If you are unsure which system your project uses, you can check in your project settings.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.
Let me check the knowledge base for you again. One moment! 📚
Let me check the knowledge base for you again. One moment! 📚
To handle the transition from a guest ID (anonymous user) to a distinct ID (identified user) in the Mixpanel SDK, you should use the following approach, especially if your project uses the Simplified ID Merge API:
1. Track events for the guest user:
When a user is browsing as a guest, Mixpanel automatically assigns a $device_id to the user. All events tracked at this stage are associated with this anonymous device ID.
2. Identify the user upon login or registration:
When the user signs up or logs in, call the .identify(<user_id> ) method with the user's unique identifier (such as a database ID). This will associate the current $device_id (guest/anonymous) with the new $user_id (identified user). Mixpanel will then merge all previous anonymous events with the identified user profile.
Example (JavaScript SDK):
// User signs in or registers
mixpanel.identify('USER_ID');
3. Send at least one event after identify:
After calling .identify(), send at least one event to ensure the merge between the guest and identified user is triggered.
mixpanel.track('Signed Up');
Key Points:
- The merge between guest and identified user is automatic when both $device_id and $user_id are present in the same event.
- Do not use .alias() in Simplified ID Merge projects, as it has no effect.
- If a user logs out and another user logs in on the same device, call .reset() to generate a new $device_id and prevent mixing user histories.
For more details, see the official documentation on Identifying Users (Simplified) and Example User Flows.
kapa.ai is still learning and improving, please let me know how I did by reacting below.
ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.