# Listing partner requests and reviews

Deployment requirements: the target database must include `AffiliateListingRequest`, and both API and console must run this release. Scheduled notification retries require `LISTING_REQUEST_EMAILS_ENABLED=true`. Verify the target revision using `/api/version`; publication of this guide alone is not deployment evidence.

## Experience

Replace Property → Travel and Publish on WikiupTravel with **Listing Partners**.
Owners see active affiliate names and website links, can visit each website,
request a listing, and track Pending, Approved or Denied. Denied requests show
the reason. Only a current property owner may submit a request.

Affiliates gain a Requests view in the existing portal. Opening a request shows
that property's public listing information, address, contact and photos. It grants
no access to reservations, guests, private notes, access codes or owner settings.
Approve or Deny uses the existing application dialogs. Deny requires a reason.
The review link requires sign-in and checks the intended affiliate account.

A request covers a property and its eligible bookable inventory, including hotels,
inns and vacation rentals. Hosts who are also affiliates retain both roles.
Approval and the existing visibility switch are separate: approval permits listing;
the affiliate can still hide an approved property. Ratings and commissions remain
in their existing flows.

## Approved REST API

These routes require a verified user session, not a partner API key. Existing
server-side affiliate APIs remain the consumer interface for listing websites.

| Method and resource | Purpose and access | Success |
| --- | --- | --- |
| GET /api/listing-partners | Signed-in property owners browse active affiliates; page/pageSize | 200 `{partners, meta}` |
| GET /api/properties/{propertyId}/listing-requests | Current owner tracks that property's requests; page/pageSize | 200 `{requests, meta}` |
| POST /api/properties/{propertyId}/listing-requests | Current owner submits `{affiliateId}` | 201 `{request}`; repeated pending submission returns the same request with 200 |
| GET /api/affiliates/listing-requests | Active affiliate sees only requests addressed to itself; optional status, page/pageSize | 200 `{requests, meta}` |
| GET /api/affiliates/listing-requests/{requestId} | Intended affiliate reviews the request and requesting property's public details | 200 `{request, property}` |
| PATCH /api/affiliates/listing-requests/{requestId} | Intended affiliate decides a pending request | 200 `{request}` |

All lists default to 12 entries; maximum 50. Pagination explicitly returns page,
pageSize and nextPage. All responses are private/no-store. Foreign request IDs
return 404. Invalid inputs return 422; a conflicting decision returns 409.

Partner directory entry:

```json
{
  "id": "affiliate_example",
  "name": "Example Listing Partner",
  "website": "https://partner.example.com"
}
```

Submit (illustrative IDs):

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

Request object, shared by owner and affiliate views:

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

- `id`, `propertyId`, `affiliateId`: opaque stable identifiers.
- Names and website: display fields from the linked records, not account secrets.
- `status`: pending, approved, denied, owner_suspended, affiliate_suspended, both_suspended, withdrawn or removed.
- `reason`: required trimmed text for denial (1–2000 characters); null otherwise.
- Timestamps: rendered in the property's timezone with the numeric offset.
- `timeZone`: property's IANA timezone.
- Review `property`: reuse the existing public listing detail field definitions;
  no private Property entity or membership serialization.

Approve:

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

Deny:

```sh
curl --fail-with-body --request PATCH \
  "$WIKIUP_API_ORIGIN/api/affiliates/listing-requests/request_example" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"status":"denied","reason":"This property is outside our coverage area."}'
```

Repeated identical decisions are safe; opposite decisions on a completed request
return 409. An owner may submit a new request after denial; the previous decision
and reason remain readable. Duplicate pending or already approved requests do not
create another review or another submission email.

## Listing visibility change — approved

For relationships governed by this workflow, only approved properties may appear
through that affiliate's catalog, direct content, room details, availability and
new booking links. Pending and denied requests do not qualify. Apply the existing
suspension and active-inventory rules as well. Do not alter completed reservations,
existing commission attribution or the owner's own booking website.

All existing listings require approval. No relationships are grandfathered or automatically approved.

## Email delivery

Reuse the existing Mailjet system sender, `no-reply@wikiup.app`, and Wikiup branded
HTML plus plain text. No new mail provider or domain setup is proposed.

- Submission: affiliate receives the property name and a signed-in review link.
- Submission: requesting owner receives confirmation and a tracking link.
- Decision: requesting owner receives Approved or Denied; denial includes reason.

Persist the request/decision before attempting notification. Retain notification
work for retries and prevent repeated submissions from creating duplicate messages.
An email failure must not erase a request or reverse approval. Treat provider
acceptance as submission, not proof of inbox delivery. Review URLs must target the
matching preview/production console and perform no approval just by opening them.

## Directory, history and review requests

Use session tokens for the review workflow; the partner's server API key remains
for the existing travel catalog, room details, availability and checkout links.

```sh
curl --fail-with-body "$WIKIUP_API_ORIGIN/api/listing-partners?page=1&pageSize=12" \
  -H "Authorization: Bearer $SESSION_TOKEN"
curl --fail-with-body "$WIKIUP_API_ORIGIN/api/properties/property_example/listing-requests?page=1" \
  -H "Authorization: Bearer $SESSION_TOKEN"
curl --fail-with-body "$WIKIUP_API_ORIGIN/api/affiliates/listing-requests?status=pending&page=1" \
  -H "Authorization: Bearer $SESSION_TOKEN"
curl --fail-with-body "$WIKIUP_API_ORIGIN/api/affiliates/listing-requests/request_example" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

Directory response (illustrative records):

```json
{"partners":[{"id":"affiliate_example","name":"Example Travel Guide","website":"https://partner.example.com"}],"meta":{"page":1,"pageSize":12,"nextPage":null}}
```

The history routes return `requests: [<request object above>]` and the same `meta`.
They are sorted newest submission first. Only the affiliate history accepts a
`status` filter. Pagination defaults to 12 and permits 1–50; `page` is 1–1000.
Unknown query/body fields are rejected. No request contains owner UID, email retry
state, account secrets, guest data or membership information.

Review response adds `property` to the request envelope:

```json
{
  "property": {
    "propertyId": "property_example",
    "name": "Example Hotel",
    "description": "A small mountain hotel with a courtyard.",
    "stayType": "inn",
    "tagLine": "Mountain stays with a courtyard",
    "address": {"line1":"100 Example Lane","line2":null,"city":"Julian","state":"CA","postalCode":"92036","country":"United States"},
    "contact": {"phone":"+1 555 010 0100","email":"host@example.com","websiteUrl":"https://hotel.example.com/"},
    "mapLocation": null,
    "timeZone": "America/Los_Angeles",
    "coverImage": {
      "id":"photo_example",
      "url":"https://api-preview.wikiup.app/api/web-assets/properties/property_example/gallery/courtyard.jpg",
      "alt":"Example hotel courtyard","width":1600,"height":900,"variants":[],"group":null
    },
    "gallery": [{
      "id":"photo_example",
      "url":"https://api-preview.wikiup.app/api/web-assets/properties/property_example/gallery/courtyard.jpg",
      "alt":"Example hotel courtyard","width":1600,"height":900,"variants":[],"group":null
    }]
  }
}
```

These are synthetic documentation values. `property` is a public projection,
not an owner entity or a date availability quote. It remains reviewable when rooms
are paused; approving a property without active inventory returns 409.
Every nested field, null meaning and photo shape is defined in
[request response schemas](listing-partner-requests.schema.json), and shown in
the [Affiliates endpoint reference](/#affiliates). Missing locations remain null;
no coordinates are guessed. Stored HTML descriptions must be safely rendered as
rich text or displayed as text, never executed.

## Errors and retries

- 401: missing/invalid sign-in.
- 403: unverified email, API key, non-owner or inactive affiliate.
- 404: missing or foreign request; no requesting property details are returned.
- 409: conflicting decision, concurrent modification or inactive inventory.
- 422: invalid fields; `{error, details:[{field,message}]}`.
- 429: at most five new requests per property/affiliate in 24 hours. Repeating an
  existing pending/approved submission does not create a new request.
- 503: storage/provider failure. Retain the user's input and offer retry.

An old signed affiliate booking link cannot start a new attributed checkout for
an unapproved property. Existing accepted payment snapshots, reservations and
commission reports remain unchanged. Owner booking sites and legacy search-only
keys retain their existing access rules.

## Deployment and email setup

1. Publish the reviewed full schema to the target environment before the API:
   `AffiliateListingRequest` is additive. Production still requires approval.
2. Deploy API and console together. No automatic approvals are created. Owners
   must submit requests and affiliates must review them before inventory appears.
3. Use the existing Mailjet credentials/system sender in that environment's
   `WIKIUP_API_ENV_FILE` GitHub environment secret. Fixed console links use
   `NEXT_PUBLIC_APP_ENV=preview` or `production`, never a request host.
4. API requests persist notification work before trying delivery. Successful
   messages use stable per-request/per-message Mailjet deduplication IDs.
   Failures back off from five minutes to a day; one failed recipient does not
   prevent attempting the other. Recipient identity is freshly verified before
   sending; a removed owner is not emailed.
5. The **Listing partner notifications** workflow processes at most ten due
   requests per run. Set repository/org variable `LISTING_REQUEST_EMAILS_ENABLED`
   to `true` after configuring the sender. Its production schedule runs every
   five minutes only after the workflow exists on main. Preview is manual dispatch
   with `environment=preview`; start with `mode=dry-run`, then `apply` when actual
   emails are intended. No workflow or emails were activated by schema approval.
6. Operator equivalent: `node scripts/run-listing-request-notifications.mjs preview --dry-run`
   (or `--apply` to send). It loads only `.env.preview`; production explicitly loads
   `.env.production`. Never substitute environments or print their credentials.

Provider acceptance is not inbox-delivery confirmation. Request status is
independent of email status. Inspect failed workflow runs and queued work rather
than repeatedly resubmitting requests. Database verification and rendered UI
checks are recorded in the repository's implementation report.

## Listing lifecycle

See [suspension and removal](./listing-partner-lifecycle.md) for the single-status owner and affiliate transitions, PATCH requests and response examples. Only `approved` is publicly eligible. Suspended listings remain manageable. Neither side can clear the other’s suspension; removed/withdrawn listings require a new request and approval. Existing reservations are unaffected.
