Prerequisites
Before this page: understand account conflict resolution. Merging is the recovery path for one specific conflict — a MergeAccountsConfirmationError.
This page covers only the merging case (MergeAccountsConfirmationError). Linking a credential can fail in other ways — the credential already belongs to an account that can’t be merged, or it’s already in use elsewhere. For the full set of conflicts and how to handle each, see account conflict resolution; use this page for the merge path only. What you’ll build
When a signed-in user adds a credential that already belongs to another mergeable account, verification throws a MergeAccountsConfirmationError. Merging folds that second account into the current one so the user ends up with a single account holding both credentials.
Two cases:
- No conflicts — the accounts don’t disagree on any profile field. You confirm and merge in one call.
- Field-level conflicts — both accounts have a value for the same field (say, a display name). The user picks which value to keep for each field, then you merge.
You’ll build the confirmation UI, the per-field chooser, and the call that completes the merge.
Merging is destructive: the second account is absorbed into the current one. Always confirm with the user before calling mergeUserAccounts — don’t merge automatically on catching the error.
The merge flow
add credential → MergeAccountsConfirmationError → confirm → resolve conflicts (if any) → mergeUserAccounts → merged
mergeConflicts. When it’s undefined there’s nothing to resolve — merge directly. When present, it lists each conflicting field with the value held by fromUser (the account being merged in) and currentUser (the signed-in account).
Completing the merge
import {
MergeAccountsConfirmationError,
mergeUserAccounts,
} from '@dynamic-labs-sdk/client';
import type {
MergeConflicts,
MergeUserConflictResolution,
} from '@dynamic-labs-sdk/client';
// `linkCredential` is your verification call (e.g. verifyOTP or wallet verify).
async function addCredentialWithMerge(linkCredential: () => Promise<void>) {
try {
await linkCredential();
} catch (error) {
if (!(error instanceof MergeAccountsConfirmationError)) throw error;
// confirmMerge is your implementation — show a dialog explaining the two
// accounts will be combined, and resolve to true only if the user agrees.
const confirmed = await confirmMerge();
if (!confirmed) return;
if (!error.mergeConflicts) {
// No field-level conflicts — merge directly.
await mergeUserAccounts();
return;
}
// Ask the user which value to keep for each conflicting field.
const conflictResolutions = await resolveConflicts(error.mergeConflicts);
await mergeUserAccounts({ conflictResolutions });
}
}
// Turn the surfaced conflicts into one resolution per field. `chooseValue` is
// your UI (a radio group, etc.) returning the userId whose value to keep.
async function resolveConflicts(
mergeConflicts: MergeConflicts,
): Promise<MergeUserConflictResolution[]> {
const resolutions: MergeUserConflictResolution[] = [];
for (const conflict of mergeConflicts.conflicts) {
const chosenUserId = await chooseValue({
label: conflict.field.label ?? conflict.field.name,
keepCurrent: conflict.currentUser.value,
keepIncoming: conflict.fromUser.value,
currentUserId: conflict.currentUser.userId,
incomingUserId: conflict.fromUser.userId,
});
resolutions.push({
fieldKey: conflict.field.name,
userId: chosenUserId,
type: conflict.field.type,
});
}
return resolutions;
}
When you catch a MergeAccountsConfirmationError, read error.mergeConflicts: if it’s present, render the ConflictResolver below with it; if it’s undefined, confirm and call merge() with no arguments. The component renders one control per conflict and merges once every field has a decision:import type {
MergeConflicts,
MergeUserConflictResolution,
} from '@dynamic-labs-sdk/client';
import { useMergeUserAccounts } from '@dynamic-labs-sdk/react-hooks';
import { useState } from 'react';
function ConflictResolver({ mergeConflicts }: { mergeConflicts: MergeConflicts }) {
// Track the chosen userId per field key.
const [choices, setChoices] = useState<Record<string, string>>({});
const { mutateAsync: merge, isPending } = useMergeUserAccounts();
const allChosen = mergeConflicts.conflicts.every(
(conflict) => choices[conflict.field.name],
);
const handleMerge = async () => {
const conflictResolutions: MergeUserConflictResolution[] =
mergeConflicts.conflicts.map((conflict) => ({
fieldKey: conflict.field.name,
userId: choices[conflict.field.name],
type: conflict.field.type,
}));
await merge({ conflictResolutions });
};
return (
<form onSubmit={(event) => { event.preventDefault(); handleMerge(); }}>
<h2>Combine your accounts</h2>
{mergeConflicts.conflicts.map((conflict) => {
const field = conflict.field.name;
return (
<fieldset key={field}>
<legend>{conflict.field.label ?? field}</legend>
<label>
<input
type="radio"
name={field}
checked={choices[field] === conflict.currentUser.userId}
onChange={() =>
setChoices((prev) => ({
...prev,
[field]: conflict.currentUser.userId,
}))
}
/>
Keep “{conflict.currentUser.value}”
</label>
<label>
<input
type="radio"
name={field}
checked={choices[field] === conflict.fromUser.userId}
onChange={() =>
setChoices((prev) => ({
...prev,
[field]: conflict.fromUser.userId,
}))
}
/>
Use “{conflict.fromUser.value}”
</label>
</fieldset>
);
})}
<button type="submit" disabled={!allChosen || isPending}>
{isPending ? 'Merging…' : 'Combine accounts'}
</button>
</form>
);
}
merge() (with no arguments) straight from the confirmation dialog. Handling errors
| Situation | What to do |
|---|
MergeAccountsConfirmationError with mergeConflicts === undefined | Confirm, then mergeUserAccounts() with no arguments. |
MergeAccountsConfirmationError with conflicts | Collect one MergeUserConflictResolution per conflict, then mergeUserAccounts({ conflictResolutions }). |
mergeUserAccounts rejects | Keep the user on their current account (the merge didn’t happen) and let them retry or cancel. |
| Missing a resolution for a conflicting field | Don’t call mergeUserAccounts until every conflict has a choice — the backend needs one resolution per field. |
Any other error linking the credential (not MergeAccountsConfirmationError) | This page doesn’t cover it — see account conflict resolution for the full set of link conflicts. |
On success mergeUserAccounts resolves to the merged user and the session updates automatically. Re-render from your auth state (the useUser hook, in the React hooks catalog) rather than the returned value if the rest of your UI already reads from there. See also
