---
title: "Batch rates by check-in date"
method: POST
path: "/hotels/rates/batch"
tags: ["Hotel rates"]
---

# Batch rates by check-in date

`POST /hotels/rates/batch`

## Request

- Base URL: `https://api.liteapi.travel/v3.0`
- URL: `https://api.liteapi.travel/v3.0/hotels/rates/batch`
- Auth: API key in header `X-API-Key`

## Overview

Enterprise-only endpoint that prices every length of stay (LOS) × occupancy combination for a single check-in across up to 200 hotels. LOS is the number of nights between check-in and check-out. Returns an NDJSON stream (one hotel object per line) so you can process results as they arrive.

## When to Use

- **Build a LOS matrix** for a check-in date across many hotels without calling `/hotels/rates` repeatedly
- **Compare occupancy options** (e.g. 2 adults vs 2 adults + child) for the same stay window

## What You Get

- **One NDJSON line per hotel** with every LOS × occupancy cell exactly once
- **Trimmed rates** — cheapest RFN (free-cancel until checkin−N days, default N=5) and cheapest NRFN per `mappedRoomId` × feed
- **Prebookable `offerId` values** — same booking flow as `/hotels/rates`
- **Per-cell status** — `ok`, `no_availability`, or `error` with a machine-readable code

## Key Features

- **Inclusive LOS range** via `lengthsOfStay.min` / `lengthsOfStay.max` (max 28 nights)
- **Up to 8 occupancy options** priced independently (not multi-room in one booking)
- **Multi-feed support** with the same `feed` / `feeds` rules as `/hotels/rates`
- **Configurable trim depth** via `maxRatesPerHotel` (default 10 rates requested per cell before RFN/NRFN trim)
- **Refundable deadline control** via `refundableDeadlineDaysBeforeCheckin` (default 5; set 0 to disable)

## Quick Start

**Required fields**: `hotelIds`, `checkin`, `lengthsOfStay`, `occupancies`, `currency`, `guestNationality`

**Tip**: Start with a small LOS range (e.g. min=1, max=2) and one occupancy while integrating. Enable `roomMapping` when you need `mappedRoomId` for room content.

**Rate limit**: Each call costs `losCount × occupancyCount × feedCount` against your API key quota. Check the `X-RateLimit-Cost` response header.

## Request body

- object
  - `hotelIds` string[], required: Hotel LP IDs. Maximum 200 per request.
  - `checkin` string, date, required: Exactly one check-in date per call.
  - `lengthsOfStay` object, required: Inclusive length of stay (LOS) range in nights. Covers every checkout from checkin+min to checkin+max. Max 28.
    - `min` integer, required: Minimum length of stay in nights (inclusive). Must be less than or equal to max.
    - `max` integer, required: Maximum length of stay in nights (inclusive). Must be greater than or equal to min.
  - `occupancies` object[], required: Occupancy options priced separately (not rooms in one booking).
    - `adults` integer, required: Number of adults for this occupancy option.
    - `children` integer[]: Ages of children for this occupancy option.
  - `currency` string, required: The currency in which the prices will be displayed.
  - `guestNationality` string, required: The guest's nationality in ISO 2-letter country code format.
  - `roomMapping` boolean: Enable room mapping to retrieve the mappedRoomId for each room. This allows you to link a rate to its specific room by combining it with hotel details, providing access to room images and additional information
  - `feeds` string[]: Optional multi-feed list (same rules as /hotels/rates).
  - `feed` string: Optional single feed (mutually exclusive with feeds).
  - `timeout` number: Per-cell supplier timeout in seconds. Default 30.
  - `maxRatesPerHotel` integer: Optional override for how many rates each LOS×occupancy cell requests before RFN/NRFN trim. Default 10.
  - `refundableDeadlineDaysBeforeCheckin` integer: RFN rates must remain free to cancel until checkin minus this many days. Default 5 (Airbnb sellable refundable window). Set 0 to disable the deadline filter.

## Response `200`

NDJSON stream: one hotel JSON object per line. `X-RateLimit-Cost` is the projected request count charged against the API key quota.

## Other responses

- `400`: Validation or bad request. Returned by the handler for invalid JSON, ValidateBatchRequest failures, invalid checkin, unknown feed, or unresolved hotel IDs.
- `401`: Missing or invalid API key (`X-API-Key`). Returned by authentication middleware.
- `403`: Forbidden. Non-enterprise API keys cannot call this endpoint.
- `429`: Rate limit exceeded. Cost of this call is `losCount × occupancyCount × feedCount` (also returned as `X-RateLimit-Cost` on success).
- `500`: Unexpected failure while running the batch (e.g. setup failure before streaming).

## Changes

- **2026-11-03** `0414c9ba2a76`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/liteapi/apis/api-search/changes/hotels/rates/batch/post.md)

---

[API](https://skmtc.dev/liteapi/apis/api-search.md) - [All operations](https://skmtc.dev/liteapi/apis/api-search/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-search/revisions/0414c9ba2a76?raw)