# Hotel stays

Last updated 29 Oct 2026.

This guide is for builders of a website, app or agent on the Partner API.

A hotel stay is booked by its dates, never through a cart. A product that is a hotel stay says
`hotelStay: true` (and `availabilityRequired: true`). Read its rooms and rates for the shopper's dates
and guests, show them on your own page, and hand the shopper the `bookingUrl` of the room they chose: it
opens Groupon's checkout for that room, those dates and those guests, where the shopper pays.

## Read the rooms of a stay

```bash
curl -s "https://api-core.livingsocial.com/partner_storefront/products/$PRODUCT_ID/stays?checkIn=2026-12-04&checkOut=2026-12-06&adults=2&children=7" \
  -H "Authorization: Bearer $GROUPON_API_KEY"
```

| Parameter | Meaning |
|---|---|
| `checkIn` | Required: the check-in day, `YYYY-MM-DD`, from yesterday to a year ahead |
| `checkOut` | Required: the check-out day, 1 to 28 nights after `checkIn` |
| `adults` | Adults in the room, 1 to 4; 2 when absent |
| `children` | Each child's age in the room, 0 to 17, comma-separated, at most 2 (`4,9`) |

One call reads one room's guests. Anything else is refused with 400 `BAD_REQUEST`, which says what to
fix, and so is a product that is not a hotel stay (read its availability, or put it in a cart).

## What the answer holds

| Field | Meaning |
|---|---|
| `status` | `known`: the rooms are Groupon's answer. `unknown`: they could not be read right now |
| `asOf` | When Groupon's hotel partner was read; rooms are kept a few minutes |
| `checkIn`, `checkOut`, `nights`, `adults`, `childrenAges` | The stay you asked about |
| `priceNote` | What the prices are, in one sentence to show beside them |
| `rooms` | Every room and rate offered for the stay, cheapest total first |

Each room:

| Field | Meaning |
|---|---|
| `id` | The room and rate, unique within one answer |
| `title`, `description` | The room as the hotel names it |
| `refundable`, `cancellationPolicy` | Whether the rate can be cancelled for a refund, and the terms in the hotel partner's words |
| `price` | The whole stay before taxes and fees |
| `total` | The whole stay with taxes and every fee, the fees paid at the hotel included; null when Groupon does not state it |
| `payAtHotel` | Of `total`, the fees the hotel collects at the stay, such as a resort fee; null when Groupon does not state them |
| `nights` | Each night at its base rate, before taxes and fees |
| `bookingUrl` | Groupon's checkout for this room, these dates and these guests |

Every amount is in minor units with its currency and `currencyPrecision`, as in the rest of the API.
Show `price` and `total` as they are, and say which is which; Groupon's checkout states the amount it
charges. A room is seen, not held: it can go before the shopper pays, and Groupon's checkout then
says so.

## Hand over the room's link

`bookingUrl` is tagged with your storefront and, when your storefront has a CJ publisher id, wrapped in
Commission Junction's click link like a cart's `buyLink`, so a stay booked through it earns your
commission. Hand it to the shopper unchanged; never open it for them, and never build it yourself.

## When the rooms cannot be read

`status: unknown` means Groupon's hotel partner could not be read right now: never show the hotel as
fully booked. Hand the shopper the product's own `bookingUrl` instead, its page on groupon.com, where
they pick the dates and pay. A `known` answer with no room means no room is offered for those dates and
guests, or Groupon's hotel partner did not price them: offer other dates.

## For an AI agent

The agent API answers the same rooms in the offer read: `GET /ls_agent_api/offers/{permalink}` with
`checkIn`, `checkOut`, `adults` and `children` answers `stays` on an offer whose `hotelStay` is true, each
room with the same prices and a `bookingUrl` for the person. The consumer MCP server's `get_offer` takes
the same four arguments.