# Agent handoff: fast area listings, then live availability

**Listing approval:** every property must have an approved request for the authenticated affiliate, including existing listings and the affiliate's own properties. Pending, denied and never-requested properties are excluded. Blacklist and active-inventory rules still apply. See [Listing partner requests](listing-partner-requests.md) for rollout status and onboarding.

Destination IDs are geographically qualified (for example `julian-ca`, `aurora-co`, `aurora-il`, `paris-tx`, `paris-fr`). See [destination IDs, compatibility, and supported areas](travel-destinations.md). This ID update is local and not deployed yet.

Implement progressive loading in the partner's lodging site using the existing server-held, email-associated **affiliate** API key. Date-free catalog and lazy availability are deployed to preview and production. See the [integration handoff’s release status](./hidden-san-diego-integration.md) for the reviewed revision and verification limits. The existing regional availability and single-listing endpoints remain compatible.

## 1. Show listings before choosing dates

```sh
curl --fail-with-body --get "$WIKIUP_API_ORIGIN/api/travel/listings" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  --data-urlencode destination=julian-ca \
  --data-urlencode page=1 --data-urlencode pageSize=12
```

Use `https://api-preview.wikiup.app` for preview. Destination accepts existing destination, parent-region, and county IDs (for example `julian-ca`, `east-county-san-diego-ca`, `san-diego-county-ca`). No dates or party fields are accepted here. No `x-property-id` is needed. Affiliate keys and verified active affiliate sessions may use this catalog GET. Omit destination to browse all approved properties; an empty destination is invalid. Host/resource keys and search-only keys retain their existing access. The batch POST below remains affiliate-key-only.

The response includes `contractVersion: 2`, `query`, `listings`, `failures`, and `meta`. Each card includes:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | Stable `hotel:<propertyId>`, `rental:<propertyId>:room:<optionId>`, or `rental:<propertyId>:pool:<optionId>` ID. |
| `type` | string | hotel or vacation_rental. |
| `propertyId` | string | Stable property ID. |
| `name, propertyName` | string | Public listing and property names. |
| `description` | string or null | Plain-text catalog excerpt, at most 240 characters. |
| `tagLine` | string or null | At most 100 characters. |
| `stayType` | string or null | hotel, inn, bed_and_breakfast, resort, or vacation_rental; null if unknown. |
| `ratings` | optional object | Included only with fetch=ratings. |
| `ratings.starRating, ratings.priceTier` | number or null | Affiliate-managed ratings; null if unset. |
| `location` | string | Public locality label. |
| `mapLocation` | object or null | Exact public position with numeric latitude and longitude; null if unavailable. |
| `timeZone` | string or null | Validated property IANA time zone; null if unknown. |
| `destination` | string or null | Canonical destination ID; null for unknown geography. Unfiltered catalogs retain these listings. |
| `maxGuests` | optional integer or null | Rental capacity, not current availability. |
| `availabilityStatus` | string | Always unchecked in the catalog. |
| `coverImage` | object or null | Public image; same contract as listing detail. |
| `imageStatus` | string | deferred, none, pending, or ready. |

Occupied and date-restricted inventory stays in this catalog. Inactive/ineligible inventory and the affiliate's blacklisted properties do not. No price, stay subtotal, available count or booking link is returned. Never label `unchecked` as available or sold out.

`PublicMapLocation` is documented in [public map locations](listing-locations.md). Plot the returned coordinate pair when non-null. There are no location status or precision fields, and no approximate points. Keep unmapped cards visible and never substitute town centers. Use the property's `timeZone` for displayed timestamps. Check the [rollout evidence](listing-card-rollout-verification.md) for the verified revision.

The fastest default skips reservation, pricing, gallery and photo-storage reads. To retrieve already prepared cover thumbnails, set `includeImages=true`; this does metadata reads but never downloads original photos or creates thumbnails. `pending` means no completed thumbnail is ready; load the existing listing-content endpoint later for the original-image fallback. `none` means no public photo. Do not invent stock photos. For galleries use `GET /api/travel/listings/{id}` and the [photo-group addendum](listing-gallery-groups.md).

Pagination is **by property**, not card: `pageSize` is 1–12 (default 12); one rental property can produce multiple cards. Do not truncate the returned cards to pageSize. `meta.nextPage` is the next page or null. `matchedProperties`, `checkedProperties`, `withdrawnProperties`, `partial`, `pageComplete`, `complete`, and `generatedAt` are explicit. `complete` is true only for a one-page complete search. Accumulate failures across pages; a failed page/property is not an empty area. Catalog scans are bounded; exceeding the bound fails explicitly. A provider with more than 200 catalog cards is reported as a failure rather than silently truncated.

## 2. Check just the visible listings after dates are selected

```sh
curl --fail-with-body "$WIKIUP_API_ORIGIN/api/travel/listings/availability" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"listingIds":["hotel:PROPERTY_ID","rental:OTHER_PROPERTY_ID:room:ROOM_ID"],"checkIn":"2027-02-09","checkOut":"2027-02-12","adults":2,"children":0,"pets":0}'
```

Supply **either** `listingIds` **or** `propertyIds`, with 1–12 unique IDs. Property IDs check all qualifying hotel/rental inventory at those properties; listing IDs restrict results to those exact cards. Never send both arrays. Unknown fields, duplicate IDs, malformed IDs, invalid dates or counts return 422. Maximum body: 8 KiB. Counts accept JSON integers or their decimal strings; defaults and date limits match existing availability (adults 2, children/pets 0, 1–28 nights, up to two years ahead).

Response:

| Field | Type | Meaning |
| --- | --- | --- |
| `query` | object | Validated request criteria. |
| `results` | array of objects | One result per requested ID, in request order. |
| `results[].requestId` | string | Exact requested listing ID or property ID. |
| `results[].propertyId` | string | Property ID. |
| `results[].status` | string | available, sold_out, not_found, or error. |
| `results[].listings` | conditional array | Priced listings for available or sold_out results. |
| `results[].options` | conditional array | Availability options for available or sold_out results. |
| `results[].code` | conditional string | For error: timeout or provider_unavailable. |
| `results[].retryable` | conditional boolean | Always true for error results. |
| `complete` | boolean | False if any requested item failed. |
| `meta.requested` | integer | Number of requested IDs. |
| `meta.checkedProperties` | integer | Number of checked properties. |
| `meta.failedProperties` | integer | Number of failed property checks. |
| `meta.generatedAt` | string | Response generation timestamp. |

Results preserve requested-ID order. Prices and booking links use the existing listing/availability contracts; **images are omitted** from these batch cards/options to avoid photo work. Merge pricing into catalog cards by `id` without replacing their photos. Options retain physical roomId or pooled roomTypeId, capacity, availableCount, currency, nightlyRate, staySubtotal and signed bookingUrl. Taxes, fees and finalTotal remain null until checkout; subtotal is accommodation only. A hotel listing's price is the lowest qualifying stay, not a sum of all rooms.

`sold_out` means no option meets the dates/party/restrictions, not a provider error. `not_found` covers missing, withdrawn, blacklisted, wrong-type or inaccessible IDs without disclosing the cause. A mixed response is HTTP 200; `complete:false` when any item is `error`. Always inspect individual statuses. Whole-request authentication/validation/admission failures use the usual HTTP errors. Do not discard successful items when another property fails.

A property is evaluated only once per batch, even if several of its listing IDs are requested. At most three property checks run concurrently, within a shared 15-second budget. Every batch rechecks current eligibility and the actual booking engine, including reservations, preparation buffers, restrictions, pets, capacity, pools and prices. No completed availability response is cached.

## 3. One listing

The existing endpoint still works:

```sh
curl --silent --show-error --fail-with-body --get \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID/availability" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" \
  --data-urlencode 'checkIn=2027-02-09' \
  --data-urlencode 'checkOut=2027-02-12' \
  --data-urlencode 'adults=2' --data-urlencode 'children=0' --data-urlencode 'pets=0'
```

Set `ENCODED_LISTING_ID` to a returned listing ID encoded once as a URL path segment (for example, `hotel%3APROPERTY_ID`).

For a lighter response without image work, send a one-ID batch instead. Always use the returned bookingUrl unchanged so dates, party and affiliate attribution survive. Opening a link does not book or charge; checkout revalidates.

## Client implementation steps

1. On area selection, fetch catalog page 1 from your server proxy and render cards immediately with unchecked availability. Keep the affiliate key exclusively on the server.
2. On dates/party selection, queue only visible card IDs, deduplicate, and issue a batch of at most 12. Load later batches as cards approach the viewport. Catalog pagination remains independent of availability checks.
3. Give each search an increasing generation ID. Abort superseded browser requests and ignore every late response whose generation/area/dates/party differs from current state. Reset previous prices and availability on criteria changes.
4. Show a small loading state per card, then price/available count, sold out, or retry. Keep sold-out catalog cards visible. Remove inaccessible cards. Do not interpret a failed check as sold out or use an old price.
5. Requests share the affiliate account's existing one-request-per-second admission budget across all keys. Sequence catalog/content/batches and honor 429 `Retry-After` with bounded retries. Do not burst 12 separate requests. Canceling a browser request does not guarantee the server stops an already running read.
6. Disable HTTP client caching and forward the three existing no-store headers. Do not cache completed availability, prices, counts or booking links anywhere. In-flight deduplication must be scoped to affiliate and exact criteria and cleared on settlement. Keep catalog JSON no-store too so withdrawals/blacklists take effect on the next request. Image caching remains the consumer's responsibility.
7. Sorting by current price must wait for availability results. Never claim global cheapest ordering while unpriced cards or unloaded pages remain. Preserve explicit partial failures and pagination, with retry for failed work.

## Acceptance checks

- Render an area's catalog without dates, including a fully booked property; exclude other regions and blacklisted inventory.
- Start loading the first visible cards while later pages remain unloaded; verify no availability requests for offscreen cards.
- Change dates/party quickly and confirm older responses cannot overwrite current cards.
- Compare individual and batch availability; check hotel, named rental and pool counts/pricing.
- Create/cancel an isolated reservation: catalog membership stays, next availability changes.
- Exercise 429, partial failure, timeout, inaccessible IDs, empty area and missing thumbnails.
- Confirm private property/guest data and credentials never enter responses or browser code.

This handoff does not change the separately managed Hidden San Diego frontend. Deploy and verify its lazy-loading behavior separately after the API release.

Optional editorial ratings: use `fetch=ratings` on catalog or direct content. Omit it to avoid ratings hydration and payload. See [affiliate ratings CRUD and rollout status](./affiliate-listing-ratings.md).

Listing detail also includes property `address` and `contact` (pending local update, not deployed). Catalog cards omit these fields. See [address/contact contract](./hidden-san-diego-integration.md#property-address-and-contact). No extra consumer request is needed.
