> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Search Price Updates
> Poll a search session for fresh supplier prices and merge them into a visible result list.
After an `instant` hotel search, call this endpoint every two seconds while the
customer is viewing the result page. It returns the hotel prices that have
become fresh since the search response.
## Request Example
```bash theme={null}
curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices" \
-H "x-api-key: $UNIFYSTAYS_API_KEY" \
-H "language: en"
```
To prioritize hotel cards currently on screen, pass up to 50 comma-separated
hotel IDs in `refresh_ids`:
```bash theme={null}
curl "$UNIFYSTAYS_BASE_URL/hotels/search/srch_a1b2c3d4e5f6g7h8/prices?refresh_ids=123456,789012" \
-H "x-api-key: $UNIFYSTAYS_API_KEY" \
-H "language: en"
```
## Update the Result List
Save `data.search_id` from the original hotel search response.
Poll every two seconds only while the customer is actively viewing the
search results.
Replace the matching hotel card data using each `updated_prices` item and
its `hotel_id`, then reapply the current sort order.
Stop polling when `data.status` is `COMPLETE` or `EXPIRED`, or when the
customer leaves the result page.
## Response Example
```json theme={null}
{
"success": true,
"message": "Price refresh status fetched",
"data": {
"search_id": "srch_a1b2c3d4e5f6g7h8",
"status": "REFRESHING",
"refresh_count": 8,
"total_hotels": 20,
"updated_prices": [],
"no_price_hotel_ids": []
}
}
```
`no_price_hotel_ids` identifies hotels whose live supplier requests returned no
price for the stay. Your UI can badge, deprioritize, or remove them according
to the product experience.
The OpenAPI section below contains all status values, request parameters, and
the precise update payload.
## OpenAPI
````yaml reference/openapi.json GET /hotels/search/{searchId}/prices
openapi: 3.0.0
info:
title: Unifystays API
description: >-
One unified hotel API across suppliers. Integrate once, then enable and
manage suppliers from the Unifystays portal.
version: '1.0'
contact: {}
servers:
- url: https://api-sandbox.unifystays.com
description: Sandbox
- url: https://api.unifystays.com
description: Production
security:
- x-api-key: []
tags: []
paths:
/hotels/search/{searchId}/prices:
get:
tags:
- Hotels
summary: Poll for fresh prices from a previous search
description: >-
Poll every 2s after a search response. Returns hotels that now have live
provider prices (FRESH). Merge updated_prices into your search results
by hotel_id and re-sort. Stop polling when status = COMPLETE or EXPIRED.
Optional refresh_ids (comma-separated, max 50): request live prices for
specific hotels — e.g. the page currently in the viewport. Stale ids
merge into the background refresh (extends the poll window 5 min);
already-fresh ids are skipped.
operationId: HotelSearchController_getPriceRefreshStatus
parameters:
- name: searchId
required: true
in: path
schema:
type: string
example: srch_a1b2c3d4e5f6g7h8
- name: refresh_ids
required: false
in: query
description: Comma-separated hotel ids to refresh on demand (max 50).
schema:
example: 15419351,15312010
type: string
- name: language
description: Enter language code(ex. en)
in: header
schema: {}
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPriceRefreshResponseDto'
'404':
description: Entity not found
components:
schemas:
SearchPriceRefreshResponseDto:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Price refresh status fetched
data:
$ref: '#/components/schemas/SearchPriceRefreshDataDto'
required:
- success
- message
- data
SearchPriceRefreshDataDto:
type: object
properties:
search_id:
type: string
example: srch_a1b2c3d4e5f6g7h8
status:
type: string
example: REFRESHING
description: >-
PENDING = queued, REFRESHING = provider fetch in progress, COMPLETE
= done, EXPIRED = session gone.
enum:
- PENDING
- REFRESHING
- COMPLETE
- EXPIRED
refresh_count:
type: number
example: 8
description: Hotels in this search that received fresh provider prices.
total_hotels:
type: number
example: 20
description: Total non-fresh hotels enqueued for this search.
updated_prices:
description: >-
Hotels with updated fresh prices. Merge into your search results by
hotel_id.
type: array
items:
$ref: '#/components/schemas/RefreshedHotelPriceDto'
expires_at:
type: object
example: '2026-04-17T10:05:00.000Z'
description: ISO timestamp when this session expires.
no_price_hotel_ids:
example:
- '123456'
- '789012'
description: >-
Hotels queried live this session that returned no price — sold out
or unavailable; client should badge or deprioritize
type: array
items:
type: string
required:
- search_id
- status
- refresh_count
- total_hotels
- updated_prices
- no_price_hotel_ids
RefreshedHotelPriceDto:
type: object
properties:
hotel_id:
type: string
example: '123456'
amount:
type: number
example: 28500
description: Updated total price in USD cents.
currency:
type: string
example: USD
rate_type:
type: string
example: live
enum:
- live
description: >-
Always 'live' — poll updates carry real supplier rates. Matches
search price.rate_type.
is_refundable:
type: object
example: true
description: Refundability of the cheapest live rate; null if unknown.
free_cancellation_until:
type: object
example: '2026-08-25T23:59:59.000Z'
description: Free-cancellation deadline (ISO); null if unknown/non-refundable.
required:
- hotel_id
- amount
- currency
- rate_type
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: Environment-specific API key created in the Unifystays portal
````