adds an apporpriate warning for migration in account linking docs

v2/thirdparty/common-customizations/account-linking/automatic-account-linking.mdx

@@ -98,6 +98,19 @@ Coming Soon
 
 You can use the input of the function to dynamically decide if you want to do account linking for a particular user and / or login method or not.
 
+:::caution
+If enabling automatic account linking for **an existing user base**, then before you enable it, you need to mark existing users as primary users so that future sign ups / ins with the same email / phone, but with a different login method, get linked to the existing user (as opposed to the other way around).
+
+To do this, you should create a script that:
+- [Loops through all users](../user-pagination) in your app (oldest first).
+- For each user, fetch the user's ID and call the [create primary user](./manual-account-linking#creating-a-primary-user) function on them.
+    - If at any point, you find that primary user creation failed because of `ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR` error, then it means that there is already another user with the same email / phone number that is already a primary user. In this case, you don't need to take any action for the current user (that failed) since they will be auto linked to the existing user when they sign in next with this method. As a side effect of this, their primary user ID will change when their account will be linked. To do any data migration at this point, see [this section on this page](#migration-of-user-data-when-accounts-are-linked).
+    - If you have two users with the same email / phone number, you can even pick which one of them will become a primary user based on your own logic. For example, instead of just making the oldest user the primary user, you can choose the one that has more activity on your app.
+- You can also do the above via [direct API calls to the core](https://app.swaggerhub.com/apis/supertokens/CDI).
+- When looping through users, and if you are using our managed service, make sure to add artificial delay in the loop to not breach [our rate limits](../../rate-limits). In case the API call or function calls throws an error with a `429`, please wait for a few seconds and then retry the call.
+- In order to be able to do this, you will first need to enable account linking feature in the SuperTokens core. For self hosted core, you can get a license key by [signing up](https://supertokens.com/auth), and for managed service users, you can enable the feature [from the dashboard](https://supertokens.com/dashboard-saas).
+:::
+
 ## Different scenarios of automatic account linking
 
 - **During sign up**: If there exists another account with the same email or phone number within the current tenant, the new account will be linked to the existing account if:
@@ -185,7 +198,7 @@ To prevent this scenario, you should:
     ```
 
 :::caution
-If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. 
+If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. However, the end user would see an error on the UI as the API would return a `500` status code. They can retry the login action and will be logged into the primary user's account as expected. 
 :::
 
 ## Support status codes

v2/thirdpartyemailpassword/common-customizations/account-linking/automatic-account-linking.mdx

@@ -98,6 +98,19 @@ Coming Soon
 
 You can use the input of the function to dynamically decide if you want to do account linking for a particular user and / or login method or not.
 
+:::caution
+If enabling automatic account linking for **an existing user base**, then before you enable it, you need to mark existing users as primary users so that future sign ups / ins with the same email / phone, but with a different login method, get linked to the existing user (as opposed to the other way around).
+
+To do this, you should create a script that:
+- [Loops through all users](../user-pagination) in your app (oldest first).
+- For each user, fetch the user's ID and call the [create primary user](./manual-account-linking#creating-a-primary-user) function on them.
+    - If at any point, you find that primary user creation failed because of `ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR` error, then it means that there is already another user with the same email / phone number that is already a primary user. In this case, you don't need to take any action for the current user (that failed) since they will be auto linked to the existing user when they sign in next with this method. As a side effect of this, their primary user ID will change when their account will be linked. To do any data migration at this point, see [this section on this page](#migration-of-user-data-when-accounts-are-linked).
+    - If you have two users with the same email / phone number, you can even pick which one of them will become a primary user based on your own logic. For example, instead of just making the oldest user the primary user, you can choose the one that has more activity on your app.
+- You can also do the above via [direct API calls to the core](https://app.swaggerhub.com/apis/supertokens/CDI).
+- When looping through users, and if you are using our managed service, make sure to add artificial delay in the loop to not breach [our rate limits](../../rate-limits). In case the API call or function calls throws an error with a `429`, please wait for a few seconds and then retry the call.
+- In order to be able to do this, you will first need to enable account linking feature in the SuperTokens core. For self hosted core, you can get a license key by [signing up](https://supertokens.com/auth), and for managed service users, you can enable the feature [from the dashboard](https://supertokens.com/dashboard-saas).
+:::
+
 ## Different scenarios of automatic account linking
 
 - **During sign up**: If there exists another account with the same email or phone number within the current tenant, the new account will be linked to the existing account if:
@@ -185,7 +198,7 @@ To prevent this scenario, you should:
     ```
 
 :::caution
-If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. 
+If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. However, the end user would see an error on the UI as the API would return a `500` status code. They can retry the login action and will be logged into the primary user's account as expected. 
 :::
 
 ## Support status codes

v2/thirdpartypasswordless/common-customizations/account-linking/automatic-account-linking.mdx

@@ -98,6 +98,19 @@ Coming Soon
 
 You can use the input of the function to dynamically decide if you want to do account linking for a particular user and / or login method or not.
 
+:::caution
+If enabling automatic account linking for **an existing user base**, then before you enable it, you need to mark existing users as primary users so that future sign ups / ins with the same email / phone, but with a different login method, get linked to the existing user (as opposed to the other way around).
+
+To do this, you should create a script that:
+- [Loops through all users](../user-pagination) in your app (oldest first).
+- For each user, fetch the user's ID and call the [create primary user](./manual-account-linking#creating-a-primary-user) function on them.
+    - If at any point, you find that primary user creation failed because of `ACCOUNT_INFO_ALREADY_ASSOCIATED_WITH_ANOTHER_PRIMARY_USER_ID_ERROR` error, then it means that there is already another user with the same email / phone number that is already a primary user. In this case, you don't need to take any action for the current user (that failed) since they will be auto linked to the existing user when they sign in next with this method. As a side effect of this, their primary user ID will change when their account will be linked. To do any data migration at this point, see [this section on this page](#migration-of-user-data-when-accounts-are-linked).
+    - If you have two users with the same email / phone number, you can even pick which one of them will become a primary user based on your own logic. For example, instead of just making the oldest user the primary user, you can choose the one that has more activity on your app.
+- You can also do the above via [direct API calls to the core](https://app.swaggerhub.com/apis/supertokens/CDI).
+- When looping through users, and if you are using our managed service, make sure to add artificial delay in the loop to not breach [our rate limits](../../rate-limits). In case the API call or function calls throws an error with a `429`, please wait for a few seconds and then retry the call.
+- In order to be able to do this, you will first need to enable account linking feature in the SuperTokens core. For self hosted core, you can get a license key by [signing up](https://supertokens.com/auth), and for managed service users, you can enable the feature [from the dashboard](https://supertokens.com/dashboard-saas).
+:::
+
 ## Different scenarios of automatic account linking
 
 - **During sign up**: If there exists another account with the same email or phone number within the current tenant, the new account will be linked to the existing account if:
@@ -185,7 +198,7 @@ To prevent this scenario, you should:
     ```
 
 :::caution
-If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. 
+If your logic in `onAccountLinked` throws an error, then it will not be called again, and will still have resulted in the accounts being linked. However, the end user would see an error on the UI as the API would return a `500` status code. They can retry the login action and will be logged into the primary user's account as expected. 
 :::
 
 ## Support status codes