# Affiliate lodging card metadata

**Release verification:** The optional affiliate-ratings contract requires this API release. Its database fields and resolver are published to preview and production. Verify the deployed revision and authenticated response before adopting it. The earlier rollout report documents the previous release, not this change.

The date-free `GET /api/travel/listings` and direct `GET /api/travel/listings/{listingId}` responses include the following metadata fields (ratings are an optional nested expansion). The card fields use `description` and `tagLine`; the earlier `shortDescription` and `accommodationSummary` response names are removed. Read the [complete affiliate guide](./hidden-san-diego-integration.md) for authentication, geography, pagination, lazy availability, attribution and booking.

| Field | Meaning and limits | Source |
| --- | --- | --- |
| `stayType` | `hotel`, `inn`, `bed_and_breakfast`, `resort`, `vacation_rental`, or null. Display labels: Hotel, Inn, Bed & Breakfast, Resort, Vacation Rental. | Explicit Property.stayType. A subtype inconsistent with broad `type` is returned as null. |
| `description` | Catalog: plain text at most 240 Unicode characters, including an ellipsis when shortened; render as text. Direct content: existing full saved description, which may contain HTML; sanitize before rendering. Unknown/empty returns null. The catalog removes markup, hidden content and common booking/placeholder prompts. | Hotel: Property.description. Rental: the exact named room's details.description or pooled room type's content.details.description. No fallback to the parent property's description for units. |
| `ratings.starRating` | Only with `fetch=ratings`: 1–5 in half-star increments, or null. Affiliate editorial classification, not guest reviews or independent certification. | Authenticated affiliate’s AffiliateListingSelection ratings resolver. |
| `ratings.priceTier` | Only with `fetch=ratings`: integer 1–5 or null: Budget, Value, Mid-range, Upscale, Luxury. Not a price quote. | Authenticated affiliate’s AffiliateListingSelection ratings resolver. |
| `tagLine` | Plain text at most 100 Unicode characters including an ellipsis when shortened, or null. No inferred private entrances or hotel room totals. Counts describe accommodation, never currently available inventory. | Hotel: owner-authored Tagline in Identity. Rental: exact unit's saved beds and bathroomCount; pooled listing: its own room-type content, never the sum of physical members. |

Unknown, out-of-range legacy values and absent descriptions remain null. Hidden San Diego may use `ratings?.starRating ?? 2` and `ratings?.priceTier ?? 2` **for its requested visual fallback only**. Do not write those defaults into Wikiup or present them as verified ratings. Omit absent descriptive text. The existing `type` (`hotel` / `vacation_rental`), listing ID and booking semantics remain authoritative.

## Consumer update

- Replace `shortDescription` with `description` in catalog cards.
- Replace `accommodationSummary` with `tagLine` in catalog and direct content.
- Direct content already has the full `description`; keep using it for the property page. The rename does not truncate that field or add a second description field.
- Both names are case-sensitive: `tagLine`, not `tagline`. Null values remain null. Add `fetch=ratings` to the same GET when ratings are needed; no separate client request is required.

## Request

Use an Affiliate key server-side. No new key or scope is needed.

```sh
curl 'https://api-preview.wikiup.app/api/travel/listings?destination=julian-ca&page=1&pageSize=12&includeImages=false' \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY"
```

Stay type, description and tagline are included with both `includeImages=false` and `includeImages=true`. Cards still have `availabilityStatus: "unchecked"`. Merge a later availability response into each card; do not discard metadata. Use the existing `failures`, `meta.partial`, `meta.pageComplete`, `meta.complete`, and `meta.nextPage` fields. A metadata null does not mean sold out. Access rules, affiliate blacklist/withdrawal, pagination and `Cache-Control: private, no-store` are unchanged.

## Illustrative projections

These are `fetch=ratings` **synthetic metadata examples**, not live property observations. Existing response fields (location, mapLocation, images and pagination) are omitted here for brevity.

```json
[
  {
    "id": "hotel:example-hotel", "type": "hotel",
    "stayType": "hotel", "description": "A coastal hotel with garden terraces.",
    "ratings": {"starRating": 4, "priceTier": 4}, "tagLine": "12 rooms and 3 suites"
  },
  {
    "id": "hotel:example-inn", "type": "hotel",
    "stayType": "inn", "description": "A hillside inn overlooking the orchard.",
    "ratings": {"starRating": 3.5, "priceTier": 2}, "tagLine": "5 private entrance rooms"
  },
  {
    "id": "rental:example-home:room:cottage", "type": "vacation_rental",
    "stayType": "vacation_rental", "description": "A cottage with a private garden.",
    "ratings": {"starRating": null, "priceTier": 3}, "tagLine": "2 king beds, 1 bath"
  },
  {
    "id": "rental:example-pool:pool:king-suite", "type": "vacation_rental",
    "stayType": "vacation_rental", "description": "A king suite with a sitting room.",
    "ratings": {"starRating": null, "priceTier": null}, "tagLine": "1 king bed, 1.5 baths"
  }
]
```

## Authoring and storage

Console: **Property → Identity**, then the existing **Save changes** action. Stay type and Tagline are also captured during property creation. Tagline allows at most 100 characters. Existing descriptions remain in their normal property/room editors.

Property owners cannot set ratings. `POST /api/properties` rejects non-null ratings with 403. `PUT /api/properties/{id}` rejects ratings changes with 403; unchanged legacy values are accepted only to support older clients and are never published as affiliate ratings. Legacy property values remain stored; they are not copied to any affiliate.

Stay type is selected during property creation and is immutable afterward. `PUT /api/properties/{id}` permits omitting `stayType` or sending the saved value. Changing it or clearing a saved value returns HTTP 409 with `{"error":"Stay type can only be selected when creating a property."}`. A legacy null or omitted stored value remains null and cannot be assigned through an update. Creation and response fields are unchanged.

Owner routes accept `tagLine`, the stored Property field and the name used in owner, console and affiliate responses; it allows at most 100 characters. Null clears it. Omitted fields survive unrelated edits. The old `accommodationSummary` column is retired, with existing text migrated before removal. Booking model is selected only during creation. Changing `roomBookingMode` afterward returns 409, and unrelated saves preserve the persisted model.

Affiliate ratings create/read/update/delete and optional listing hydration are documented in [affiliate-listing-ratings.md](./affiliate-listing-ratings.md).
Bathrooms are an optional structured API field: `PATCH /api/rooms/{roomId}/details` accepts `bathroomCount` (0–100, increments of 0.5, or null). For pooled room types, use the existing authorized `PUT /api/room-types/{id}` endpoint with `content.details.bathroomCount`; retain other content when editing. Zero is an explicit supplied value; missing is unknown. Beds use existing structured `details.beds` values. Rental cards derive their tagline from the unit's structured accommodation facts, not Property.tagLine. The new bathroom count does not add an iOS editor or change booking capacity.

Affiliate ratings storage requires two nullable fields and one resolver on the existing AffiliateListingSelection table; no new table. The naming of owner text needs no database migration. Existing owner text is preserved in storage; values longer than 100 characters are shortened only in the public `tagLine`, with an ellipsis. Older owner clients and unrelated edits continue to preserve the saved text. The previously added property metadata and bathroom fields remain unchanged.

## Performance and verification

Default card metadata uses already-loaded inventory and performs no ratings reads. `fetch=ratings` performs one bounded, affiliate-scoped Onyx query for at most 12 properties, selecting only identity fields and the ratings resolver. Rental units at one property share its affiliate ratings. No reservation or pricing requests are added. Description input parsing is bounded to 20,000 source characters. Existing property concurrency and deadline limits remain unchanged.

The machine-readable fields and bounds are in [travel-listings.schema.json](./travel-listings.schema.json), definitions `CatalogListing` and `ListingContent`. Repository verification evidence and live-test limitations are recorded in `plan/listing-card-metadata-verification.md`. Verify the deployed revision and response before consuming the extension. Schema publication alone does not deploy the API.

For property-related evidence, display dates/times using the returned IANA `timeZone` and include its local offset. Do not mistake UTC transport timestamps for the property's local time.
