Get Search Price Updates

curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Price refresh status fetched",
  "data": {
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "status": "REFRESHING",
    "expires_at": "2026-10-01T09:45:00.000Z",
    "total_hotels": 3,
    "hotels": [
      {
        "hotel_id": "123456",
        "price": {
          "amount": 27900,
          "currency": "USD",
          "rate_type": "live",
          "status": "live",
          "reason": null,
          "fetched_at": "2026-10-01T09:30:08.000Z",
          "supplier_code": "TRIPJACK",
          "is_refundable": false,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": true,
            "free_cancellation_until": "2026-10-25T23:59:59.000Z",
            "fetched_at": "2026-10-01T09:30:02.000Z"
          },
          {
            "hotel_id": "123456",
            "supplier_code": "TRIPJACK",
            "supplier_name": "Tripjack",
            "amount": 27900,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": false,
            "free_cancellation_until": null,
            "fetched_at": "2026-10-01T09:30:08.000Z"
          }
        ]
      },
      {
        "hotel_id": "789012",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "checking",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      },
      {
        "hotel_id": "345678",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "no_price",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      }
    ]
  }
}

GET

hotels

{searchId}

prices

curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

{
  "contract_version": "2",
  "success": true,
  "message": "Price refresh status fetched",
  "data": {
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "status": "REFRESHING",
    "expires_at": "2026-10-01T09:45:00.000Z",
    "total_hotels": 3,
    "hotels": [
      {
        "hotel_id": "123456",
        "price": {
          "amount": 27900,
          "currency": "USD",
          "rate_type": "live",
          "status": "live",
          "reason": null,
          "fetched_at": "2026-10-01T09:30:08.000Z",
          "supplier_code": "TRIPJACK",
          "is_refundable": false,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": true,
            "free_cancellation_until": "2026-10-25T23:59:59.000Z",
            "fetched_at": "2026-10-01T09:30:02.000Z"
          },
          {
            "hotel_id": "123456",
            "supplier_code": "TRIPJACK",
            "supplier_name": "Tripjack",
            "amount": 27900,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": false,
            "free_cancellation_until": null,
            "fetched_at": "2026-10-01T09:30:08.000Z"
          }
        ]
      },
      {
        "hotel_id": "789012",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "checking",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      },
      {
        "hotel_id": "345678",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "no_price",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      }
    ]
  }
}

Search Hotels returns quickly, and some cards come back with price.status = "checking" because suppliers are still being asked. This endpoint is how those cards get their prices. Call it every 2 seconds while the result page is visible. Each response has the current price and supplier_prices of every hotel in the search session, in the same shape and with the same rules as the search cards. Only the organization that ran the search can poll it. Any other caller gets 404.

When to call it

Start when the search response has data.refresh_status = "PENDING". If it is NA, the prices you already have are final for this search and you do not need to poll.
Poll every 2 seconds, and only while the customer is looking at the results. Stop when they leave the page.
Stop as soon as data.status is COMPLETE or EXPIRED. Apply that last response first.
Any card can change between polls while data.status is PENDING or REFRESHING: checking becomes priced, no_price or unpriced, and a priced card can drop to a lower amount when a cheaper supplier answers.

Request examples

curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

To prioritize the cards on screen, pass up to 50 comma-separated hotel IDs as refresh_ids:

curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices?refresh_ids=123456,789012" \
  -H "x-api-key: $UNIFYSTAYS_API_KEY"

Parameter	What it means	How to use it
`searchId` (path)	`data.search_id` from the search response.	Valid for about 5 minutes from the search. Unknown, expired or other-organization IDs return 404.
`refresh_ids` (query, optional)	Comma-separated hotel IDs (max 50) that are on screen right now.	Send the IDs in the viewport, for example when the guest scrolls or opens page 2. Hotels without a fresh price are queued for the supplier refresh and the `searchId` stays valid for 5 more minutes. Hotels that are already fresh are skipped.

Update the result list

Keep the search ID

Save data.search_id from the search response.

Poll every 2 seconds

Poll while results are visible. Add refresh_ids for the hotels in the viewport when the guest scrolls.

Replace each card's price

For every entry in data.hotels, find the card with the same hotel_id and replace its price and supplier_prices. Replace, do not merge: the entry is the full current state. Ignore entries for hotels you do not display (the session can include hotels just beyond the page).

Stop the loop

Keep polling while data.status is PENDING or REFRESHING. Stop on COMPLETE, EXPIRED, or when the customer leaves.

async function pollPrices(searchId, cardsById, visibleIds) {
  while (true) {
    const qs = visibleIds().length ? `?refresh_ids=${visibleIds().slice(0, 50).join(",")}` : "";
    const res = await fetch(`${BASE}/hotels/search/${searchId}/prices${qs}`, {
      headers: { "x-api-key": KEY },
    });
    if (res.status === 404) return "restart_search"; // search_id expired
    const { data } = await res.json();
    for (const h of data.hotels) {
      const card = cardsById.get(h.hotel_id);
      if (card) { card.price = h.price; card.supplier_prices = h.supplier_prices; }
    }
    if (data.status === "COMPLETE" || data.status === "EXPIRED") return data.status;
    await new Promise((r) => setTimeout(r, 2000));
  }
}

Keep the server’s order of the list. Updating prices in place does not change positions.

Response example

{
  "contract_version": "2",
  "success": true,
  "message": "Price refresh status fetched",
  "data": {
    "search_id": "srch_a1b2c3d4e5f6g7h8",
    "status": "REFRESHING",
    "expires_at": "2026-10-01T09:45:00.000Z",
    "total_hotels": 3,
    "hotels": [
      {
        "hotel_id": "123456",
        "price": {
          "amount": 27900,
          "currency": "USD",
          "rate_type": "live",
          "status": "live",
          "reason": null,
          "fetched_at": "2026-10-01T09:30:08.000Z",
          "supplier_code": "TRIPJACK",
          "is_refundable": false,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": [
          {
            "hotel_id": "123456",
            "supplier_code": "REZLIVE",
            "supplier_name": "RezLive",
            "amount": 28500,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": true,
            "free_cancellation_until": "2026-10-25T23:59:59.000Z",
            "fetched_at": "2026-10-01T09:30:02.000Z"
          },
          {
            "hotel_id": "123456",
            "supplier_code": "TRIPJACK",
            "supplier_name": "Tripjack",
            "amount": 27900,
            "currency": "USD",
            "rate_type": "live",
            "is_refundable": false,
            "free_cancellation_until": null,
            "fetched_at": "2026-10-01T09:30:08.000Z"
          }
        ]
      },
      {
        "hotel_id": "789012",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "checking",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      },
      {
        "hotel_id": "345678",
        "price": {
          "amount": null,
          "currency": "USD",
          "rate_type": null,
          "status": "no_price",
          "reason": null,
          "fetched_at": null,
          "supplier_code": null,
          "is_refundable": null,
          "free_cancellation_until": null,
          "sort_basis": null
        },
        "supplier_prices": []
      }
    ]
  }
}

Response field guide

Field	What it means	How to use it
`data.search_id`	The session being polled.	Echo.
`data.status`	`PENDING` or `REFRESHING`: suppliers are still being asked, keep polling. `COMPLETE`: all suppliers answered. `EXPIRED`: the refresh session has run out of time or was abandoned.	Stop on `COMPLETE` or `EXPIRED` after applying the response. After `EXPIRED`, search again if you need fresh prices.
`data.expires_at`	ISO time after which the `search_id` stops working (404).	Sending `refresh_ids` extends it by 5 minutes.
`data.total_hotels`	Number of entries in `data.hotels`.	Can exceed the number of cards you display.
`data.hotels[].hotel_id`	Hotel ID.	Match to your card.
`data.hotels[].price`	Price state of the hotel, same object as on the search card.	Replace the card’s `price`.
`data.hotels[].supplier_prices`	Every live supplier quote received so far (empty until one arrives).	Replace the card’s list.

price fields are the ones described in Search Hotels: status, amount (minor units of currency, whole stay), currency, supplier_amount, supplier_currency, rate_type, reason, fetched_at, supplier_code, is_refundable, free_cancellation_until. In poll responses sort_basis is always null.

What to show for each status

price.amount is a number only when price.status is live or recent, a real supplier quote for this exact search. Otherwise it is null.

`price.status`	Meaning	What to do
`live`	A supplier quote was received during this search.	Show `price.amount`.
`recent`	A stored quote from your account for the same dates, rooms, guests and nationality, at most about 3 hours old.	Show `price.amount`.
`checking`	Suppliers are still being asked.	Show a spinner. Keep polling.
`no_price`	Suppliers answered with no availability. It will not get a number.	Show “sold out” for these dates. Badge, deprioritize or hide.
`unpriced`	No price could be obtained; `price.reason` says why.	Show “unavailable”. Offer a retry (repeat the search) unless `reason` is `not_mapped`.

price.reason is null unless the status is unpriced, then one of not_mapped, supplier_error, timeout, not_queried, no_result. Treat an unknown status as no price. A hotel can move from checking to any other status. A live or recent hotel can get a lower price.amount when a cheaper supplier answers later, so re-render the amount on every update.

Several suppliers

supplier_prices can hold several quotes for the same hotel_id with different supplier_code values. price shows the lowest. Unifystays returns every quote, so your integration decides which one to display: lowest, latest or a preferred supplier. Quotes are in minor units of their currency, the same display currency as the search, and each carries the supplier’s own supplier_amount and supplier_currency. Contract v1 polls (updated_prices) are presented in the display currency too. A hotel you already showed is never removed from your list by a poll; only its card changes state.

Common mistakes

Polling forever. Stop on COMPLETE or EXPIRED.
Polling faster than every 2 seconds, or while the page is hidden.
Merging poll prices into the old object instead of replacing price and supplier_prices.
Treating a missing hotel in the poll as sold out. Only no_price means sold out.
Continuing to use a search_id after a 404. Run the search again.

How no-price history affects later searches

No-price history is isolated by account, environment and the exact set of suppliers enabled for it. It never affects another account’s search.

After a completed no-price result, the same hotel and exact stay may be left out of a new search for 30 minutes.
A hotel may be left out more broadly after no-price results on at least three distinct check-in dates in the previous 14 days.
A later live price clears that history.
Enabling or disabling a supplier starts a new supplier scope, so older history from a different set is not used.
Supplier failures and timeouts do not count as no-price evidence.

This only applies when a new search is made. For the current search you stay in control of how each no_price hotel appears.

Next step

When the guest picks a hotel, call Get Hotel Rooms for bookable offers. The OpenAPI section below contains every status value, parameter and the exact payload.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

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

searchId

string

required

Search session ID from data.search_id of the Search Hotels response. Valid for about 5 minutes from the search; unknown, expired or other-organization IDs return 404.

Example:

"srch_a1b2c3d4e5f6g7h8"

Query Parameters

refresh_ids

string

Optional comma-separated hotel IDs (max 50) that are on screen right now, for example the hotels in the viewport. Hotels without a fresh price are queued for the supplier refresh, and the search_id stays valid for 5 more minutes. Hotels that are already fresh are skipped.

Example:

"15419351,15312010"

Response

One price object per hotel of the session, plus every supplier quote received so far.

contract_version

string

required

Response contract version. Always 2.

Example:

"2"

success

boolean

required

True when the request succeeded.

Example:

true

message

string

required

Human-readable status. Do not parse.

Example:

"Price refresh status fetched"

data

object

required

Current prices for the search session.

Show child attributes

Overview

Destination & master data

Search & hotels

Bookings

Webhook endpoints

Webhook logs

When to call it

Request examples

Update the result list

Response example

Response field guide

What to show for each status

Several suppliers

Common mistakes

How no-price history affects later searches

Next step

Authorizations

Headers

Path Parameters

Query Parameters

Response

​When to call it

​Request examples

​Update the result list

​Response example

​Response field guide

​What to show for each status

​Several suppliers

​Common mistakes

​How no-price history affects later searches

​Next step

Authorizations

Headers

Path Parameters

Query Parameters

Response

When to call it

Request examples

Update the result list

Response example

Response field guide

What to show for each status

Several suppliers

Common mistakes

How no-price history affects later searches

Next step