Referrals & resell assistance

Once a shopper has bought a unit they enter the Pre-Delivery owner area — a post-purchase suite that also lets them do two outbound things: refer a buyer to ODH, and request help reselling a unit they own. Both are handled by the shopper app, both go out through crms-middleware to the CRM, and both leave the same kind of local footprint: a row in user_requests (App\Models\UserRequest, app/Models/UserRequest.php:11) tagged with a request_type from UserRequestsEnums. The CRM record is the authoritative one — the portal keeps only a thin analytics mirror.

Both are UserRequest variants — but they take different routes

A referral and a resale request are two of the four UserRequestsEnums values (app/Enums/UserRequestsEnums.php:10-13). They do not share a submit path. A resale request has its own dedicated endpoint (resell-assistance). A referral has no dedicated backend route at all — it is submitted through the shared POST leads endpoint and only becomes a “referral” because the app tags it with portal_page = REFERRAL_PRE_DELIVERY. This is the single most important thing to keep straight on this page.

The whole trip, in one diagram

sequenceDiagram
actor OW as Owner (Shopper)
participant SPA as Pre-Delivery SPA
participant API as Backend (Laravel)
participant MW as crms-middleware
participant CRM as CRM
participant DB as Portal DB
Note over OW,DB: Flow A — Refer a buyer
OW->>SPA: Fill referral form (buyer name, phone, unit, way to share)
SPA->>API: POST leads with portal_page = REFERRAL_PRE_DELIVERY
API->>MW: POST /shopper/leads (is_referral computed)
MW->>CRM: Create lead, flagged is_referral
CRM-->>API: 200
API->>DB: SaveUserRequest → UserRequest request_type = referral
API-->>SPA: 200 mapped response
Note over OW,DB: Flow B — Request resale assistance
OW->>SPA: Fill resell form (asking price, currency)
SPA->>API: POST units resell-assistance (authed)
API->>MW: POST /resell-assistance
MW->>CRM: Create resale request
CRM-->>API: 200
API->>DB: SaveUserRequest → UserRequest request_type = unit_resale
API-->>SPA: 200 mapped response

Referrals and resell — owner submits, CRM records, portal mirrors as UserRequest

The shape is the same for both: submit to the CRM first, then — only on an HTTP 200 — write the local UserRequest mirror. If the CRM call is non-200, no local row is written and the request never shows up in the portal’s analytics or owner views (LeadController.php:42, CustomerRequestController.php:48, :81).

The two flows, step by step

Flow A — Refer a buyer

1. Route. POST leads → LeadController@submitLead (routes/api/shopper.php:86). This route sits outside the auth:sanctum group that starts at routes/api/shopper.php:93 — it is scoped only by user-provider:shoppers (the whole file, :9). So it is token-optional: the controller reads $shopper = Auth::user() and stores user_id => $shopper?->id, null-safe (LeadController.php:29, :46).
2. Validation. SubmitLeadRequest carries the referral fields: referral_unit_name, referral_customer, referral_customer_name, referral_unit_destination, and referral_way_to_share_unit (constrained to ReferralWayToShareUnitEnums), plus a required is_predelivery boolean and an optional portal_page (SubmitLeadRequest.php:37-42).
3. CRM submit. ShopperSubmitNewLead::handle POSTs the prepared payload to {crms-middleware}/shopper/leads with the country header resolved from the destination (ShopperSubmitNewLead.php:16-31). It computes is_referral = referral_customer && referral_unit_name (:41) — this is what marks the lead as a referral CRM-side.
4. Local mirror (on 200 only). request_type starts as LEAD, then is promoted to REFERRAL when portal_page == PortalPages::REFERRAL_PRE_DELIVERY (value 5, app/Enums/PortalPages.php:15; promotion at LeadController.php:48-51). country_code is derived from the phone number (:43-44), UTM fields are stripped (:52-54), and the row is persisted by SaveUserRequest (app/Actions/UserRequest/SaveUserRequest.php:12-21), which also syncs the destination pivot.

“Way to share the referred unit”

referral_way_to_share_unit is validated against ReferralWayToShareUnitEnums (app/Enums/ReferralWayToShareUnitEnums.php:7-12): 1 = RESERVATION_LINK (share a reservation link with the referred buyer) or 2 = CONTACTING_WITH_SALES (let a sales agent reach out). It is optional, so a referral can be submitted without it.

Flow B — Request resale assistance

1. Route. POST units/{publishedUnitShopper}/resell-assistance → CustomerRequestController@submitResellAssistance (routes/api/shopper.php:140-143). Unlike the referral path, this route is inside the auth:sanctum + ability:ACCESS_SHOPPER_API group (:93-96), so the owner must be logged in.
2. Validation. SubmitResellAssistanceRequest accepts only customer_source_id, asking_price, and currency_source_id (SubmitResellAssistanceRequest.php:11-15).
3. CRM submit. SubmitResellAssistance::handle resolves the currency_code from currency_source_id + the unit’s country, then POSTs to {crms-middleware}/resell-assistance with the country header (app/Actions/CustomerRequests/SubmitResellAssistance.php:18-45).
4. Local mirror (on 200 only). formatUserRequestData builds the row with request_type = unit_resale, unit_type_id = unit->unit_type_id, and the unit’s destination_slug for the pivot; SaveUserRequest persists it (CustomerRequestController.php:64-107).

Where the “my referrals” list comes from

The owner’s submitted-referrals list is served by GET user/referrals → ReferralController@getUserReferrals (routes/api/shopper.php:126). Today that endpoint returns hardcoded mock data (four fake referrals with statuses Ongoing / Closed Deal / Folded) behind a // TODO: call CRM to get user referrals — it never queries the CRM (app/Http/Controllers/Api/Shopper/ReferralController.php:12-51). Treat anything it shows as placeholder, not real referral state.

The UserRequest variants

Every one of these lands as a user_requests row (table renamed from lead_requests in database/migrations/2024_09_18_125025_rename_requests_tables.php:19,26-29). The request_type column defaults to lead; service_type is nullable. Only the four values below exist (app/Enums/UserRequestsEnums.php:10-13):

Value	Enum case	How it is created	CRM endpoint
lead	LEAD	POST leads (default request_type)	/shopper/leads
referral	REFERRAL	POST leads with portal_page = REFERRAL_PRE_DELIVERY	/shopper/leads (lead flagged is_referral)
unit_service	UNIT_SERVICE	POST units/{publishedUnitShopper}/customer-requests	/customer-requests
unit_resale	UNIT_RESALE	POST units/{publishedUnitShopper}/resell-assistance	/resell-assistance

The mirror is deliberately thin

UserRequest’s $fillable is only seven columns — user_id, user_type, unit_type_id, request_type, service_type, created_at_dm, country_code (app/Models/UserRequest.php:15-23). Everything else the app sends (buyer name, phone, asking_price, referral_customer, and so on) is dropped by mass-assignment — those fields live only in the CRM. The portal row exists to power the shopper-admin analytics (analytics/user-requests/count, analytics/unit-services/count-per-service-type), not to reconstruct the request.

Gotchas

A referral has no route of its own — it rides the lead endpoint

There is no submit-referral route in the backend. grep-ing every file under routes/ finds exactly two referral/resell lines: GET user/referrals (the mocked list) and the resell-assistance POST. A referral is a POST leads whose portal_page happens to be REFERRAL_PRE_DELIVERY. If a pre-delivery client insists a referral endpoint returns 404, that is expected — check the app is posting to leads, not to a dedicated referral path. (The frontend inventory’s submitReferral → POST /user/submit-referral key in docs-site/_inventory/frontend-apps.md:116 has no matching backend route and looks like drift — the working path is POST leads.)

“referral” locally and “is_referral” in the CRM are decided by different conditions

The local request_type = referral tag keys off portal_page == REFERRAL_PRE_DELIVERY (LeadController.php:48-51). The CRM is_referral flag keys off referral_customer and referral_unit_name being present (ShopperSubmitNewLead.php:41). These are independent conditions, so they can disagree: a submission can be a referral in user_requests while the CRM lead is not is_referral (referral fields omitted), or vice-versa (referral fields present but portal_page unset, so it is stored locally as a plain lead). Don’t assume the two are in sync.

Resell requests always store a null service_type — from an undefined key

formatUserRequestData reads $requestData['service_slug'] for every request type, including resale (CustomerRequestController.php:102). But SubmitResellAssistanceRequest never collects service_slug (SubmitResellAssistanceRequest.php:11-15), so on the resale path that read hits an undefined array key — under PHP 8.2 that emits an Undefined array key "service_slug" warning and evaluates to null. Net effect: unit_resale rows always land with service_type = null (harmless data-wise, but it fills the log with warnings and the key is misleading).

No local row unless the CRM returns 200 — and referral submit is token-optional

Both flows write the local mirror only inside an if (status == 200) guard (LeadController.php:42; CustomerRequestController.php:48, :81). A CRM outage means the owner may still get their response mapped back, but nothing lands in user_requests, so the request is invisible to portal analytics. Separately, because POST leads is outside auth:sanctum (routes/api/shopper.php:86 vs the group at :93), a referral can be submitted without a token and the mirror is saved with user_id = null — so an “orphan” referral row with no owner is possible. Resale requests can’t hit this, they’re inside the authed group.

Small asymmetries between the two rows

The referral path sets country_code from the buyer’s phone number but leaves unit_type_id null (LeadController.php:43-47). The resale path sets unit_type_id from the unit but never sets country_code (CustomerRequestController.php:97-107). So the same user_requests table holds rows with different columns populated depending on which flow produced them — worth remembering when querying or reporting across request_type.

Where to go next

Shopper buys a unitThe purchase that puts a shopper into the Pre-Delivery owner area in the first place.

Broker submits a leadThe other side of the lead pipeline — the same CRM lead endpoint, from the agent apps.

Submitting an EOIAnother CRM-mirrored request flow — agent-initiated, client-paid, with its own local mirror.

Verified, not guessed

Every claim here is traced to a file and line in the current backend (routes/api/shopper.php, LeadController, CustomerRequestController, the two Actions, and the enums) and cross-checked against docs-site/_inventory/data-model.md and backend-api.md. The referral-via-leads mechanism, the mocked user/referrals list, and the service_slug undefined-key quirk are all read from source.