# Affiliate listing ratings

**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.

**Release verification:** The required ratings fields and resolver are published to preview and production. API support requires deployment of this release. Verify the target revision and an authenticated `fetch=ratings` response before enabling the integration; schema publication alone does not establish endpoint readiness.

Ratings belong to the affiliate account authenticated by the API key. Each affiliate can rate any eligible property, including its own. A hotel’s rooms and rentals under the same property share that affiliate’s property rating. Owner ratings are not a fallback and are not copied automatically.

## Fetch listings without ratings

```http
GET /api/travel/listings?destination=julian-ca&page=1&pageSize=12&includeImages=false
Authorization: Bearer <affiliate-api-key>
```

The normal response omits `ratings` entirely. It also omits the old top-level `starRating` and `priceTier`. No rating resolver or rating lookup runs. Existing stayType, description, tagLine, locations, IDs, eligibility, blacklist, images and pagination retain their contracts.

## Include ratings in the same GET

```http
GET /api/travel/listings?destination=julian-ca&page=1&pageSize=12&includeImages=false&fetch=ratings
Authorization: Bearer <affiliate-api-key>
```

Illustrative response excerpt; other listing and pagination fields are omitted here only for brevity:

```json
{
  "listings": [
    {
      "id": "hotel:example-property",
      "propertyId": "example-property",
      "name": "Example Hotel",
      "stayType": "inn",
      "ratings": {
        "starRating": 4.5,
        "priceTier": 3
      }
    }
  ]
}
```

The same option works on `GET /api/travel/listings/{listingId}?fetch=ratings`. Both image modes support it. With the option, unrated properties return `ratings: {"starRating": null, "priceTier": null}`. Without it, the `ratings` member is absent. `fetch=rating`, unknown names, empty values, comma lists and repeated parameters return 422. Only the allowlisted expansion is accepted; this is not arbitrary access to Onyx resolvers.

- `starRating`: null or a number from 1 through 5 in increments of 0.5. Affiliate editorial classification, not guest reviews or independent certification.
- `priceTier`: null or an integer from 1 through 5: Budget, Value, Mid-range, Upscale, Luxury. Not a nightly rate or booking quote.

Use your own affiliate API key for both management and retrieval. The server derives the affiliate identity from the key; callers cannot supply another account’s UID. Different keys for the same affiliate share its ratings. Other affiliates have separate values.

## Create, read, replace and delete

Use the raw `propertyId` from a listing, not the prefixed listing ID.

```http
PUT /api/affiliates/listings/example-property/ratings
Authorization: Bearer <affiliate-api-key>
Content-Type: application/json

{"starRating":4.5,"priceTier":3}
```

PUT creates or replaces both values; both fields are required. Null clears an individual value. Unknown fields are rejected. It cannot change visibility, commission, property identity or another affiliate’s values.

```http
GET /api/affiliates/listings/example-property/ratings
DELETE /api/affiliates/listings/example-property/ratings
```

GET and DELETE take no body. DELETE clears both ratings and preserves the property’s blacklist setting. These operations return 200 with:

```json
{"propertyId":"example-property","starRating":null,"priceTier":null}
```

An active affiliate API key or a verified-email session for an active affiliate is required. Property-owner keys and search-only `travel_availability` keys are denied. A hosting account must use its affiliate key for this operation. Ownership does not authorize editorial ratings through property APIs.

Errors: 401 for unauthenticated requests; 403 for denied scope/account; 404 for unavailable property; 422 for invalid input; 429 with Retry-After for the account-wide one-request-per-second budget; 503 for provider failures. GET, PUT and DELETE return `Cache-Control: private, no-store`. Keep the key server-side.

## Database and performance

The existing `AffiliateListingSelection` table gains nullable `starRating: Double` and `priceTier: Integer`, plus this computed resolver:

```json
{
  "name": "ratings",
  "resolver": "mapOf(Pair(\"starRating\", this.starRating), Pair(\"priceTier\", this.priceTier))"
}
```

No new table. No records are created by GET. The resolver projects the two values on the same affiliate/property row without extra joins. With `fetch=ratings`, the catalog performs one scoped, bounded query for the current page’s maximum 12 properties. It filters authenticated UID and deterministic row IDs, selects only identity fields plus `ratings`, and calls `.resolve('ratings')`. Multiple rental cards reuse the property result. It never loads every affiliate’s ratings and filters them afterward.

A failed resolver or provider query is not treated as null ratings. Catalog failures remain explicit through `failures`, `meta.partial`, `meta.pageComplete` and `meta.complete`; direct content fails with 503. Preserve the existing no-store behavior. Availability calculations, booking attribution and commission terms are unchanged.

[Listing schemas](./travel-listings.schema.json) · [Complete integration guide](./hidden-san-diego-integration.md) · [Card metadata](./listing-card-metadata.md)
