Step 3 Tell us about your property

Purpose (Product)

This step initializes the property record and captures the core attribute: property type. It is the foundation for tailoring subsequent steps (rooms, address, pricing, amenities) and determines default assumptions and UI branching.

For landlords choosing “Create new property,” this is the first action step after selecting the onboarding path. It either creates a new onboarding property or updates an existing draft if present.

UX Flow (What the user sees)

1

Select property type

  • A grid of selectable cards with icons and labels:

    • House

    • Apartment

    • Studio

    • Hotel

    • Villa

    • Apartment block

  • Selecting a card highlights it.

2

Validate selection

  • Clicking Next validates the selection.

  • If no card is selected, a red validation message appears.

3

Create or update property

  • If valid:

    • If no onboarding property exists, the system creates a new onboarding property.

    • If a draft property exists, the system updates the existing property’s type.

  • On success, the flow advances to the next step (“[[Step 4 - What type of place will guests have]]”).

![[Desktop 2.png]]

System Flow (How it works)

APIs called:

  • POST /api/properties/create-onboarding-property-v2

    • Purpose: Create a new onboarding property.

    • Payload:

{ "userId": "string", "propertyType": "HOUSE" | "APARTMENT" | "STUDIO" | "HOTEL" | "VILLA" | "APARTMENT_BLOCK" }

  • Response: { id: number, ... } (new property)

  • Errors: 400 (validation), 401/403 (auth), 500 (server)

  • Idempotency: Not guaranteed; client only calls when no existing property is detected.

  • PATCH /api/properties/{propertyId}

    • Purpose: Update existing property’s type.

    • Payload:

  • Response: Updated property

  • Errors: 400, 401/403, 404 (not found), 500

  • Idempotency: Safe for same values.

  • PATCH /api/users/{userId}

    • Purpose: Advance onboarding step.

    • Payload:

  • Response: Updated user

  • Errors: 400, 401/403, 404, 500

  • Retries: None automatic; navigation contingent on success.

Flow notes:

  • Client behavior:

    • If a property exists: send PATCH to update propertyDetails.propertyType.

    • If no property exists: send POST with userId and propertyType.

    • After property create/update succeeds: PATCH user to increment onboardingStep by 1.

    • Navigation to the next step should only occur after the user PATCH succeeds.

  • Error handling:

    • If any API call fails (create/update or user PATCH), the user remains on the step and sees appropriate error messaging; no onboardingStep increment or navigation occurs.

QA Checklist

Visual

  • All six property type cards render with correct icons and labels.

  • Selected card styling applies; hover/elevation looks correct.

Behavior

  • Without a selection, clicking Next shows validation error.

  • With a selection:

    • If a property exists, a PATCH is sent with propertyDetails.propertyType.

    • If none exists, a POST creates the property with userId and propertyType.

    • After property create/update, users.onboardingStep increments by 1 via PATCH.

    • Step advances to “What type of place will guests have?”.

Data

  • Verify property record reflects the chosen propertyType.

  • Verify users.onboardingStep increments by 1 only once per successful step.

Negative

  • Simulate API failure: user remains on the step; no step increment; no navigation.

Idempotency

  • Re-submitting the same type updates safely without creating duplicate records.

PreviousStep 2 Onboarding Proeprty SelectionNextStep 4 What type of place will guests have