Update a payee's email address

Updates the email address of a payee (contractor). Use this endpoint to correct a payee's email before they have registered, or to merge accounts if the payee is already registered under a different email.

Eligibility Criteria

Before updating a payee's email address, ensure that the following conditions are met:

1. Pending Payee: The payee must have a pending account (User.status is Pending).
2. Single Payer-Payee Relationship: The payee should only be associated with your payer account and have no other clients. This prevents one payer from unilaterally changing the email of a payee who is working with multiple payers.
3. Engagements Enabled: Your payer account must be using engagements (not collaborator groups).

If these conditions are not met, the email change cannot be processed.

Email Update Logic

When you request an email update for a payee, the system follows a specific logic flow based on whether the new email exists in the system and its relationship with your payer account.

Scenarios

1. New Email Does Not Exist in the System

• Current State: The payee has a pending account with an incorrect email.
• Action: The system updates the email on the existing pending account to the new email.
• Outcome: The payee can register using the new email, and all existing engagements and data remain associated with their account.

2. New Email Exists but Is Not Associated with Your Payer Account

• Current State: The new email belongs to an active user in the system, but they are not a payee under your payer account.
• Action:
  • A new payer-payee relationship is created between your payer account and the existing user.
  • Any engagements from the original payee are transferred to the existing user.
  • Invoices and deductions are moved to the existing user.
  • The original pending payee account is archived.
• Outcome: The existing user now has access to the engagements, invoices, and deductions associated with your payer account.

3. New Email Exists and Is Already Associated with Your Payer Account

• Current State: The new email belongs to an active user who is already a payee under your payer account.
• Action:
  • Any engagements from the original pending payee that do not exist under the existing payee are created under the existing payee.
  • Invoices and deductions are moved to the existing payee.
  • The original pending payee account is archived.
• Outcome: The existing payee now has all the engagements, invoices, and deductions from both accounts consolidated.

Detailed Process

When an email update is initiated, the system performs the following steps based on the scenario:

1. Check for Existing User with New Email:

   • If the new email does not exist:
     • Update the email on the pending payee's account to the new email.
   • If the new email exists:
     • Identify the existing user (target payee).

2. Handle Payer-Payee Relationship:

   • If the target payee is not associated with your payer account:
     • Create a new payer-payee relationship between your payer account and the target payee.
   • If the target payee is already associated with your payer account:
     • Proceed to merge data.

3. Transfer or Merge Engagements:

   • For each engagement associated with the original pending payee:
     • If the engagement does not exist under the target payee, create it.
     • This ensures that any pending requirements on invoices are preserved.

4. Transfer Invoices and Deductions:

   • Move all invoices and deductions from the original pending payee to the target payee.
   • Link them to the appropriate engagements under the target payee.

5. Archive Original Payee and Engagements:

   • The original pending payee and their engagements are archived to prevent confusion and maintain data integrity.

6. Payout Pending Invoices:

   • If the target payee is eligible (e.g., has completed all necessary onboarding steps) on the relevant engagements, any pending invoices are paid out accordingly.

Important Notes

• Irreversible Action: Once an email update is processed, it cannot be undone. Ensure that the new email is correct before initiating the update.
• Notifications: The payee may receive notifications about new engagements or invoices after the email update, especially if they are already registered under the new email.