# Accounts & Identity

What to know about sign-up, WHMCS linking, and profile updates.

## New Sign-Up Flow

- Input required: email, password, name, phone, full billing address, and Customer Number (from Salesforce).
- Salesforce check: we look up the Customer Number; if it already has a portal/WHMCS link, we stop and tell the user to log in.
- WHMCS account creation: we create a WHMCS client using the provided contact + address details. Required fields include first/last name, email, phone, address1, city, state, postcode, and country. Optional custom fields we set when provided:
  - Customer Number (custom field ID 198 by default)
  - Date of Birth
  - Gender
  - Nationality
- Portal records: we store a portal user (password hashed with Argon2) and an `id_mapping` row linking the portal user, WHMCS client ID, and Salesforce account ID.
- Salesforce flags: after creation we set the portal status on the Salesforce Account (status = Active, source = New Signup) and write the WHMCS Account ID back to Salesforce.
- Address ownership: WHMCS is the billing system of record. The address entered at sign-up becomes the WHMCS address used for invoices and checks.

### If something goes wrong

- Customer Number not found or already mapped: we stop the flow and tell the user to log in instead.
- WHMCS already has this email: we ask the user to link instead of creating a duplicate.
- WHMCS creation fails: we show a clear “failed to create billing account” message; nothing is committed in the portal.
- Database write fails after WHMCS creation: we mark the WHMCS client as Inactive for cleanup and ask support to review.

## Linking an Existing WHMCS User

- For users who already have a WHMCS account with this email:
  - We validate their WHMCS login.
  - We read the Customer Number from WHMCS custom field 198 (label “Customer Number”) and find the matching Salesforce Account.
  - We create a portal user (no password yet) and an `id_mapping` with WHMCS + Salesforce IDs.
  - We set Salesforce portal flags (status = Active, source = Migrated) and prompt the user to set a new portal password.
- Duplicate protection: if the WHMCS client or Salesforce account is already mapped to a portal user, we ask the user to log in instead of linking again.

### If something goes wrong

- Invalid WHMCS credentials: we return “Invalid email or password.”
- WHMCS account not found: we return “No billing account found with this email.”
- Salesforce Customer Number missing in WHMCS: we tell the user to contact support (cannot link without it).
- Salesforce account lookup fails: we show a generic “unable to verify customer info” message and stop.

## Profile & Address Updates

- Address and profile edits in the portal are written directly to WHMCS, and the WHMCS cache for that user is cleared so the change shows up immediately.
- Address is treated as authoritative in WHMCS; Salesforce receives address snapshots only when orders are created (so order records show the address used at checkout).
- Password changes are portal-only; WHMCS credentials are never stored in the portal.