The Pre-Delivery owner area

Once a shopper’s purchase reaches DONE, the app drops them out of the public browse-and-reserve journey and into the Pre-Delivery owner area — a separate owner dashboard for everything that happens between purchase and handover. It is a read-mostly dashboard over the shopper’s owned units: view the units, read the payment schedule and pay installments, sign the contract, hold owner (access) cards, and reach out for help. The CRM stays the source of truth for sale, schedule, and installments — the portal serves a thin local projection for the unit list and cards, and reads the schedule live from crms-middleware on demand.

Two endpoint maps, two prefixes — the split that defines this area

The shopper app ships two endpoint maps in src/api/endpoints.ts. The public journey calls ENDPOINTS (prefix NX__SHOPPER_ENDPOINT_PREFIX). Everything under /pre-delivery/* calls PRE_DELIVERY_ENDPOINTS (prefix NX__PRE_DELIVERY_ENDPOINT_PREFIX), rendered inside a separate PreDeliveryLayout. Both hit the same base host and the same routes/api/shopper.php file — the two prefixes are a frontend layout split, not two backends. A pre-delivery screen wired to the wrong prefix 404s. The app-level screen tour is on the Shopper app deep-dive; this page follows the owner actions through the backend.

The three outbound owner actions — buying add-ons, referring a buyer / requesting resale, and raising a service request — each have their own flow page and are not re-documented here:

Buying a unit add-onThe post-purchase, card-only add-on purchase from the owned-unit area — the Paymob charge and the CRM submit that only fires after the money moves.

Referrals & resell assistanceThe two owner-initiated CRM-mirrored requests — refer a buyer (rides the leads endpoint) and ask ODH to help resell a unit.

Unit-service requestsRaise one of 14 CR_* service requests against an owned unit — including CR_SignContract, which is how the sign-contract screen actually submits.

The owner area, end to end

sequenceDiagram
actor OW as Owner (Shopper)
participant SPA as Pre-Delivery SPA
participant API as Backend (Laravel)
participant MW as crms-middleware
participant GW as Gateway (Paymob/Thawani/WSPG)
Note over OW,MW: Sale reaches DONE — the owner enters the Pre-Delivery area
OW->>SPA: Open My Units
SPA->>API: GET user/units (authed)
API-->>SPA: owned units (local DONE projection)
OW->>SPA: Open a unit then its payment schedule
SPA->>API: GET sales/{saleSourceId}/installments
API->>MW: GET /sales/{id}/installments (country header)
MW-->>API: raw installment schedule
API-->>SPA: per-country mapped installments
OW->>SPA: Pay an installment
SPA->>GW: shared online-payment pipeline (see linked flow)
OW->>SPA: Sign the contract
SPA->>API: POST units/{unit}/customer-requests (CR_SignContract)
API->>MW: POST /customer-requests

Entering the Pre-Delivery area and the read-mostly owner actions

Everything in this diagram sits inside the auth:sanctum + ability:ACCESS_SHOPPER_API group in routes/api/shopper.php:93-96 — the owner is always a logged-in Shopper, so unlike the token-optional referral path there are no owner-less rows here.

The key owner actions

1. List owned units — GET user/units → UserController@getUnits (app/Http/Controllers/Api/Shopper/UserController.php:57, route routes/api/shopper.php:128). This is a local projection, not a CRM call: it plucks unit_id from UnitSale rows where user_id = shopper, status = DONE, and crm_status is neither canceled nor draft, then loads those Units with images, unitType, project.destination.country, and projectPhase. A unit only appears once its sale finished the buy state machine — a mid-flight DRAFT/PENDING_INFO sale is invisible in the owner area.

2. Open one owned unit — GET user/units/{publishedUnitShopper} → UserController@getUnitDetails (UserController.php:76, route routes/api/shopper.php:129). This route carries the ownership middleware (OwnershipForUser), which runs IsUnitOwner (app/Actions/Unit/IsUnitOwner.php) — the same DONE + not-canceled/draft UnitSale existence check — and 404s if the logged-in shopper does not own that unit. The detail response eager-loads constructionUpdates.images, addons.images, and accessCard.images so the unit page can surface progress, purchasable add-ons, and the owner card in one payload.

3. Read the payment schedule — GET sales/{saleSourceId}/installments → SalesController@getInstallments (app/Http/Controllers/Api/Shopper/SalesController.php:12, route routes/api/shopper.php:121). This is a live CRM read: GetSaleInstallments (app/Actions/Sale/GetSaleInstallments.php) calls GET {crms-middleware}/sales/{saleSourceId}/installments with a country header, then runs a per-country mapper — EgyptInstallmentMapper, OmanInstallmentMapper, or MontenegroInstallmentMapper. The request requires a country_slug query param that must exist as a published country (InstallmentRequest, app/Http/Requests/Unit/InstallmentRequest.php) — the slug both routes the call to the right CRM and selects the mapper. A slow schedule is a slow CRM, not a slow database.

4. Pay an installment — installment payment reuses the shared online-payment pipeline (the same Paymob / Thawani / WSPG gateway-by-country, the polymorphic Transaction ledger, and the success callback documented on the online payment pipeline page) rather than a bespoke installment rail. Note the sharp edge: the only card-payment route on a sale, POST units/{publishedUnitShopper}/{salePayment}/payment (routes/api/shopper.php:107), binds {salePayment} DRAFT-only — UnitSale filtered crm_status = DRAFT and status = DRAFT (app/Providers/RouteServiceProvider.php:76). That binding exists for the reservation charge, so a DONE sale cannot re-enter it — see Gotchas for what this means for owner-side installment collection.

5. Sign the contract — the /pre-delivery/sign-contract/:unitId screen does not re-run the reservation-form signing from the buy flow. It submits a unit-service request with service code CR_SignContract (app/Enums/UnitServiceRequestCodeEnum.php:22) via POST units/{publishedUnitShopper}/customer-requests → CustomerRequestController@submitUnitService (CustomerRequestController.php:32, route routes/api/shopper.php:136-139), carrying the contract-specific fields sign_contract_place, sign_contract_requested_option, and sign_contract_visit_date_and_time (app/Http/Requests/CustomerRequest/SubmitUnitServiceRequest.php:20-26). sign_contract_requested_option is a ContractRequestedOption — 1 = SIGN_ONLINE, 2 = SIGN_OFFLINE, 3 = REQUEST_DELIVARY (the enum name is misspelled in source). The full CR_* mechanics — the slug-to-service_code mapping and the 200-only local mirror — live on the unit-service requests page.

6. Owner cards — GET user/cards → UserController@getAccessCards (UserController.php:49, route routes/api/shopper.php:123) returns the shopper’s accessCards (Shopper::accessCards HasMany, app/Models/Shopper.php:60) with images, shaped by AccessCardResource into id, cover image, project_name, and destination_name. AccessCard (app/Models/AccessCard.php) is a local, soft-deletable model belongsTo a Shopper and a Unit — an admin-managed membership/access card, not a CRM mirror.

The owner-area endpoints

All of these sit inside the authed shopper group (routes/api/shopper.php:93-96); {p} = the pre-delivery/shopper API surface.

Endpoint	Controller / Action	Source of truth	Notes
GET user/units	UserController@getUnits	local UnitSale projection	owned units, DONE and not canceled/draft
GET user/units/{publishedUnitShopper}	UserController@getUnitDetails	local Unit (+ addons, accessCard)	ownership middleware → IsUnitOwner, else 404
GET sales/{saleSourceId}/installments	SalesController@getInstallments	live CRM	per-country mapper, country_slug required
GET user/cards	UserController@getAccessCards	local AccessCard	admin-managed owner/access cards, not a CRM mirror
GET user/offers	UserController@getOffers	local (mock — TODO)	returns paginated Offer rows, not owner-scoped yet
GET user/news	NewsController@getUserNews	local	real filtered news via GetNewsWithFilters
GET user/referrals	ReferralController@getUserReferrals	local (mock — TODO)	hardcoded referral list, never queries the CRM
GET user/customer-requests	CustomerRequestController@index	live CRM	owner’s submitted service requests, read from the CRM
POST units/{publishedUnitShopper}/customer-requests	CustomerRequestController@submitUnitService	CRM + thin mirror	service requests incl. CR_SignContract
POST units/{publishedUnitShopper}/resell-assistance	CustomerRequestController@submitResellAssistance	CRM + thin mirror	resale request (see referrals flow)
GET issue-types	IssueTypeController@index	local	help topics for the Get-Help screen

Gotchas

The reservation payment route is DRAFT-only — it is not the installment rail

POST units/{publishedUnitShopper}/{salePayment}/payment binds {salePayment} to a UnitSale filtered crm_status = DRAFT and status = DRAFT (app/Providers/RouteServiceProvider.php:76). That is the reservation charge from the buy flow — a DONE sale (every sale an owner sees here) can never bind to it, so this exact route cannot collect a post-purchase installment. Owner installment payment reuses the shared online-payment machinery (gateways + Transaction ledger + callback), not this DRAFT-gated route. When reasoning about an owner’s installment charge, trace it through the online payment pipeline, and don’t expect the reservation payment endpoint to answer for it.

The payment schedule is read-only and country-scoped

GET sales/{saleSourceId}/installments is a live CRM read with no write side (GetSaleInstallments). It requires a country_slug that exists as a published country (InstallmentRequest) — the slug both routes to the correct CRM and picks the Egypt/Oman/Montenegro mapper. A missing or wrong slug means a validation failure or the wrong mapper, not a partial schedule. There is no backend payment-breakdown route — the frontend getUnitPaymentBreakdown (/user/units/{unitId}/payment-breakdown) and getUnitPayments (/user/units/{unitId}/sale) keys in PRE_DELIVERY_ENDPOINTS have no matching backend route and read as drift. The working schedule read is the installments endpoint above.

Signing the contract is a service request, not the reservation form

The sign-contract screen submits CR_SignContract through customer-requests (SubmitUnitServiceRequest.php:20-26) — a CRM-owned unit-service request with a thin local user_requests mirror. It is not the reservation-form PDF signing from the buy flow (that is part of reaching DONE). Don’t confuse “sign the contract” in the owner area with the reservation form — they are different endpoints, different CRM records, and different stages.

Owner cards are local and admin-managed — not from the CRM

AccessCard (app/Models/AccessCard.php) is a plain local model (SoftDeletes, HasImages) tying a Shopper to a Unit; getAccessCards reads it straight off the relation with no CRM call. So an owner whose card is missing is an admin data-entry gap (the card was never created / images never attached), not a CRM sync failure. AccessCardResource exposes only id, cover image, project_name, and destination_name.

Offers and referrals are still mock endpoints

GET user/offers (UserController@getOffers, UserController.php:91) returns paginated Offer rows behind a // TODO to scope offers to the owner’s unit destinations — it is not personalized yet. GET user/referrals (ReferralController@getUserReferrals) returns a hardcoded four-row list and never queries the CRM. Treat both as placeholders — anything they show is canned data, not real owner state.

Get-Help reads real issue types but the submit path is frontend-only

The Get-Help screen loads real help topics from GET issue-types (IssueTypeController@index, routes/api/shopper.php:84). But several PRE_DELIVERY_ENDPOINTS keys the pre-delivery area references — submitAssistanceRequest (/user/assistance-request), changeContactDetailsRequest (/user/change-contact-info), and submitReferral (/user/submit-referral) — have no matching backend route in routes/api/shopper.php and are drift. Where an owner request genuinely lands server-side today, it lands as a customer-requests service request (e.g. CR_ChangeContactDetails, CR_General), not through those keys.

Verified, not guessed

The owned-units DONE projection, the ownership/IsUnitOwner gate, the live per-country installments read, the DRAFT-only salePayment binding, the CR_SignContract sign-contract path, and the local AccessCard model are all traced to current backend code (routes/api/shopper.php, UserController, SalesController, GetSaleInstallments, RouteServiceProvider, IsUnitOwner, AccessCard) and cross-checked against docs-site/_inventory/backend-api.md and frontend-apps.md. The mock offers/referrals and the drift endpoints are read from source.

Where to go next

Shopper buys a unitThe DRAFT→DONE reservation flow that puts a shopper into the owner area in the first place.

The online payment pipelineThe shared gateway + Transaction ledger + callback machinery an owner installment payment reuses.

The Shopper appThe app-level deep-dive — the 17 pre-delivery screens, the PreDeliveryLayout, and the two endpoint maps.

Unit-service requestsThe 14 CR_* codes behind the owner's service and sign-contract requests.