Skip to main content
Caching makes your integration faster and keeps you well below your rate limit. But the API returns two very different kinds of data. Reference data changes slowly and is safe to cache. Live shopping and booking data (prices, offers, tokens, booking status) is time-sensitive and must be fetched fresh.

​
At a glance

​
Cache this

​
Autocomplete: up to 48 hours

Cache only successful responses. Trim and lowercase q before building the key:
Hotel suggestions depend on the suppliers enabled for your organization, so never share this cache across organizations, and clear it when you change supplier connections in the portal. Debounce type-ahead requests (200 to 300 ms) and start at 3 characters; shorter queries return an empty list. Do not cache errors or empty results from a failed call.

​
Nationalities: up to 30 days

Request the full list once with limit=250, cache data.items, and filter it locally in your guest form. Use the pagination metadata only if data.meta.totalPages is above 1.
Send the iso_code from the refreshed list in later requests. Do not cache authentication, validation or server-error responses.

​
Hotel filters: until cached_until

The server caches each destination’s filter payload for 24 hours and tells you when it will be rebuilt in data.cached_until. Cache it until then. Counts describe the catalogue, not live availability, so they are fine to cache. Request exactly one of place_id or hotel_id.

​
Hotel content: your own expiry

Content comes from the Unifystays catalogue, never from a supplier call, and has no price or availability. Cache it by hotel_id. The response does not say when the content last changed, so pick an expiry that suits your product (a few hours to a day is a good default). Photos are plain URLs; treat them as opaque.

​
Never cache this

A cache is a performance tool, not a reservation guarantee. Prices, room options and prebook results change as suppliers update availability.
  • Search prices. price.amount is a supplier quote for one exact search (dates, rooms, guests, nationality). A recent price is already a stored quote at most about 3 hours old. Never use a stored price as a booking price. Poll Search Price Updates every 2 seconds while results are visible, and stop on COMPLETE or EXPIRED.
  • Room offers and booking_token. Request rooms again whenever the hotel, dates, guest mix or nationality changes, and when a token expires. Do not reuse a token from an earlier request.
  • Room and family IDs. unifystays_room_id and unifystays_family_id are for display and grouping in the current search. A tmp_ ID is valid for that search only, and a built ID can be retired later. Do not keep them as long-lived keys.
  • prebooking_id and offer_id. Prebook when checkout starts. Repeating a prebook with the same token returns the stored result and does not contact the supplier, so it will not show a newer price. Get a new token for a fresh check.
  • Cancellation quotes. Request a new quote when the guest asks to cancel.
  • Booking status. Read it after booking, after cancelling, and when a webhook arrives. A webhook payload is a snapshot; use data.object.version to order events and read the booking when you need the latest state.

​
Rules that apply everywhere

  • Keep Sandbox and Production caches fully separate. IDs are environment-specific.
  • Cache only successful responses (2xx). Never cache 4xx or 5xx.
  • Include in the key everything that changes the answer (for example organization and supplier set for autocomplete).
  • Combine identical in-flight requests: one lookup per key, not one per user.
  • On any 404 or expiry for a search, stream or token, discard the cached state and start the step again. See Errors & Retries.
See the full time limits