Using Simplified ID Merge API for Non-Browser ID Linking

Eliott C. · 2025-07-29 08:15:31.013619+00

We're using the Simplified ID Merge API. On user login, right after calling the standard identify(user_id), we fire an additional custom event from the client. Its sole purpose is to link a server-side identity (a name+phone hash) to the user. For this event, we set $user_id to the logged-in user's ID and $device_id to our custom hash, which is different from the SDK's current browser ID. Is this a valid approach to use the client to trigger a merge for a non-browser-native ID, or are there potential side effects we should be aware of?

Mixpanel is headed to Money20/20 October 26 - 29 in Las Vegas, Nevada!

Using Simplified ID Merge API for Non-Browser ID Linking | Mixpanel Community

8 comments

· Sorted by Oldest

kapa.ai
APP
·
·
Please stand by Eliott C. as I search the knowledge base. I normally take about 15 seconds or so. 👋
Feel free to ask a follow-up question once I've answered by mentioning me with @kapa.ai
kapa.ai
APP
·
·
Your approach—sending a custom event with $user_id set to the logged-in user's ID and $device_id set to a custom hash (name+phone hash), which is different from the SDK's browser-generated $device_id—will technically trigger a merge in the Simplified ID Merge API. Any event containing both $user_id and $device_id will cause Mixpanel to merge those two IDs into the same identity cluster, and the $user_id will become the canonical distinct_id for that user moving forward Understanding Simplified ID Merge Canonical Distinct ID.However, there are important side effects and considerations:Best Practice: Mixpanel recommends using $device_id for device/session-based anonymous identifiers and $user_id for stable, unique user identifiers (such as a database ID). If you need to associate additional identifiers (like a name+phone hash) with a user, consider storing them as user profile properties or custom event properties, rather than overloading $device_id Identifying Users (Simplified).Summary: While your approach will technically trigger a merge, it is not recommended and may lead to confusing or fragmented identity clusters. Use $device_id for device/session IDs and $user_id for user IDs. Store other identifiers as custom properties.
If you need to support multiple user IDs per user (such as both email and phone), the Simplified ID Merge API does not support this—consider using the Original ID Merge API instead Considerations when Migrating.
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.
Eliott C.
·
·
kapa.ai Our core challenge, which the 'user properties' suggestion doesn't seem to solve, is linking past, server-side anonymous events* to a user's profile after they've been identified. Consider this specific, critical scenario for our e-commerce platform:
1.
A guest completes a checkout. Our server must track a "Complete Order" event at that moment. The only unique identifier we have is a hash of their name and phone number (ph_...), which we use as the distinct_id for this event.
2.
A week later, that same person creates an account and is assigned a permanent member_id.
3.
We now need to link the "Complete Order" event from step 1 to this new member_id's history. Storing the ph_... hash as a user property on their new profile doesn't seem to merge the past event's history into their timeline.
Given this, isn't sending a targeted merge event (with $device_id = ph_... and $user_id = member_id) the only practical way to retroactively connect that specific server-side event to the user's canonical profile? If there's a better way to solve this exact use case, we would be very grateful to learn it.
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
You are correct in your understanding: in the Simplified ID Merge system, the only way to retroactively link past server-side anonymous events (tracked with a unique identifier like your ph_... hash) to a newly identified user (member_id) is to send an event that includes both the anonymous identifier (as $device_id) and the new user identifier (as $user_id). This triggers Mixpanel to merge the two IDs into a single identity cluster, and all events previously associated with the $device_id (ph_...) will be attributed to the $user_id (member_id) moving forward Understanding Simplified ID Merge.Key points from the documentation:Why user properties alone are not sufficient: Storing the ph_... hash as a user property on the profile does not merge the event histories. User properties are metadata for querying and segmentation, but do not affect the underlying identity cluster or event attribution Identifying Users (Simplified) FAQ.Your approach is valid: Sending a targeted event (from client or server) with both $device_id = ph_... and $user_id = member_id is the correct and recommended way to merge the histories in this scenario. This will retroactively associate all events tracked with ph_... as the distinct_id to the new member_id profile.No better alternative is documented: The knowledge sources do not describe any alternative method for retroactively merging server-side anonymous events with a newly identified user in the Simplified ID Merge system. Your approach aligns with Mixpanel’s documented best practices for this use case.Summary: Yes, sending a merge-triggering event with both $device_id (ph_...) and $user_id (member_id) is the correct and only documented way to retroactively link those histories in Mixpanel’s Simplified ID Merge system. This is the intended mechanism for your scenario.
If you have further requirements (such as supporting multiple user IDs per user), note that Simplified ID Merge does not support this, and you would need to consider the Original ID Merge API for more complex identity management Considerations when Migrating.
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.
Eliott C.
·
·
kapa.ai That confirms our server-side logic is sound. To be perfectly clear about our client-side implementation: we are not altering the SDK's default $device_id for general events like page views or clicks. Those events correctly use the browser's anonymous ID managed by your SDK. Our custom "Request ID Merge" event is an additional, separate action fired only at login. Its sole purpose is to trigger the merge for our server-generated ph_... hash, which the standard identify() call doesn't know about. Given that we are not interfering with the SDK's default device_id management for all other events, can you confirm that this specific, non-disruptive use of a custom merge event on the client is also considered a safe and valid practice?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
Yes, based on the documentation, your approach is considered safe and valid for the scenario you described.As long as you are not altering the SDK’s default $device_id for general client-side events (such as page views or clicks), and are only firing a single, custom “Request ID Merge” event at login—with $user_id set to the logged-in user’s ID and $device_id set to your server-generated ph_... hash—this will not interfere with the SDK’s normal device ID management. This targeted event will simply trigger the merge between the server-side anonymous identifier and the user’s canonical profile, as intended by the Simplified ID Merge system.The documentation explicitly states that including both $device_id and $user_id in an event is the mechanism for merging identities, and it is valid to use a custom $device_id for this purpose, provided it is unique and only used for this merge action. This approach is supported and does not disrupt the SDK’s handling of browser-based anonymous IDs for other events Understanding Simplified ID Merge.> “As soon as the user is identified (i.e. logged in), the events should include both $device_id (user’s Anonymous ID) and $user_id (user’s User ID) properties. A single instance of such event is adequate to trigger identity merging which merges [the anonymous ID] and [the user ID].”
— Understanding Simplified ID MergeThere are no warnings in the documentation against this specific, non-disruptive use of a custom merge event, as long as you do not use the custom $device_id for other client-side events.In summary:
Your client-side implementation, as described, is a safe and valid practice for triggering a merge between a server-side anonymous identifier and a user’s profile in Mixpanel’s Simplified ID Merge system.
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.

kapa.ai
APP
·
·
Please stand by Eliott C. as I search the knowledge base. I normally take about 15 seconds or so. 👋
Feel free to ask a follow-up question once I've answered by mentioning me with @kapa.ai
kapa.ai
APP
·
·
Your approach—sending a custom event with $user_id set to the logged-in user's ID and $device_id set to a custom hash (name+phone hash), which is different from the SDK's browser-generated $device_id—will technically trigger a merge in the Simplified ID Merge API. Any event containing both $user_id and $device_id will cause Mixpanel to merge those two IDs into the same identity cluster, and the $user_id will become the canonical distinct_id for that user moving forward Understanding Simplified ID Merge Canonical Distinct ID.However, there are important side effects and considerations:Best Practice: Mixpanel recommends using $device_id for device/session-based anonymous identifiers and $user_id for stable, unique user identifiers (such as a database ID). If you need to associate additional identifiers (like a name+phone hash) with a user, consider storing them as user profile properties or custom event properties, rather than overloading $device_id Identifying Users (Simplified).Summary: While your approach will technically trigger a merge, it is not recommended and may lead to confusing or fragmented identity clusters. Use $device_id for device/session IDs and $user_id for user IDs. Store other identifiers as custom properties.
If you need to support multiple user IDs per user (such as both email and phone), the Simplified ID Merge API does not support this—consider using the Original ID Merge API instead Considerations when Migrating.
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.
Eliott C.
·
·
kapa.ai Our core challenge, which the 'user properties' suggestion doesn't seem to solve, is linking past, server-side anonymous events* to a user's profile after they've been identified. Consider this specific, critical scenario for our e-commerce platform:
1.
A guest completes a checkout. Our server must track a "Complete Order" event at that moment. The only unique identifier we have is a hash of their name and phone number (ph_...), which we use as the distinct_id for this event.
2.
A week later, that same person creates an account and is assigned a permanent member_id.
3.
We now need to link the "Complete Order" event from step 1 to this new member_id's history. Storing the ph_... hash as a user property on their new profile doesn't seem to merge the past event's history into their timeline.
Given this, isn't sending a targeted merge event (with $device_id = ph_... and $user_id = member_id) the only practical way to retroactively connect that specific server-side event to the user's canonical profile? If there's a better way to solve this exact use case, we would be very grateful to learn it.
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
You are correct in your understanding: in the Simplified ID Merge system, the only way to retroactively link past server-side anonymous events (tracked with a unique identifier like your ph_... hash) to a newly identified user (member_id) is to send an event that includes both the anonymous identifier (as $device_id) and the new user identifier (as $user_id). This triggers Mixpanel to merge the two IDs into a single identity cluster, and all events previously associated with the $device_id (ph_...) will be attributed to the $user_id (member_id) moving forward Understanding Simplified ID Merge.Key points from the documentation:Why user properties alone are not sufficient: Storing the ph_... hash as a user property on the profile does not merge the event histories. User properties are metadata for querying and segmentation, but do not affect the underlying identity cluster or event attribution Identifying Users (Simplified) FAQ.Your approach is valid: Sending a targeted event (from client or server) with both $device_id = ph_... and $user_id = member_id is the correct and recommended way to merge the histories in this scenario. This will retroactively associate all events tracked with ph_... as the distinct_id to the new member_id profile.No better alternative is documented: The knowledge sources do not describe any alternative method for retroactively merging server-side anonymous events with a newly identified user in the Simplified ID Merge system. Your approach aligns with Mixpanel’s documented best practices for this use case.Summary: Yes, sending a merge-triggering event with both $device_id (ph_...) and $user_id (member_id) is the correct and only documented way to retroactively link those histories in Mixpanel’s Simplified ID Merge system. This is the intended mechanism for your scenario.
If you have further requirements (such as supporting multiple user IDs per user), note that Simplified ID Merge does not support this, and you would need to consider the Original ID Merge API for more complex identity management Considerations when Migrating.
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.
Eliott C.
·
·
kapa.ai That confirms our server-side logic is sound. To be perfectly clear about our client-side implementation: we are not altering the SDK's default $device_id for general events like page views or clicks. Those events correctly use the browser's anonymous ID managed by your SDK. Our custom "Request ID Merge" event is an additional, separate action fired only at login. Its sole purpose is to trigger the merge for our server-generated ph_... hash, which the standard identify() call doesn't know about. Given that we are not interfering with the SDK's default device_id management for all other events, can you confirm that this specific, non-disruptive use of a custom merge event on the client is also considered a safe and valid practice?
kapa.ai
APP
·
·
Let me check the knowledge base for you again. One moment! 📚
kapa.ai
APP
·
·
Yes, based on the documentation, your approach is considered safe and valid for the scenario you described.As long as you are not altering the SDK’s default $device_id for general client-side events (such as page views or clicks), and are only firing a single, custom “Request ID Merge” event at login—with $user_id set to the logged-in user’s ID and $device_id set to your server-generated ph_... hash—this will not interfere with the SDK’s normal device ID management. This targeted event will simply trigger the merge between the server-side anonymous identifier and the user’s canonical profile, as intended by the Simplified ID Merge system.The documentation explicitly states that including both $device_id and $user_id in an event is the mechanism for merging identities, and it is valid to use a custom $device_id for this purpose, provided it is unique and only used for this merge action. This approach is supported and does not disrupt the SDK’s handling of browser-based anonymous IDs for other events Understanding Simplified ID Merge.> “As soon as the user is identified (i.e. logged in), the events should include both $device_id (user’s Anonymous ID) and $user_id (user’s User ID) properties. A single instance of such event is adequate to trigger identity merging which merges [the anonymous ID] and [the user ID].”
— Understanding Simplified ID MergeThere are no warnings in the documentation against this specific, non-disruptive use of a custom merge event, as long as you do not use the custom $device_id for other client-side events.In summary:
Your client-side implementation, as described, is a safe and valid practice for triggering a merge between a server-side anonymous identifier and a user’s profile in Mixpanel’s Simplified ID Merge system.
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.