# Affiliate Integration Guide

Build a lodging site with Wikiup as the source for listings, photos, live availability,
prices, and hosted checkout. This guide applies to any affiliate: tourism sites,
publishers, influencers, and hosts who also refer bookings.

The examples use fictional property IDs and content. They describe the contract,
not live inventory or deployment evidence. Replace IDs with values returned by the
API and dates with future travel dates. This guide does not add or change endpoints.

## Account, credentials, and eligible properties

1. Create an account with the affiliate's contact email, verify it, and set up the
   Affiliate profile in the console's **Affiliate Portal**.
2. Create an **Affiliate** API key from the account menu. A host API key is not an
   affiliate key, even if both belong to the same email. Keep the secret on your
   server; never include it in browser code, public URLs, or logs.
3. Configure `WIKIUP_API_ORIGIN` as `https://api-preview.wikiup.app` for testing or
   `https://api.wikiup.app` for production. Use the key issued in that environment.
   `WIKIUP_AFFILIATE_API_KEY` below is your server-held secret.
4. Owners request participation through Property → Listing Partners. Review requests
   in Affiliate Portal → Requests. Each property needs approval for your affiliate,
   including properties you own. Pending, denied, suspended, withdrawn, removed,
   blacklisted, or otherwise ineligible listings must not be displayed as bookable.

Affiliate requests span eligible properties across owners; no `x-property-id` is
needed. Affiliate keys do not authorize owner APIs for guests, reservations,
access codes, memberships, or internal notes. Account/profile and key management
use the signed-in console. See [listing approvals and lifecycle](listing-partner-requests.md)
and [affiliate account and reporting](affiliates.md).

## 1. Browse an area without checking availability

```sh
curl --silent --show-error --fail-with-body --get \
  "$WIKIUP_API_ORIGIN/api/travel/listings" \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY" \
  -H 'Accept: application/json' \
  --data-urlencode 'destination=julian-ca' \
  --data-urlencode 'includeImages=true' \
  --data-urlencode 'page=1' --data-urlencode 'pageSize=12'
```

Use supported [destination IDs](travel-destinations.md), including destination,
parent-region, or county IDs. Do not invent IDs from a town name. The catalog
accepts no dates or guest counts. Occupied listings can appear: this is discovery,
not an availability claim.

`includeImages=true` requests prepared cover-image metadata, not the full gallery.
Omit it or use `includeImages=false` for the lightest catalog response, with covers
deferred. There is no `fetch=images` alternative. To include your affiliate's
editorial ratings, add `--data-urlencode 'fetch=ratings'` to this cURL request.
Ratings are otherwise omitted; see [ratings retrieval and CRUD](affiliate-listing-ratings.md).

Populated catalog-card excerpt (the response also includes `contractVersion`,
`query`, `failures`, and `meta`):

```json
{
  "listings": [
    {
      "id": "hotel:property_example",
      "propertyId": "property_example",
      "type": "hotel",
      "name": "Example Garden Inn",
      "propertyName": "Example Garden Inn",
      "description": "A small inn with garden terraces.",
      "tagLine": "A quiet mountain retreat",
      "stayType": "inn",
      "location": "Julian, CA",
      "destination": "julian-ca",
      "mapLocation": null,
      "timeZone": "America/Los_Angeles",
      "availabilityStatus": "unchecked",
      "coverImage": null,
      "imageStatus": "pending"
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `id`, `propertyId` | Stable listing ID and underlying property ID. Preserve both; they are not interchangeable. |
| `type` | `hotel` represents a property with room selection; `vacation_rental` represents a bookable unit. |
| `name`, `propertyName` | Public listing name and parent property name. |
| `description`, `tagLine` | Nullable text: catalog description up to 240 characters; tagline up to 100. |
| `stayType` | Nullable subtype: hotel, inn, bed_and_breakfast, resort, vacation_rental. Do not use it to infer the booking model. |
| `location`, `destination` | Locality display label and canonical geography ID. |
| `mapLocation` | Exact `{latitude, longitude}` or null. Keep unmapped cards visible; never substitute a town-center pin. |
| `timeZone` | Property IANA time zone, or null if unknown. Use it for displayed timestamps. |
| `availabilityStatus` | `unchecked`; no price or availability calculation has run. |
| `coverImage`, `imageStatus` | Cover metadata and its readiness; see the photo section below. |
| `maxGuests` | Rental capacity, nullable when unknown; absent on hotel cards. |
| `ratings` | Only with `fetch=ratings`: `{starRating, priceTier}`, each nullable and scoped to your affiliate. |

Follow `meta.nextPage` until null. Pagination is by property, not card: a rental
property can produce several cards, so never truncate the response to `pageSize`.
Keep `failures`, `meta.partial`, `meta.pageComplete`, and `meta.complete` visible in
search state. A failed property is not an empty area. Complete field definitions
are in [the response schemas](travel-listings.schema.json), especially
`CatalogResponse`, `CatalogListing`, and `CatalogMeta`.

## 2. Open a listing and load its photos

Set `ENCODED_LISTING_ID` to the returned ID encoded once as one URL path segment,
for example `hotel%3Aproperty_example`.

```sh
curl --silent --show-error --fail-with-body \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID" \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY" \
  -H 'Accept: application/json'
```

Read `listing`. Detail includes identity, description, amenities, ordered photos,
map location, time zone, property address, and business contact details. It contains
no live prices, available counts, or booking URLs. Sanitize description HTML before
rendering; treat ordinary labels and address/contact values as text.

The ordinary detail request includes these address/contact fields (excerpt):

```json
{
  "listing": {
    "id": "hotel:property_example",
    "address": {
      "line1": "100 Example Lane",
      "line2": null,
      "city": "Julian",
      "state": "CA",
      "postalCode": "92036",
      "country": "United States"
    },
    "contact": {
      "phone": "+1 202-555-0142",
      "email": "hello@example.com",
      "websiteUrl": "https://example.com/"
    }
  }
}
```

Each address/contact value is a string or null; `address` itself is null when
entirely absent. Country is stored text, not guaranteed to be an ISO code. These
are property business details, not private owner account records. Omit empty
rows. `contact.websiteUrl` is not an attributed Reserve link. Catalog cards omit
address/contact to stay lightweight. See schema `ListingContent` for every detail field.

The detail endpoint needs no image query parameter. Use the dedicated listing
photos below; never substitute website slideshows or scrape owner endpoints.

## Detail image shape

This is a populated **image-field excerpt**, not a full listing response or a
live property response. Example IDs/URLs below must never be hardcoded.

```json
{
  "listing": {
    "id": "hotel:property_example",
    "coverImage": {
      "id": "encoded-cover-source",
      "url": "https://api-preview.wikiup.app/public/listing-images/encoded-cover-source/content-version/640.webp",
      "alt": "Garden terrace",
      "width": 640,
      "height": 360,
      "group": null,
      "variants": [
        {
          "url": "https://api-preview.wikiup.app/public/listing-images/encoded-cover-source/content-version/640.webp",
          "width": 640,
          "height": 360,
          "format": "webp"
        }
      ]
    },
    "gallery": [
      {
        "id": "encoded-cover-source",
        "url": "https://api-preview.wikiup.app/public/listing-images/encoded-cover-source/content-version/640.webp",
        "alt": "Garden terrace",
        "width": 640,
        "height": 360,
        "group": null,
        "variants": [
          {
            "url": "https://api-preview.wikiup.app/public/listing-images/encoded-cover-source/content-version/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ]
      },
      {
        "id": "encoded-entrance-source",
        "url": "https://api-preview.wikiup.app/public/listing-images/encoded-entrance-source/content-version/640.webp",
        "alt": "Property entrance",
        "width": 640,
        "height": 360,
        "group": null,
        "variants": [
          {
            "url": "https://api-preview.wikiup.app/public/listing-images/encoded-entrance-source/content-version/640.webp",
            "width": 640,
            "height": 360,
            "format": "webp"
          }
        ]
      }
    ],
    "galleryGroups": []
  }
}
```

- `gallery` already includes the cover as its first image. Do not prepend
  `coverImage` or duplicate it. Preserve array order. Hotels have up to 10
  dedicated property photos, or just the retained cover until a gallery is saved.
- Each image's `id` identifies its source; `url` is a versioned public image URL;
  `alt` is its description; `width`/`height` are actual dimensions of that URL.
- `variants` provides actual available sizes and formats (`webp`, `jpeg`, `png`,
  or `avif`). Use responsive image selection; never manufacture thumbnail URLs.
  The list may contain only the original while thumbnails are pending.
- `group` is an existing nullable `{id,title}` descriptor. `galleryGroups` is an
  existing array of `{id,title,imageIds}`. Neither is required to render photos.
  Removing the Group input from the console does not remove these API fields.
- Catalog `coverImage` has the same image shape, or null. `imageStatus` is
  `ready`, `pending` (thumbnails not ready), `none` (no source), or `deferred`
  (`includeImages=false`). Pending/deferred is not proof of an empty gallery.
- Rental listings use their unit photos first, with the dedicated property
  collection as fallback. Hotel room detail photos remain room-specific.

## UI and freshness

1. Render card covers from the catalog. Fetch detail when opening a listing;
   render its full `gallery` as the main photo plus selectable thumbnails.
2. Use 16:9 display frames with proportional `object-fit: cover`; never stretch.
   The original/full-photo viewer may preserve the complete source proportions.
3. Replace the entire displayed collection on a fresh successful detail response.
   Do not merge old slideshow images, retain removed photos, or append defaults.
4. Honor JSON no-store headers. Purge any existing cached/copied listing JSON or
   old image-source mappings. Public image bytes may be cached by their exact
   versioned URLs; URL changes must select new bytes.
5. Keep credentials server-side. Honor `Retry-After` on 429 and sequence detail
   and availability calls; these share the account's rate limit.
6. Show genuine empty/error/retry states. A provider failure is not an empty
   gallery. Preserve approval/suspension restrictions and booking attribution.
7. If the provider returns the wrong collection, report sanitized response,
   listing ID, API revision, and property-local timestamp to Wikiup. Do not
   compensate by scraping the slideshow or inventing another source.

## 3. Load live availability after dates and guests are selected

For visible cards, send one batch of at most 12 unique `listingIds` (or
`propertyIds`, never both). This avoids a separate request per property:

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

Batch `results` preserve request order. Each has `requestId`, `propertyId`, and
`status`: `available`, `sold_out`, `not_found`, or `error`. Successful checks include
`listings` and `options`; errors include `code` and `retryable`. Batch responses
omit images: merge prices by stable ID while retaining catalog photos. HTTP 200
can be partial; inspect `complete` and every result. See [batch schema and limits](affiliate-lazy-loading.md).

On a property page, check the selected listing directly:

```sh
curl --silent --show-error --fail-with-body --get \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID/availability" \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_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'
```

Illustrative full direct-availability response. The booking URL is a non-working
example; use the actual returned URL in your integration.

```json
{
  "listingId": "hotel:property_example",
  "status": "available",
  "options": [
    {
      "id": "room_example",
      "roomId": "room_example",
      "roomTypeId": null,
      "name": "Garden King",
      "photos": [],
      "capacity": 2,
      "maxGuests": 2,
      "availableCount": 1,
      "currency": "USD",
      "nightlyRate": 200,
      "staySubtotal": 600,
      "priceBasis": "accommodation_subtotal",
      "taxes": null,
      "fees": null,
      "finalTotal": null,
      "bookingUrl": "https://api-preview.wikiup.app/widgets/booking?propertyId=property_example&roomId=room_example&checkIn=2027-02-09&checkOut=2027-02-12&adults=2&children=0&pets=0&guests=2&affiliateReferral=EXAMPLE_NOT_VALID",
      "image": null,
      "imageVariants": []
    }
  ],
  "complete": true,
  "generatedAt": "2026-11-15T12:00:00-08:00"
}
```

| Field | Meaning |
| --- | --- |
| `listingId`, `status`, `complete`, `generatedAt` | Listing checked, outcome, successful completion, and response instant. |
| `options[].id` | Opaque choice ID; preserve unchanged for room detail and selection. |
| `roomId`, `roomTypeId` | Physical room ID or pooled type ID; the unused value is null. |
| `name`, `capacity`, `maxGuests` | Choice label and guest capacity. |
| `availableCount` | Units assignable for the whole stay; not reserved or held. |
| `currency` | Currency for amounts expressed in major units. Never compare different currencies as one price ranking. |
| `nightlyRate`, `staySubtotal`, `priceBasis` | Average nightly accommodation price and stay accommodation subtotal; excludes taxes and fees. |
| `taxes`, `fees`, `finalTotal` | Null until checkout, not zero. |
| `photos`, `image`, `imageVariants`, optional `coverImage` | Public option photo URLs, cover URL, prepared sizes, and structured cover metadata. Use room detail for its full gallery. |
| `bookingUrl` | Signed checkout destination for this choice and party; use unchanged. |

Dates must be valid future/current `YYYY-MM-DD` dates, check-in within two years,
with 1–28 nights. Adults: 1–20 (default 2); children: 0–19; pets: 0–10; total
humans at most 20. Children/pets default to 0. Refresh after any date or party
change and ignore superseded responses. Disable Reserve until a fresh matching
option exists. A successful direct sold-out response has `options: []`; provider
failure is 503, not sold out.

## 4. Optional hotel room page

Use the same route for named rooms and pooled room types. Set `ENCODED_ROOM_ID`
to the exact `options[].id`, URL-encoded once; do not choose routes by booking model.

```sh
curl --silent --show-error --fail-with-body \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID/rooms/$ENCODED_ROOM_ID" \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY" \
  -H 'Accept: application/json'
```

Read `room` for description, amenities, capacity, and gallery. This route accepts
no dates or query parameters and does not quote a price or reserve inventory.
Refresh parent availability and match its exact option ID for Reserve. See
[room details and populated responses](hotel-room-details.md). Rentals continue
using their listing detail page.

## 5. Send the guest to Wikiup checkout

Set Reserve to the selected option's **entire returned `bookingUrl`**, unchanged.
Navigate the browser there. Do not rebuild its parameters, replace the room,
remove `affiliateReferral`, append the API key, or substitute the property website.
Opening it does not reserve or charge. Wikiup collects guest details and payment,
rechecks availability and final totals, then handles confirmation and the guest portal.
Guests do not need a staff account. A Reserve click is not booking success; there
is no partner booking-completion webhook in this contract.

To smoke-test an actual returned URL without booking, set `BOOKING_URL` to its
exact value and request HTML without authorization:

```sh
curl --silent --show-error --fail-with-body --max-time 25 \
  "$BOOKING_URL" -H 'Accept: text/html' --output wikiup-checkout.html
```

Do not proxy the downloaded HTML as your own checkout or log signed booking URLs.

## Failures, performance, and freshness

- Keep catalog/detail/availability JSON `no-store`, including your server proxy and
  framework caches. Do not reuse completed availability, prices, counts, or links.
  Versioned public image bytes may be cached separately by their exact URL.
- All travel requests share the affiliate account's one-request-per-second budget
  across keys. Sequence requests; batch visible listings instead of bursting
  individual calls. Honor 429 `Retry-After` with bounded retries.
- Catalog pagination and availability loading are separate. Do not claim a complete
  search or global cheapest sort while pages/checks remain unloaded or failed.
- 401: invalid/missing credential; 403: denied scope/account; 404: inaccessible
  listing; 422: invalid input; 429: rate limit; 503: provider/configuration failure.
  Show retry for failures, not fabricated inventory or a false sold-out state.
- Format displayed verification/event timestamps using the property's `timeZone`.
  Never shift date-only check-in/out values through UTC date conversion.

## Attribution and commission reports

Signed checkout links carry affiliate attribution. Wikiup sets a fixed **0.75%**
commission on accommodation after discounts only, excluding taxes, cleaning,
pet fees, and all other add-ons or fees. Neither affiliates nor platform users
configure a percentage. In Affiliate Portal → Bookings & income, **Rate** is
0.75%, **Pending** is estimated commission before checkout, and **Earned** is
commission after checkout, limited by collected payments and reduced by successful
refunds. Existing attributed bookings use this policy too, including those with
legacy missing rates. Reports do not execute payouts. See [commission rules](affiliates.md).

## Integration acceptance checklist

- Browse without dates, preserving unchecked status and property pagination.
- Plot only supplied exact map positions; keep unmapped cards visible.
- Render the full ordered gallery, cover once, with selectable thumbnails.
- Verify reordered/removed photos appear correctly on the next fresh detail read.
- Handle pending thumbnails, empty galleries, and provider errors distinctly.
- Keep named-room, pooled-room, and rental identities intact through selection.
- Change dates/guests/pets quickly; stale requests must not overwrite newer results.
- Handle partial failures and 429 without losing successful results or showing stale prices.
- Confirm approved/active eligibility and suspension/removal behavior with isolated fixtures.
- Navigate to the actual signed checkout link and confirm attribution using an
  authorized test booking; a page-load check alone is not an end-to-end booking test.
- Verify responsive layout, keyboard gallery controls, and API-key secrecy.

If Wikiup lacks a required field or returns incorrect content, send its team a
Markdown task containing the expected behavior, route, sanitized criteria and
response, API revision, property-local observation time, and acceptance checks.
Do not scrape owner resources, guess missing data, or invent a workaround in the
partner website for behavior that belongs in Wikiup.

## Reference contracts

- [Response schemas and field definitions](travel-listings.schema.json)
- [Listing API reference](travel-listings.md)
- [Lazy-loading and batch availability](affiliate-lazy-loading.md)
- [Destinations](travel-destinations.md)
- [Owner listing-photo management](property-listing-photos.md)
- [Affiliate ratings](affiliate-listing-ratings.md)
- [Listing approvals](listing-partner-requests.md)
- [Affiliate accounts, attribution, and reports](affiliates.md)

This document is an integration guide, not a deployment report. Verify the target
origin's revision and authenticated responses before releasing your consumer.


## Signed-in Affiliate Portal previews

**Local contract update; verify deployment before use.** The Wikiup console can use
its verified, active affiliate session on these existing GET routes:

- `/api/travel/listings`
- `/api/travel/listings/{listingId}`
- `/api/travel/listings/{listingId}/rooms/{roomId}`
- `/api/travel/listings/{listingId}/availability`

Each request still requires that affiliate's approved, unsuspended relationship
with the property. Being a property owner alone grants no affiliate access.
Blacklist, active inventory, no-store and the shared one-request-per-second account
budget apply equally to sessions and keys. Honor `Retry-After` on HTTP 429.

Omit catalog `destination` to browse all approved properties across destinations,
including properties whose destination is unknown. The unfiltered response omits
`query.destination`; each listing's `destination` may be null. Supplying a valid
ID retains geographic filtering; an empty or invalid ID returns 422. Pagination
and partial-failure semantics are unchanged.

```sh
curl --fail-with-body --get \
  "$WIKIUP_API_ORIGIN/api/travel/listings" \
  -H "Authorization: Bearer $WIKIUP_SESSION_TOKEN" \
  --data-urlencode 'includeImages=true' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=12'
```

Session-based direct availability returns ordinary hosted `bookingUrl` links with
dates and guests but **no affiliateReferral token**. They are portal inspection
links, not commission-attributed referrals. Opening checkout does not create a
booking; submitting checkout is the real guest booking flow.

Partner sites must continue using their server-held affiliate API key. Its returned
booking links retain signed attribution. This session extension does not apply to
batch `POST /api/travel/listings/availability` or regional
`GET /api/travel/availability`, and does not grant property-management access.
Suspended listings remain accessible through the existing affiliate management
APIs, not the public catalog/detail routes.

## Date-free hotel room galleries

Use `GET /api/travel/listings/{listingId}/rooms?page=1` to render all active hotel
rooms or pooled room types below the property description without an availability
search. Follow `meta.nextPage` until null; twelve rooms per page. Each `rooms[]`
entry is the existing individual room-detail object, including its own gallery.
See [room collection and detail contract](hotel-room-details.md#browse-every-room-without-dates)
for cURL, populated JSON, field definitions, authorization and retry behavior.
This addition is local until deployment is verified.
