Stream Room Updates

This is where the bookable offers arrive. Get Room Options starts the search and returns an sse_stream_url. You open that URL and read a Server-Sent Events (SSE) stream. Each supplier sends its offers as soon as it answers, so the first offers usually show up well before the slowest supplier has finished. A final done event tells you the search is over. Search → Rooms (this page) → Prebook → Book.

curl -N "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "accept: text/event-stream"

How a search runs

Open the stream right away

Use data.sse_stream_url from the POST response with the same x-api-key. Open it immediately: the search starts when the POST is accepted, and the stream only keeps recent events.

Read events as they arrive

Add each provider_options event’s rooms[] (family objects) to your room store and each options[] entry to your offer list. Draw the room cards from them.

Stop at done

The done event is the last event. Close the connection yourself when you get it. The server keeps a finished stream readable for about 2 minutes so late or reconnecting clients can still read it, so the connection is not closed for you.

Let the guest choose

Send the chosen offer’s booking_token unchanged to Prebook a Room.

Browser EventSource cannot send an x-api-key header. Open the stream from your server and forward the events to the browser, or use a fetch-based SSE client that can set headers. Never put your API key in front-end code.

Events

Every event has an SSE id (a whole number that starts at 1 and increases by one for each event of the stream), an event name and a JSON data body. The body of every event also carries these envelope fields:

Field	What it means	How to use it
`event_type`	Same as the SSE `event` name	Switch on it if your client only sees `data`.
`contract_version`	Always `"2"`	Informational. The response also carries the `X-Unifystays-Contract-Version: 2` header.
`request_id`	ID of the room search	Quote it to support.
`stream_id`, `hotel_id`	The stream and the Unifystays hotel	Match them with the POST response.
`emitted_at`	When the event was created (ISO 8601, UTC)	Logging only.

`event`	When it is sent	Extra fields	What to do
`stream_ready`	First event, immediately	`created_at_ms`, `ttl_ms` (45000)	Nothing. `ttl_ms` is how long the search may run.
`provider_options`	A supplier returned offers (or none)	See below	Add the family objects and the offers.
`provider_error`	A supplier failed or timed out	`provider_code`, `code`, `stage` (`ROOMS`), `retryable`	Keep going; other suppliers continue. Do not show the supplier’s code to guests.
`provider_skipped`	A supplier was not queried	`provider_code`, `reason` (and `code`, `retryable` when the supplier’s hotel match is not confirmed yet)	Keep going. Starting a new search later may include it.
`heartbeat`	Every 15 seconds while the search runs	Envelope only	Use it as a liveness signal.
`done`	Last event	`success`, `status`, `total_options`, `providers`	Stop reading and close the connection.

`provider_options`

Field	What it means	How to use it
`provider_code`	Supplier of these offers	Display as the seller if you wish.
`options[]`	Complete offers. Can be empty when the supplier has no availability	Add each to your offer list. See the offer.
`rooms[]`	The family objects these offers use, new or updated	Store by `unifystays_room_id`, replacing any earlier copy. See Family objects.
`option_count`	Offers in this batch across all its chunks	Progress display.
`chunk_index`, `chunk_count`	Position of this event in the batch (0-based) and number of events in it	Each event is self-contained; you do not have to wait for the other chunks. Absent when `options` is empty.
`hidden_payment_option_count`	Offers the supplier returned that need a card and are therefore not shown	Informational. Only present for some events.

A single event carries at most 50 offers and about 256 KB of JSON. A larger result is split into several events with the same provider_code. A supplier can also send its offers in more than one batch: offers whose rooms are already known first, the rest shortly after.

`done`

{
  "event_type": "done",
  "success": true,
  "status": "PARTIAL",
  "total_options": 14,
  "providers": { "queried": 3, "succeeded": 2, "failed": 0, "timed_out": 1, "skipped": 0 },
  "contract_version": "2",
  "stream_id": "stream_a71c0e9b2f44",
  "hotel_id": "1393631",
  "request_id": "req_9d41c7e0b3a24f5e8a1d6c0b7e2f3a49",
  "emitted_at": "2026-10-08T10:00:21.114Z"
}

Field	What it means	How to use it
`status`	`COMPLETE`: every queried supplier answered. `PARTIAL`: at least one answered and at least one failed, timed out or was skipped. `FAILED`: no supplier answered.	Show the offers you have for `COMPLETE` and `PARTIAL`. For `FAILED` offer a retry (a new room search).
`success`	`true` for `COMPLETE` and `PARTIAL`, `false` for `FAILED`	Same meaning as `status`.
`total_options`	Number of offers sent on the whole stream	`0` with `success: true` means the hotel has no availability for these dates.
`providers`	Counts of suppliers `queried`, `succeeded`, `failed`, `timed_out` and `skipped`	Diagnostics. Absent when no supplier was queried.
`reason`	`stream_ttl_expired` when the 45 second limit ended the search before every supplier answered	Treat the result as partial.

Time limits and partial results

The whole search is capped at 45 seconds from the POST. When the cap is reached, suppliers that have not answered are counted as timed out, and done is sent with PARTIAL (or FAILED if nobody answered).
Each supplier also has its own time limit (about 20 seconds by default). A supplier that exceeds it produces a provider_error with code: "PROVIDER_TIMEOUT" and never delays the others.
Show offers as they arrive and keep a “still searching” state until done. A result list that was complete at done is stable: later events never remove an offer, but a later provider_options event can replace a family object.
Offers are valid for a limited time. See lifecycle.expires_at. If the guest waits too long, run a new room search instead of sending an old booking_token.

Reconnect with `Last-Event-ID`

The stream keeps the latest 250 events. If your connection drops, reconnect to the same sse_stream_url and send the id of the last event you processed as the Last-Event-ID header (browser EventSource does this for you). The API replays the later events and then continues live. Without the header, or with 0, you get every retained event from the start.

curl -N "$UNIFYSTAYS_BASE_URL/hotels/123456/rooms/stream/stream_8f4b9d1f6d9e" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY" \
  -H "Last-Event-ID: 17"

Response	Meaning	What to do
`409 ROOM_STREAM_REPLAY_GAP`	The event you asked to resume after is no longer retained	Start a new room search. Do not accept an incomplete stream.
`404 ROOM_STREAM_NOT_FOUND`	The stream does not exist or has expired (about 2 minutes after `done`)	Start a new room search.
`404 ROOM_STREAM_HOTEL_MISMATCH`	The stream belongs to another hotel	Use the `hotel_id` you searched.

A reconnect never loses offers when you replay from your last processed id. Make your handler idempotent anyway: store offers by offer_id and family objects by unifystays_room_id. A fetch-based client that reconnects until done:

async function readRoomStream(
  url: string,
  apiKey: string,
  onEvent: (event: string, data: any) => void,
) {
  let lastId = "0";
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(url, {
      headers: { "x-api-key": apiKey, "Last-Event-ID": lastId, accept: "text/event-stream" },
    });
    if (res.status === 409) throw new Error("Replay gap: start a new room search");
    if (!res.ok || !res.body) throw new Error(`Stream failed: ${res.status}`);

    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break; // dropped: reconnect with lastId
      buffer += decoder.decode(value, { stream: true });
      let end: number;
      while ((end = buffer.indexOf("\n\n")) >= 0) {
        const frame = buffer.slice(0, end);
        buffer = buffer.slice(end + 2);
        let id = "", event = "message", data = "";
        for (const line of frame.split("\n")) {
          if (line.startsWith("id:")) id = line.slice(3).trim();
          else if (line.startsWith("event:")) event = line.slice(6).trim();
          else if (line.startsWith("data:")) data += line.slice(5).trim();
        }
        if (id) lastId = id;
        if (!data) continue;
        onEvent(event, JSON.parse(data));
        if (event === "done") { await reader.cancel(); return; }
      }
    }
  }
  throw new Error("Stream did not finish");
}

Family objects on `provider_options`

Offers from different suppliers for the same physical room are grouped under one family object, and each family splits into variants by bed type:

rooms[] on a provider_options event holds the family objects that event’s offers use, new or updated. Store them by unifystays_room_id and replace an earlier copy: a family’s variants, bed_assignment and details can change as more suppliers send offers for it.
A family object has unifystays_room_id, name, details, suppliers, variants[] and bed_assignment. Each variant has unifystays_room_id, beds, bedrooms, max_guests, smoking and suppliers. A variant’s facts are non-null only when every supplier selling that variant in this stream stated exactly that value. variants[] lists only variants with at least one seller in this stream so far.
bed_assignment.suppliers lists the suppliers whose offers belong to the family but state no bed type (the hotel assigns it). Such offers are in no variant, and a family-level seller never contributes beds to a variant.
Every slot in options[].rooms[] carries unifystays_room_id (the variant id, or the family id for an offer listed under bed_assignment.suppliers) and unifystays_family_id (the family). unifystays_room is null.
offer_family_id is filled and is computed over family ids: offers whose slots are in the same families in the same order share it. It is null when any slot is a tmp_ room (a room valid for this search only).
A supplier’s offers can arrive in more than one provider_options batch: offers whose rooms are already known first, the rest after a short, bounded wait. option_count, chunk_index and chunk_count describe one batch; done ends the stream.

Client rule: Show the family header (name, details with its source). Show each variant’s beds, bedrooms, max guests and smoking only from the variant object. Show offers listed under bed_assignment.suppliers with the label Bed type assigned by the hotel. Always show each offer row’s own provider_room. details (photos, size, description, amenities) come from the one supplier named in details.source. A tmp_ room is a temporary family object: no variants and bed_assignment.suppliers holding the seller when it stated no beds, otherwise one variant.

Field	What it means	How to use it
`unifystays_room_id` (family)	Family ID, for display and grouping	Key of your family store. Never a booking key. A `tmp_` ID is valid for this search only: do not store it. A built ID may be retired later when two rooms turn out to be one, so do not keep it as a long-lived key.
`name`	Room type name, for example “Deluxe Room”	Card title.
`details`	Photos, size, description and amenities, all from the one supplier in `details.source`	Show them with the label “Photos & details: source”. `source` is `null` when no supplier’s details may be shown; the other fields are then empty.
`suppliers`	Suppliers linked to the family, sorted	Can list a supplier before its offers arrive.
`variants[]`	One entry per bed configuration that has a seller in this stream	Sub-headings of the card. Show `beds`, `bedrooms`, `max_guests`, `smoking` from here only. A `null` value is unknown.
`bed_assignment.suppliers`	Suppliers whose offers do not state a bed type	Group their offers under “Bed type assigned by the hotel”.

{
  "contract_version": "2",
  "event_type": "provider_options",
  "provider_code": "REZLIVE",
  "option_count": 2,
  "chunk_index": 0,
  "chunk_count": 1,
  "rooms": [
    {
      "unifystays_room_id": "4120552",
      "name": "Deluxe Room",
      "details": {
        "source": "TRIPJACK",
        "images": [],
        "size": null,
        "description": null,
        "description_format": null,
        "amenities": []
      },
      "suppliers": ["REZLIVE", "TRIPJACK"],
      "variants": [
        {
          "unifystays_room_id": "4120553",
          "beds": [{ "type": "KING", "count": 1 }],
          "bedrooms": null,
          "max_guests": 2,
          "smoking": null,
          "suppliers": ["REZLIVE", "TRIPJACK"]
        },
        {
          "unifystays_room_id": "4120554",
          "beds": [{ "type": "TWIN", "count": 2 }],
          "bedrooms": null,
          "max_guests": null,
          "smoking": null,
          "suppliers": ["TRIPJACK"]
        }
      ],
      "bed_assignment": { "suppliers": ["REZLIVE"] }
    }
  ],
  "options": [
    {
      "offer_id": "off_rz_king",
      "offer_family_id": "fam_5d0c2a9e41b7f3c8",
      "booking_token": "bq7.quote-id.0.signature",
      "provider_code": "REZLIVE",
      "rooms": [
        {
          "room_allocation_id": "ra_rz_king_0",
          "unifystays_room_id": "4120553",
          "unifystays_family_id": "4120552",
          "unifystays_room": null,
          "mapping_status": "MAPPED",
          "provider_room": {
            "provider_code": "REZLIVE",
            "id": null,
            "name": "Deluxe Room King",
            "bed_configurations": [
              {
                "id": "rz-king",
                "bed_count": 1,
                "bedroom_count": null,
                "beds": [
                  {
                    "type": "King",
                    "normalized_type": "KING",
                    "supplier_type": "King",
                    "quantity": 1
                  }
                ],
                "bed_type_guaranteed": true,
                "selected": true
              }
            ],
            "occupancy": {
              "max_allowed": {
                "total": 2,
                "adults": 2,
                "children": null,
                "infants": null
              }
            }
          },
          "meal_plan": { "code": "RO", "label": "Room Only" }
        }
      ]
    },
    {
      "offer_id": "off_rz_deluxe_any_bed",
      "offer_family_id": "fam_5d0c2a9e41b7f3c8",
      "booking_token": "bq7.quote-id.1.signature",
      "provider_code": "REZLIVE",
      "rooms": [
        {
          "room_allocation_id": "ra_rz_deluxe_0",
          "unifystays_room_id": "4120552",
          "unifystays_family_id": "4120552",
          "unifystays_room": null,
          "mapping_status": "MAPPED",
          "provider_room": {
            "provider_code": "REZLIVE",
            "id": null,
            "name": "Deluxe Room Double or Twin",
            "bed_configurations": [],
            "occupancy": null
          },
          "meal_plan": { "code": "RO", "label": "Room Only" }
        }
      ]
    }
  ]
}

The example is shortened; every offer carries all the fields described in the offer. The king offer sits under variant 4120553. The second REZLIVE offer states no bed type, so its slot carries the family id as unifystays_room_id and REZLIVE is listed in bed_assignment.suppliers: show it as Bed type assigned by the hotel. REZLIVE appears both as a variant seller (its king offer, which states one king bed and 2 guests, like TRIPJACK) and under bed_assignment.suppliers (its “Double or Twin” offer). Each row still shows its own provider_room.

Room grouping only decides where an offer is drawn. It never changes what is booked. Every offer is the supplier’s own offer, identified by its booking_token and the room_allocation_id of each slot.

The offer (`HotelOffer`)

Each entry of options[] is one complete, bookable offer: a price, a cancellation policy and a meal plan for all requested rooms from one supplier. A multi-room search returns offers whose rooms[] has one entry per requested room. The customer chooses one whole offer; never mix rooms from different offers.

Full offer example (one room, three nights)

{
  "offer_id": "off_92b941fda86b4ad698044ab35152eaa5",
  "revision": 1,
  "offer_family_id": "fam_5d0c2a9e41b7f3c8",
  "supersedes_offer_id": null,
  "booking_token": "bq7.Y0QxTmtKc21Wbmk.0.6zI4D6fUEw2jVv7KQdM4Kw",
  "provider_code": "RATEHAWK",
  "quote_context": {
    "hotel": {
      "id": "123456",
      "name": "Conrad Los Angeles",
      "address": null,
      "address_local": null,
      "city": "Los Angeles",
      "state": "California",
      "country": "US",
      "postal_code": null,
      "latitude": null,
      "longitude": null,
      "timezone": null
    },
    "check_in": "2026-10-12",
    "check_out": "2026-10-15",
    "nights": 3,
    "rooms": [{ "adults": 2, "child_ages": [] }],
    "residency": "IN",
    "nationality": "IN",
    "language": "en"
  },
  "room_combination": { "normalized_type": "SINGLE_ROOM", "supplier_code": null, "supplier_name": null },
  "rate_plan": {
    "normalized_type": "UNKNOWN",
    "supplier_code": null,
    "supplier_name": null,
    "qualification": null,
    "is_package": false,
    "is_fenced": false
  },
  "rooms": [
    {
      "room_allocation_id": "ra_2c1fb39ed54742f28d95bd8bc5f4375d",
      "provider_room": {
        "provider_code": "RATEHAWK",
        "provider_hotel_id": "10004834",
        "id": null,
        "name": "Deluxe King Room",
        "supplier_name": "Deluxe King Room",
        "description": null,
        "description_format": null,
        "detail_status": "PARTIAL",
        "room_type": null,
        "room_category": null,
        "size": null,
        "amenities": [],
        "images": [],
        "bed_configurations": [
          {
            "id": "bed_1",
            "bed_count": 1,
            "bedroom_count": null,
            "beds": [
              {
                "type": "King",
                "normalized_type": "KING",
                "supplier_type": "King",
                "quantity": 1,
                "width_min_cm": null,
                "width_max_cm": null
              }
            ],
            "bed_type_guaranteed": null,
            "selected": true
          }
        ],
        "bed_summary": "1 king bed",
        "occupancy": { "max_allowed": { "total": 2, "adults": 2, "children": null, "infants": null } },
        "bathroom": null,
        "views": [],
        "features": null,
        "extra_bed": null,
        "child_bed": null
      },
      "unifystays_room_id": "4120553",
      "unifystays_family_id": "4120552",
      "mapping_status": "MAPPED",
      "mapping_details": {
        "source": "AUTO",
        "confidence": null,
        "algorithm_version": "rules-1",
        "reason_codes": ["ROOM_MATCH_CODE"]
      },
      "unifystays_room": null,
      "occupancy": { "adults": 2, "child_ages": [] },
      "meal_plan": {
        "code": "BB",
        "supplier_code": "breakfast",
        "supplier_name": "Breakfast",
        "label": "Bed & Breakfast",
        "is_breakfast_included": true,
        "is_child_meal_included": null
      },
      "inclusions": [{ "code": "wifi", "label": "Free WiFi" }]
    }
  ],
  "lifecycle": {
    "stage": "ROOMS",
    "quoted_at": "2026-10-08T10:00:00.000Z",
    "expires_at": "2026-10-08T10:15:00.000Z",
    "prebook_required": true,
    "price_guaranteed": false,
    "availability": "AVAILABLE",
    "rooms_remaining": 2,
    "on_request": false,
    "available_booking_modes": ["INSTANT"],
    "hold_allowed": false,
    "hold_deadline": null,
    "post_booking_actions": ["STATUS", "CANCEL"]
  },
  "pricing": {
    "price_basis": "COMMISSIONABLE",
    "breakdown_status": "COMPLETE",
    "native_ledger": {
      "primary_currency": "USD",
      "totals": [
        {
          "currency": "USD",
          "currency_exponent": 2,
          "payable_to_supplier": { "amount_minor": 17346, "currency": "USD", "currency_exponent": 2 },
          "payable_at_property": { "amount_minor": 885, "currency": "USD", "currency_exponent": 2 },
          "total": { "amount_minor": 18231, "currency": "USD", "currency_exponent": 2 }
        }
      ],
      "lines": [
        {
          "category": "room_rate",
          "code": "room_rate",
          "normalized_code": "ROOM_RATE",
          "description": "Accommodation rate",
          "amount": { "amount_minor": 15576, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "SUPPLIER",
          "included_in_quoted_total": true,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null
        },
        {
          "category": "fee",
          "code": "service_fee",
          "normalized_code": "SERVICE_FEE",
          "description": "Service fee",
          "amount": { "amount_minor": 1770, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "SUPPLIER",
          "included_in_quoted_total": true,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null
        },
        {
          "category": "tax",
          "code": "city_tax",
          "normalized_code": "CITY_TAX",
          "description": "City tax",
          "amount": { "amount_minor": 885, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "PROPERTY",
          "included_in_quoted_total": false,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null
        }
      ]
    },
    "usd_ledger": {
      "primary_currency": "USD",
      "totals": [
        {
          "currency": "USD",
          "currency_exponent": 2,
          "payable_to_supplier": { "amount_minor": 17346, "currency": "USD", "currency_exponent": 2 },
          "payable_at_property": { "amount_minor": 885, "currency": "USD", "currency_exponent": 2 },
          "total": { "amount_minor": 18231, "currency": "USD", "currency_exponent": 2 }
        }
      ],
      "lines": [
        {
          "category": "room_rate",
          "code": "room_rate",
          "normalized_code": "ROOM_RATE",
          "description": "Accommodation rate",
          "amount": { "amount_minor": 15576, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "SUPPLIER",
          "included_in_quoted_total": true,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null,
          "source_amount": { "amount_minor": 15576, "currency": "USD", "currency_exponent": 2 },
          "is_estimated": false
        },
        {
          "category": "fee",
          "code": "service_fee",
          "normalized_code": "SERVICE_FEE",
          "description": "Service fee",
          "amount": { "amount_minor": 1770, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "SUPPLIER",
          "included_in_quoted_total": true,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null,
          "source_amount": { "amount_minor": 1770, "currency": "USD", "currency_exponent": 2 },
          "is_estimated": false
        },
        {
          "category": "tax",
          "code": "city_tax",
          "normalized_code": "CITY_TAX",
          "description": "City tax",
          "amount": { "amount_minor": 885, "currency": "USD", "currency_exponent": 2 },
          "collection_location": "PROPERTY",
          "included_in_quoted_total": false,
          "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null },
          "mandatory": null,
          "source_amount": { "amount_minor": 885, "currency": "USD", "currency_exponent": 2 },
          "is_estimated": false
        }
      ]
    },
    "conversion": {
      "status": "AVAILABLE",
      "missing_currencies": [],
      "rates": [{ "base_currency": "USD", "quote_currency": "USD", "rate": 1, "rate_updated_at": null }]
    }
  },
  "payment": {
    "settlement_channel": "SUPPLIER_ACCOUNT",
    "payer": "AGENCY",
    "supplier_payment_type": "deposit",
    "payable_at": "SUPPLIER",
    "collection_timing": "ON_INVOICE",
    "requires_card_data": false,
    "requires_cvc": false,
    "requires_vcc": false,
    "security_deposit": null
  },
  "commercial": {
    "supplier_charge_total": { "amount_minor": 17346, "currency": "USD", "currency_exponent": 2 },
    "display_total": null,
    "gross_total": null,
    "net_total": null,
    "commission_total": null,
    "agent_reward": null,
    "recommended_selling_total": null,
    "minimum_selling_total": null,
    "original_total": null,
    "discount_total": null,
    "vat": null
  },
  "booking_requirements": [
    {
      "requirement_id": "br_title_all_guests_1",
      "code": "TITLE",
      "label": "Title",
      "value_type": "ENUM",
      "scope": "ALL_GUESTS",
      "room_allocation_ids": [],
      "required": true,
      "allowed_values": ["MR", "MRS", "MS", "MISS", "MASTER", "OTHER"],
      "description": null,
      "constraints": null
    },
    {
      "requirement_id": "br_first_name_all_guests_2",
      "code": "FIRST_NAME",
      "label": "First name",
      "value_type": "TEXT",
      "scope": "ALL_GUESTS",
      "room_allocation_ids": [],
      "required": true,
      "allowed_values": [],
      "description": null,
      "constraints": null
    },
    {
      "requirement_id": "br_last_name_all_guests_3",
      "code": "LAST_NAME",
      "label": "Last name",
      "value_type": "TEXT",
      "scope": "ALL_GUESTS",
      "room_allocation_ids": [],
      "required": true,
      "allowed_values": [],
      "description": null,
      "constraints": null
    },
    {
      "requirement_id": "br_email_lead_guest_4",
      "code": "EMAIL",
      "label": "Email",
      "value_type": "EMAIL",
      "scope": "LEAD_GUEST",
      "room_allocation_ids": [],
      "required": true,
      "allowed_values": [],
      "description": null,
      "constraints": null
    },
    {
      "requirement_id": "br_phone_lead_guest_5",
      "code": "PHONE",
      "label": "Phone",
      "value_type": "PHONE",
      "scope": "LEAD_GUEST",
      "room_allocation_ids": [],
      "required": true,
      "allowed_values": [],
      "description": null,
      "constraints": null
    }
  ],
  "cancellation": {
    "refundability": "PARTIALLY_REFUNDABLE",
    "policy_stage": "INDICATIVE",
    "free_cancellation_until": {
      "local_datetime": "2026-10-10T23:59:59",
      "timezone": "UTC",
      "utc_datetime": "2026-10-10T23:59:59.000Z"
    },
    "policy_text": "Free cancellation until 2026-10-10T23:59:59; penalties may apply afterwards.",
    "penalties": [
      {
        "from": { "local_datetime": "2026-10-11T00:00:00", "timezone": "UTC", "utc_datetime": "2026-10-11T00:00:00.000Z" },
        "to": null,
        "charge_basis": "PERCENTAGE",
        "percentage": 100,
        "number_of_nights": null,
        "native_amount": { "amount_minor": 17346, "currency": "USD", "currency_exponent": 2 },
        "usd_amount": { "amount_minor": 17346, "currency": "USD", "currency_exponent": 2 },
        "conversion_status": "AVAILABLE",
        "description": "Cancellation penalty",
        "calculation_basis": "TOTAL",
        "scope": { "basis": "PER_STAY", "room_allocation_id": null, "guest_type": null, "quantity": null }
      }
    ],
    "no_show": null
  },
  "nightly_prices": [
    {
      "date": "2026-10-12",
      "room_allocation_id": "ra_2c1fb39ed54742f28d95bd8bc5f4375d",
      "amount": { "amount_minor": 5192, "currency": "USD", "currency_exponent": 2 },
      "scope": "ROOM_ALLOCATION",
      "component": "ROOM_RATE"
    },
    {
      "date": "2026-10-13",
      "room_allocation_id": "ra_2c1fb39ed54742f28d95bd8bc5f4375d",
      "amount": { "amount_minor": 5192, "currency": "USD", "currency_exponent": 2 },
      "scope": "ROOM_ALLOCATION",
      "component": "ROOM_RATE"
    },
    {
      "date": "2026-10-14",
      "room_allocation_id": "ra_2c1fb39ed54742f28d95bd8bc5f4375d",
      "amount": { "amount_minor": 5192, "currency": "USD", "currency_exponent": 2 },
      "scope": "ROOM_ALLOCATION",
      "component": "ROOM_RATE"
    }
  ],
  "promotions": [],
  "benefits": [],
  "notices": [
    {
      "code": "city_tax_at_property",
      "severity": "INFO",
      "scope": "PAYMENT",
      "text": "City tax of USD 8.85 is payable at the property.",
      "must_display": true
    }
  ],
  "supplier_terms_and_conditions": null
}

Identity and booking

Field	What it means	How to use it
`offer_id`	Unifystays ID of this offer (`off_…`)	List key. Prebook returns a new offer that replaces it. Not the booking key.
`booking_token`	Opaque signed token for this complete offer	Send it unchanged to Prebook. Never parse, build or edit it. It expires with the offer (`lifecycle.expires_at`, at most 15 minutes after `quoted_at`). Keep it only for the immediate prebook step.
`revision`, `supersedes_offer_id`	`1` and `null` for a room-search offer. After prebook the new offer has the next revision and names the offer it replaces	Replace the old offer, do not merge. Book only the latest prebook `offer_id`.
`offer_family_id`	Shared by offers whose slots are in the same room families in the same order. `null` when any slot is a `tmp_` room	Card key for multi-room searches. Never use it for booking.
`provider_code`	Supplier selling the offer	Display or analytics.
`quote_context`	The search the offer answers: hotel, dates, `nights`, occupancy per room, `residency`, `nationality`, `language`	Check it matches the guest’s search. `hotel.address` is English when a verified supplier address exists; `address_local` holds the original local-script address.
`room_combination.normalized_type`	`SINGLE_ROOM`, `SAME_ROOM_TYPE`, `MIXED_ROOM_TYPES`, `FIXED_COMBINATION`, `OTHER`, `UNKNOWN`	How the rooms are composed. The `rooms` array is always one atomic offer.
`rate_plan`	Rate class (`PUBLIC`, `NEGOTIATED`, `CORPORATE`, `MEMBER`, …) and opaque supplier fields	Use `normalized_type` for logic. `UNKNOWN` is valid; do not assume `PUBLIC`. Show `qualification` when present.

Rooms (one slot per requested room)

Field	What it means	How to use it
`rooms[].room_allocation_id`	Opaque ID of this exact room slot	Keep it with the slot. You will use it in booking guest lists.
`rooms[].unifystays_room_id`, `unifystays_family_id`	Variant (or family for a hotel-assigned bed type) and family of the slot	Look them up in your family store to draw the card. Display only.
`rooms[].provider_room`	The seller’s own room: name, beds, capacity, amenities, images	Show its beds and maximum guests on every offer row. See The seller’s own room.
`rooms[].occupancy`	Adults and child ages you searched for, for this slot	Keep guest assignment compatible with it.
`rooms[].meal_plan`	`code` is `RO`, `BB`, `HB`, `FB`, `AI`, `OTHER` or `UNKNOWN`; also `label`, `is_breakfast_included`	Show `label`. Use `is_breakfast_included` for a breakfast badge.
`rooms[].inclusions[]`	`code` and `label` of things included (for example free WiFi)	Show the `label`s. Treat unknown codes as plain labels.
`rooms[].mapping_status`, `mapping_details`	`MAPPED` (slot is in a built family) or `UNMAPPED` (`tmp_` room); how it was placed	Diagnostics only. They never decide bookability.
`benefits[]`	Extra benefits in the rate (`code`, `label`)	Show as perks.
`promotions[]`	Promotions applied (`code`, `title`, `description`)	Show `title` where relevant.

The price ledger (`pricing`)

All amounts are objects { "amount_minor", "currency", "currency_exponent" }. amount_minor is an integer in minor units: divide by 10^currency_exponent (17346 with exponent 2 is 173.46; a currency with exponent 0, such as JPY, is already whole units). Never treat it as a decimal.

Field	What it means	How to use it
`pricing.native_ledger`	The authoritative price in the supplier’s currency	Source of truth for what is owed. Its lines already add up to its totals.
`pricing.usd_ledger`	The same lines converted to USD. `null` when an exchange rate is missing	Use for USD display or comparison. Lines have `source_amount` (original) and `is_estimated` (true when converted).
`pricing.display_ledger`, `pricing.display_currency`	The same lines converted to your display currency (your organization’s setting or the `X-Unifystays-Currency` header). `null` ledger when a rate is missing	Use to show the guest price in their currency. See Display currency.
`pricing.conversion`	`status` (`AVAILABLE` or `UNAVAILABLE`), `missing_currencies`, `rates`	Check `status` before relying on `usd_ledger`.
`native_ledger.totals[]`	One entry per currency: `payable_to_supplier`, `payable_at_property`, `total`	`payable_to_supplier` is what is settled through the supplier. `payable_at_property` is what the guest pays at the hotel. `total` is the sum of the two.
`lines[].category`	`room_rate`, `tax`, `fee`, `adjustment`, `other`	There is exactly one `room_rate` line. There is no separate base price.
`lines[].normalized_code`, `description`	For example `CITY_TAX`, `RESORT_FEE`, `SERVICE_FEE`, `VAT`	Show `description`. Use `normalized_code` for grouping; new codes can appear.
`lines[].collection_location`	`SUPPLIER` or `PROPERTY`	`PROPERTY` lines are paid by the guest at the hotel. Show them as “pay at hotel”.
`lines[].included_in_quoted_total`	`true` when the supplier’s quoted rate already contains the line, `false` when it is charged on top	Show “included” vs “extra” on the price breakdown.
`lines[].mandatory`	`true` compulsory, `false` optional, `null` unknown	Show optional charges as optional.
`lines[].scope`	`basis`: `PER_STAY`, `PER_ROOM`, `PER_ROOM_PER_NIGHT`, `PER_PERSON`, `PER_PERSON_PER_NIGHT`; plus `room_allocation_id`, `guest_type`, `quantity`	The line amount is already the total for its scope. Do not multiply it again.
`breakdown_status`	`COMPLETE`, `PARTIAL`, `NOT_PROVIDED`, `ESTIMATED`	How detailed the itemisation is.
`price_basis`	`NET`, `GROSS`, `COMMISSIONABLE`, `UNKNOWN`	The supplier’s own declaration.
`nightly_prices[]`	Per-night amounts (`date`, `amount`, `scope`, `component`)	Optional display. Empty when the supplier gives none. The ledger is authoritative.

Never add commercial values to the ledger, and never add a ledger line to payable_to_supplier yourself. If you show one price to the guest, show total and explain which part is paid at the hotel.

Commercial values. commercial holds the supplier’s own reference amounts: supplier_charge_total (what the supplier expects to invoice you), display_total, gross_total, net_total, commission_total, agent_reward, recommended_selling_total, minimum_selling_total, original_total, discount_total and vat. They are informational views and must never be added to any ledger. null means not supplied; zero means the supplier explicitly returned zero. Respect minimum_selling_total when it is set.

Cancellation

Field	What it means	How to use it
`cancellation.refundability`	`REFUNDABLE`, `PARTIALLY_REFUNDABLE`, `NON_REFUNDABLE`, `UNKNOWN`	Badge on the offer row (“Free cancellation”, “Non-refundable”).
`free_cancellation_until`	`local_datetime`, `timezone`, `utc_datetime`; `null` when there is no free window	Show the deadline with its time zone. Use `utc_datetime` for countdown logic.
`penalties[]`	Windows with `from`, `to`, `charge_basis` (`FIXED_AMOUNT`, `PERCENTAGE`, `NIGHTS`, `FULL_STAY`, `UNKNOWN`), `percentage`, `number_of_nights`, `native_amount`, `usd_amount`, `calculation_basis`	Render a timeline. `to: null` means open-ended. `native_amount` is `null` when it cannot be computed: then describe the rule with `percentage` or `number_of_nights`.
`no_show`	`applies_from_local_time` and `penalty`; `null` when not supplied	Show it with the policy. `null` does not mean a no-show is free.
`policy_stage`	`INDICATIVE` (search), `RECHECKED` or `FINAL` (confirmed at prebook)	Show the policy from prebook before the guest pays. It can differ from the search policy.
`policy_text`	Ready-to-show English summary	Fallback text.

Payment

Field	What it means	How to use it
`payment.payer`	`AGENCY` you pay, `GUEST` the guest pays directly, `UNKNOWN`	Decide who is charged in your own system. Unifystays does not collect or settle funds.
`payment.settlement_channel`, `payable_at`	`SUPPLIER_ACCOUNT` or `PROPERTY`; `SUPPLIER` or `PROPERTY`	Where the money goes. Pair with the ledger’s `collection_location`.
`payment.collection_timing`	`AT_BOOKING`, `BEFORE_CHECK_IN`, `AT_CHECK_IN`, `AT_CHECK_OUT`, `ON_INVOICE`, `UNKNOWN`	Tell the guest when payment is due.
`payment.requires_card_data`, `requires_cvc`, `requires_vcc`	Whether a guest card or virtual card is needed	Offers that need a card are never returned, so these are `false`. Each eligible payment choice is a separate offer with its own token.
`payment.security_deposit`	Deposit `amount` and `refundable`, when explicitly supplied	Show to the guest. `null` when none.
`payment.supplier_payment_type`	The supplier’s own label	Informational. Do not branch on it.

Booking requirements

booking_requirements[] lists the guest and booking fields that will be needed at booking. Build your checkout form from it now, so the guest is asked once.

Field	What it means	How to use it
`requirement_id`	Opaque ID bound to this offer	Echo it when you send the answer in the booking request.
`code`	Field code, for example `TITLE`, `FIRST_NAME`, `LAST_NAME`, `EMAIL`, `PHONE`, `GENDER`, `DATE_OF_BIRTH`, `NATIONALITY`, `PASSPORT_NUMBER`, `PASSPORT_COUNTRY`, `PASSPORT_EXPIRY`, `TAX_ID`	Map to your form field. New codes can appear.
`label`, `description`	Text for the field	Show next to the input.
`value_type`	`TEXT`, `EMAIL`, `PHONE`, `DATE`, `ENUM`, `COUNTRY_CODE`, `IDENTIFIER`	Pick the input type.
`scope`	`LEAD_GUEST`, `ALL_GUESTS`, `ADULT`, `CHILD`, `INFANT`	Who must answer.
`room_allocation_ids`	Rooms it applies to; empty for all	Ask only for those rooms.
`required`	Whether an answer is mandatory	Mark required fields.
`allowed_values`	Choices for `ENUM` fields	Build the dropdown.
`constraints`	`min_length`, `max_length`, `pattern` (with `pattern_flags`), `min_age`, `max_age`; may be `null`	Validate on your side. The API checks again.

Prebook returns the requirements again. Use the list from the prebook response for the final form.

Lifecycle

Field	What it means	How to use it
`lifecycle.stage`	`ROOMS` here; `PREBOOK` after prebook	Informational.
`quoted_at`, `expires_at`	When the offer was obtained and when it stops being valid (ISO 8601, UTC)	Show a countdown if you like. After `expires_at`, search again.
`prebook_required`	`true` for room-search offers	Always call Prebook before booking.
`price_guaranteed`	`false` here	The price is confirmed by prebook. Tell the guest the price is final only after prebook.
`availability`, `rooms_remaining`, `on_request`	`AVAILABLE`, `SOLD_OUT`, `ON_REQUEST` or `UNKNOWN`; rooms left when known; `true` when the supplier confirms after booking	Show urgency and “on request” labels.
`available_booking_modes`, `hold_allowed`, `hold_deadline`	Booking modes certified for the offer (`INSTANT`, `HOLD`). `hold_allowed` is `false` at room search	Prebook can add `HOLD`.
`post_booking_actions`	Subset of `STATUS`, `CANCEL`, `CONFIRM_HOLD`	Hide a “cancel” control for offers where `CANCEL` is missing.

Notices and terms

Field	What it means	How to use it
`notices[].text`, `severity`, `scope`	Supplier or legal notices. `severity`: `INFO`, `WARNING`, `REQUIRED`. `scope`: `OFFER`, `ROOM`, `PAYMENT`, `CANCELLATION`, `HOTEL`	Show them near what they describe.
`notices[].must_display`	`true` means the guest must see the text before booking	Always show these, for example on the checkout page.
`supplier_terms_and_conditions`	Full supplier terms with `format` (`PLAIN_TEXT` or sanitised `HTML`) and `text`; `null` when none	You decide where to show them (for example a link at checkout). Escape `PLAIN_TEXT`.

Passport, tax ID, date of birth and nationality rules are declared through booking_requirements; mandatory legal text appears in notices. There is no separate compliance object.

The seller’s own room

rooms[].provider_room is always the seller’s own room, whichever variant or family it is shown under. Show its beds and maximum guests on every offer row, grouped or not. It contains every structured detail the supplier sent.

Field	What it means	How to use it
`name`, `supplier_name`	Display name and the exact supplier name	Show `name`.
`description`, `description_format`	Text, and `HTML` (sanitised, render it) or `TEXT` (escape it)	Render accordingly.
`detail_status`	`NONE` (only id and name), `PARTIAL` (some detail), `COMPLETE` (not used today)	Hide empty sections when `NONE`.
`bed_configurations[]`	Bedding choices: `beds[]` (`type`, `normalized_type`, `quantity`, widths), `bed_count`, `bedroom_count`, `bed_type_guaranteed`, `selected`	`selected: true` is the layout this offer is sold with. `bed_type_guaranteed: true` only when the supplier guarantees it.
`bed_summary`	English text such as “1 king bed”	Short display text.
`occupancy.max_allowed`	Capacity: `total`, `adults`, `children`, `infants`	Show “sleeps N”. It is capacity, not your searched occupancy.
`size`, `room_type`, `room_category`, `bathroom`, `views[]`, `features`, `extra_bed`, `child_bed`	Further attributes	Show what you need.
`amenities[]`, `images[]`	Amenities and photos from the seller	`images[].is_primary` marks the lead image.

null means not known. An empty array means none were supplied. Neither means “no”. bed_configurations: [] means the supplier gave no dependable bedding data; it does not mean the room has no bed. New fields and enum values may be added: ignore what you do not recognise.

Common mistakes

Do not wait for done before showing offers. Render as events arrive.
Do not book with a unifystays_room_id. Book with booking_token.
Do not add commercial fields, or ledger lines, to a price you compute.
Do not reuse a booking_token after lifecycle.expires_at.
Do not keep the connection open after done.
Do not store tmp_ room IDs, or keep any room ID as a long-lived key.

Next step

When the guest picks an offer, call Prebook a Room with its booking_token.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

Last-Event-ID

string

Optional SSE resume cursor. Omit it (or use 0) for the first connection. When reconnecting, send the ID of the last event successfully processed. If that event is no longer retained, the API returns ROOM_STREAM_REPLAY_GAP and a new room search is required.

X-Unifystays-Contract-Version

enum<string>

default:2

Hotel API contract version. Optional: 2 is the current version and the default.

Available options:

2

X-Unifystays-Currency

string

ISO 4217 currency for display amounts (display_ledger, display_amount, commercial_display). Optional: defaults to your organization's display currency, USD unless configured. Read pricing.display_currency in the response.

Required string length: 3

Example:

"EUR"

Path Parameters

hotel_id

string

required

Unifystays hotel ID used to start the room search. It must match the hotel the stream was created for, otherwise the stream is reported as not found.

Example:

"123456"

stream_id

string

required

Room stream ID (data.stream_id) returned by POST /hotels/{hotel_id}/rooms. A stream lives for about 45 seconds of searching and is kept for about 2 minutes after its done event.

Example:

"stream_8f4b9d1f6d9e"

Response

Room stream not found, expired, or belongs to another hotel.

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

How a search runs

Events

`provider_options`

`done`

Time limits and partial results

Reconnect with `Last-Event-ID`

Family objects on `provider_options`

The offer (`HotelOffer`)

Identity and booking

Rooms (one slot per requested room)

The price ledger (`pricing`)

Cancellation

Payment

Booking requirements

Lifecycle

Notices and terms

The seller’s own room

Common mistakes

Next step

Authorizations

Headers

Path Parameters

Response

​How a search runs

​Events

​provider_options

​done

​Time limits and partial results

​Reconnect with Last-Event-ID

​Family objects on provider_options

​The offer (HotelOffer)

​Identity and booking

​Rooms (one slot per requested room)

​The price ledger (pricing)

​Cancellation

​Payment

​Booking requirements

​Lifecycle

​Notices and terms

​The seller’s own room

​Common mistakes

​Next step

Authorizations

Headers

Path Parameters

Response

How a search runs

Events

`provider_options`

`done`

Time limits and partial results

Reconnect with `Last-Event-ID`

Family objects on `provider_options`

The offer (`HotelOffer`)

Identity and booking

Rooms (one slot per requested room)

The price ledger (`pricing`)

Cancellation

Payment

Booking requirements

Lifecycle

Notices and terms

The seller’s own room

Common mistakes

Next step