> ## 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.

# 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](/api-reference/destination-autocomplete) | Cache successful responses for **48 hours**.                | Include environment, language, normalized `q`, `types`, `city_id`, and `limit`. |
| [Nationalities](/api-reference/nationalities)                       | Cache successful responses for **30 days**.                 | Include environment, language, search, sorting, page, and limit.                |
| [Hotel filters](/api-reference/hotel-filters)                       | Unifystays caches the destination response for 24 hours.    | Request exactly one of `place_id`, `city_id`, or `hotel_id`.                    |
| [Hotel content](/api-reference/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:

```text theme={null}
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.

```text theme={null}
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

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

* For a customer-facing result page, use `pricing_mode: "instant"` and poll
  [Get Search Price Updates](/api-reference/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](/errors)