# Listing partner suspension and removal

Use one `status` field for the entire request/listing lifecycle.

## Status values

| status | Meaning |
| --- | --- |
| pending | Awaiting affiliate approval |
| approved | Approved and neither side has suspended it |
| denied | Affiliate declined the request; reason required |
| owner_suspended | Owner paused the approved listing |
| affiliate_suspended | Affiliate paused the approved listing |
| both_suspended | Both sides independently paused the listing |
| withdrawn | Owner withdrew a pending request or removed the listing |
| removed | Affiliate removed a previously approved listing |

Only `approved` qualifies for public affiliate listing reads and new attributed
checkout, subject to existing active inventory and API-key permissions. Owner
booking websites, other affiliates, existing reservations and accepted payments
are unaffected. Suspension preserves approval; removal requires a fresh owner
request and affiliate approval. History and ratings are retained.

## Routes and payloads

- Add `PATCH /api/properties/{propertyId}/listing-requests/{requestId}` for the
  current owner.
- Extend existing `PATCH /api/affiliates/listing-requests/{requestId}` for the
  intended affiliate.
- Every mutation uses `{"status":"<target status>"}`. Existing denial also
  requires `reason`. No `suspended`, `ownerSuspended`, or `affiliateSuspended`
  boolean fields are added to requests or responses.
- Existing GET request endpoints return the same request shape, with the expanded
  status enum. Status filtering accepts these values.
- Affiliate management GET `/api/affiliates/listings` gains `requestId` and
  `status`; it retains suspended entries so affiliates can resume them. Public
  travel listing payloads do not gain management fields.

The server validates both current state and acting role while holding the existing
property/affiliate mutation guard:

| Actor/action | Current status | Target status |
| --- | --- | --- |
| Affiliate approves | pending | approved |
| Affiliate denies | pending | denied (reason required) |
| Owner suspends | approved | owner_suspended |
| Owner suspends | affiliate_suspended | both_suspended |
| Affiliate suspends | approved | affiliate_suspended |
| Affiliate suspends | owner_suspended | both_suspended |
| Owner resumes | owner_suspended | approved |
| Owner resumes | both_suspended | affiliate_suspended |
| Affiliate resumes | affiliate_suspended | approved |
| Affiliate resumes | both_suspended | owner_suspended |
| Owner removes/withdraws | pending or any approved/suspended state | withdrawn |
| Affiliate removes | any approved/suspended state | removed |

Neither side can clear the other's suspension. A stale target that would do so
returns 409 and the UI reloads the current status. Identical authorized retries
are idempotent. Old withdrawn/removed request IDs cannot affect new requests.
Both parties can stop a listing even when inventory is inactive or sold out.
Only verified signed-in sessions may manage requests; API-key privileges do not
expand. Foreign IDs return 404, invalid payloads 422, invalid transitions 409.
Responses remain private/no-store.

Example owner suspension:

```sh
curl --fail-with-body --request PATCH \
  "$WIKIUP_API_ORIGIN/api/properties/property_example/listing-requests/request_example" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"status":"owner_suspended"}'
```

HTTP 200, illustrative response:

```json
{
  "request": {
    "id": "request_example",
    "propertyId": "property_example",
    "propertyName": "Example Hotel",
    "affiliateId": "affiliate_example",
    "affiliateName": "Example Listing Partner",
    "affiliateWebsite": "https://partner.example.com",
    "status": "owner_suspended",
    "reason": null,
    "submittedAt": "2026-11-14T16:00:00-08:00",
    "decidedAt": "2026-11-14T16:30:00-08:00",
    "timeZone": "America/Los_Angeles"
  }
}
```

`decidedAt` retains its approval/denial meaning. No new audit timestamps.

## UI and verification

Owner Listing Partners and affiliate Listings/review expose Suspend, Resume and
Remove listing as applicable. Use the existing confirmation dialog for removal.
Show which party has paused the listing. Retain stopped entries in management
views; exclude them before pagination in public catalog/search. Recheck direct
property/room content, availability, and previously issued referral links at new
checkout authorization. An already loaded third-party page cannot be retracted;
subsequent API reads and new checkout enforce the state.

Preserve existing email deduplication. Withdrawal/removal must not produce a
mislabelled approval/denial email; suppress obsolete queued approval notices.
New lifecycle email types are not proposed.

Test all transitions, role isolation, conflicting updates, idempotent retries,
Onyx nullable readback, compatibility migration, resubmission, pagination,
checkout enforcement and unchanged existing reservations. Verify controls in
light/dark and desktop/mobile using isolated fixtures and mocked email.

Release status: implemented locally; not yet deployed.
