Caching Strategy

Cache stable reference data efficiently while keeping hotel prices and booking availability current.

Caching makes an integration faster and reduces unnecessary API traffic, but not every hotel API response has the same freshness requirements. Separate stable reference data from supplier-backed availability and booking state.

Recommended Cache Policy

Data	Cache policy	Key requirements
Destination autocomplete	Cache successful responses for 48 hours.	Include environment, language, normalized q, types, city_id, and limit.
Nationalities	Cache successful responses for 30 days.	Include environment, language, search, sorting, page, and limit.
Hotel filters	Unifystays caches the destination response for 24 hours.	Request exactly one of place_id, city_id, or hotel_id.
Hotel content	Cache according to your product’s content-freshness policy.	Content is static and not a price or availability guarantee.
Hotel search prices	Do not use a stale price as a booking guarantee.	Use the search price refresh endpoint for live updates.
Room options and prebooking	Treat as time-sensitive.	Request fresh data for the selected stay before checkout.
Booking status	Treat as current state.	Poll the booking status endpoint after create or cancel operations.

Autocomplete: 48 Hours

Cache only successful autocomplete responses. Normalize q by trimming whitespace and converting it to lowercase before building the key:

environment + language + normalized q + types + city_id + limit

Keep city-scoped hotel searches separate from an unscoped query. The same text can return a different response when city_id is present. Debounce type-ahead requests and start after the minimum query length accepted by the endpoint.

Nationalities: 30 Days

For a typical guest form, request the default list with limit=250, cache the successful data.items, then filter the cached list locally. Use the pagination metadata only when more pages are available.

environment + language + search + sort_by + sort_order + page + limit

Use iso_code from the refreshed list for later shopping requests. Do not cache authentication, validation, or server-error responses.

Live Shopping and Checkout

A cache is a performance tool, not a reservation guarantee. Hotel prices, room options, and prebooking results can change as suppliers update availability.

• For a customer-facing result page, use pricing_mode: "instant" and poll Get Search Price Updates every two seconds while results are visible.
• Stop the polling loop when the refresh reports COMPLETE or EXPIRED.
• Do not reuse an expired booking_token or prebooking ID. Restart from room options or hotel search when necessary.
• Keep sandbox and production cache entries fully separate.

See retry behavior