# Hotel rate types filter

The [hotel search](/openapi/hotelapi/hotel/hotelsearch) and [hotel details](/openapi/hotelapi/hotel/hoteldetails) APIs each use a `filters` > `rateTypes` field to filter the results based on a specific hotel rate type (e.g., corporate rates).

This guide explains this filter in detail and how to use it in an API call.

## Hotel search vs hotel details APIs

The [hotel search](/openapi/hotelapi/hotel/hotelsearch) API lists all available hotel properties based on the search parameters. If you wish to further restrict the hotel results, include a qualified `rateTypes` filter (e.g., *Government rates*). See [rate type groups](#rate-type-groups) to understand the difference between standard rate type and qualified rate type filters.

The [hotel details](/openapi/hotelapi/hotel/hoteldetails) API is used to view the rates and property details (e.g., amenities) for one specific property. This API is called after [hotel search](/openapi/hotelapi/hotel/hotelsearch) to get more details about a specific property selected by the traveler (see [hotel booking workflow](/spotnana/hotel_booking_workflow)). In the [hotel details](/openapi/hotelapi/hotel/hoteldetails) API, using the `rateTypes` filter will list all the matching rates offered by that specific property.

## Rate type values

The following are the different values supported in the `rateTypes` filter:

| Value  | Group  | Description |
|  --- | --- | --- |
| `PUBLISHED` | Standard | The retail rate set by the property for all travelers. |
| `CORPORATE` | Standard | A rate negotiated by your company for its travelers. |
| `SPOTNANA` | Standard | A rate negotiated by Spotnana for its partner organizations. |
| `TMC` | Standard | A rate negotiated by a Travel Management Company (TMC) for its customer organizations. |
| `BEST_AVAILABLE_RATE` | Standard | The lowest publicly available rate during the requested dates. |
| `REGULAR` | Standard | A generic value that includes all the standard group rate types. |
| `AAA` | Qualified | A discounted rate for members of the American Automobile Association (AAA). |
| `AARP` | Qualified | A discounted rate for members of the American Association for Retired Persons (AARP). |
| `SENIOR_CITIZEN` | Qualified | A discounted rate for travelers who meet the property's minimum age requirement for senior rates. |
| `GOVERNMENT` | Qualified | A discounted rate for government employees. |
| `MILITARY` | Qualified | A discounted rate for military personnel. |
| `MEMBERSHIP` | Qualified | A rate available to members of the loyalty program offered by the property. |


## Rate type groups

The `rateTypes` values form two groups, standard rate types and qualified rate types. The group determines how a value behaves in `filters` > `rateTypes`.

### Standard rate types

Standard rate types are included in a hotel search result by default. Additionally, if the [hotel search](/openapi/hotelapi/hotel/hotelsearch) API call includes any of the standard rate types (e.g., `PUBLISHED`), the search result will include all the standard rate types.

The following are the standard rate types in the `filters` > `rateTypes` filter:

- `PUBLISHED`
- `CORPORATE`
- `SPOTNANA`
- `TMC`
- `BEST_AVAILABLE_RATE`
- `REGULAR`


### Qualified rate types

Qualified rate types are discounted rates that require traveler eligibility (e.g., AAA member rate). The following are the different qualified rate types:

- `AAA`
- `AARP`
- `SENIOR_CITIZEN`
- `GOVERNMENT`
- `MILITARY`
- `MEMBERSHIP`


**Notes:**

- If you're selecting a `MEMBERSHIP` rate, you'll be required to provide the loyalty membership number during checkout.
- For all the other qualified rate types there is no such requirement during checkout. Instead, the property may verify the eligibility at check-in, and if requested, travelers must present proof (e.g., if you booked a AAA rate, you may be asked to present the AAA membership card).


### Combining the filter types

The standard and qualified rate type filters can be combined to provide more granular results. However, the combined use of these filters behaves differently in the [hotel search](/openapi/hotelapi/hotel/hotelsearch) and [hotel details](/openapi/hotelapi/hotel/hoteldetails) APIs. These differences are explained below:

- Qualified rate types can be combined in a [hotel search](/openapi/hotelapi/hotel/hotelsearch) API request. For example, if the `rateTypes` is set to `["GOVERNMENT", "MILITARY"]`, then properties offering government rates and properties offering military rates are shown in the search result.
- In the [hotel search](/openapi/hotelapi/hotel/hotelsearch) API, qualified rate types take precedence. When the list contains both standard and qualified rate types, the response will return only the qualified rates specified in the filter. Negotiated rates (corporate, TMC, and Spotnana rates) are not retrieved for that search. For example, if `rateTypes` is set to `["CORPORATE", "AAA"]`, the results will contain only the properties offering `AAA` rates. To view a property's standard rates, call the [hotel details](/openapi/hotelapi/hotel/hoteldetails) API.
- In the [hotel details](/openapi/hotelapi/hotel/hoteldetails) API, standard and qualified values combine as one list. For example, if `rateTypes` is set to `["CORPORATE", "AAA", "AARP"]`, the response will contain the selected property's AAA and AARP rates along with all of its standard rates. In this scenario, the senior citizen, government, and military rates are not returned in the response.


## Filtering rate types in the hotel search API

If the optional `filters` > `rateTypes` is omitted from the [hotel search](/openapi/hotelapi/hotel/hotelsearch) API then the results will contain published rates and all negotiated rates (corporate, TMC, and Spotnana rates) available to the traveler. Including a single standard rate type, for example `["CORPORATE"]`, returns the same results as omitting the `filters` > `rateTypes` field (i.e., the response contains all standard rates).

However, qualified rate types narrow the search results. The response will contain only properties that have at least one rate matching a qualified rate type in the list. Such a search typically returns fewer properties than an unfiltered search, because qualified rate availability varies by property.

Here's a sample [hotel search](/openapi/hotelapi/hotel/hotelsearch) API request with *qualified* rate type filters:


```json POST /v2/hotel/search
{
  // ... payload truncated for focus
  "filters": {
    "rateTypes": ["GOVERNMENT", "MILITARY"]
  }
}
```

In the above scenario, a property is returned if it offers a government rate, a military rate, or both. Properties that don't offer a government rate or a military rate are not returned in the search results.

**Note:** [Hotel search](/openapi/hotelapi/hotel/hotelsearch) returns one price for each property, which is the lowest-priced rate among the rates the search retrieved. This price does not always match the `rateTypes` filter in the request. For example, when the filter is set to `["AAA"]`, a property appears in the results only if it offers an `AAA` rate. However, the displayed price can come from a lower-priced standard rate that was retrieved alongside the `AAA` rates. Use the [hotel details](/openapi/hotelapi/hotel/hoteldetails) API to view the property's offered rates and their `rateType` values (all standard rates *and* the AAA rates) before presenting a specific rate to the traveler.

## Filtering rate types in the hotel details API

In the [hotel details](/openapi/hotelapi/hotel/hoteldetails) API, including a standard rate type filter (e.g., `CORPORATE`) will return all the standard rates for the specific hotel. When you include a qualified rate type filter (e.g., `AAA`), the response contains only the rates of that type.

The following table explains the rates returned in the response when using a qualified rate type filter:

| Value provided in the list  | Rates returned in the response |
|  --- | --- |
| `AAA` or `AARP` | Both AAA and AARP rates are returned for either of the values. |
| `SENIOR_CITIZEN` | Senior citizen rates. |
| `GOVERNMENT` | Government rates. |
| `MILITARY` | Military rates. |
| `MEMBERSHIP` | Loyalty program member rates. |


Combining a standard and a qualified rate type filter will return all the matching rates for a specific property. For example, `["MEMBERSHIP", "CORPORATE"]` returns loyalty program member rates along with *all* standard rate types.

## Booking a membership rate

If you book a loyalty program member rate (i.e., if `rateTypes` is set to `MEMBERSHIP` and the corresponding membership rate is booked), you must include the traveler's membership number during checkout. The booking will fail (with an error) when the membership number is absent. See the [hotel loyalty programs](/guides/hotel_guides/hotel_loyalty_guide) guide for how to attach loyalty details.