Build on the Partner API

Hotel stays

Last updated 29 Oct 2026

Nobody reads documentation.

Here are the instructions for your agent. Give it this prompt: it reads the guides and the API contract, then walks you through the integration step by step, what to do, where and how.

Download agent instructions

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.