Modes

Rates — POST /shop

One hotel × one stay → every room × rate plan, public and member, with the after-tax figure on each row.

Request

{ "chain": "hyatt", "hotel_code": "CHIZP", "checkin": "2026-11-10", "los": 1,
  "occupancy": { "adults": 2, "children": [], "rooms": 1 }, "currency": "USD" }

Field	Type	Notes
`chain`	id	one of the 16 ids on Chains & coverage
`hotel_code`	string	the chain’s own property code, 1–16 letters/digits/`-`/`_`
`checkin`	`YYYY-MM-DD`	a date already past in every timezone (earlier than yesterday UTC) is `invalid_request`, never billed
`los`	int 1–30	nights; default 1
`occupancy`	object	`adults` 1–8 (default 2), `children` ages 0–17 (up to 8), `rooms` 1–8 (default 1)
`currency`	ISO 4217	default `USD`
`rate_filters`	array	subset of `bar member advance_purchase package corporate aaa senior government other`
`max_age`	int sec	max acceptable cache age; omitted = any cached answer within the TTL; 0 = always live

Response

ShopResponse: chain, hotel {code,name,brand,currency}, checkin, los, occupancy, status (available / sold_out / closed / restricted_los / not_found / error), min_los where the chain states a minimum stay, rates[], lowest, shopped_at, source, cache_age_sec.

Each row of rates[] carries room_code, room_name, bed_type, rate_code, rate_name, rate_type, member_only, refundable, cancel_deadline, meal_plan, price_per_night (native basis), price_per_night_after_tax (comparable), price_total, taxes_fees_total, tax_included, currency, rooms_left, and points_per_night / points_total / cash_copay on chains that return points inline.

lowest keys: bar (lowest public), member (lowest member-only), bar_after_tax, member_after_tax. A key is absent when no rate supplies it. A member rate never collapses into bar.

A real response, trimmed, is on the home page and on each chain page.

Billing

Billed the chain’s shop weight per live shop (see /chains shop_credits); cache hits 0.25×; errors free. max_age (sec) caps cache staleness; max_age=0 forces live.

Notes

sold_out, closed and restricted_los are answers — the hotel exists, it is not selling that stay. They are billed; not_found and error are not.
A live single-hotel lookup typically takes 1–10 seconds. Schedule bulk work; do not put it in a request path.
The OTAs answer this call too, with their own hotel id as the code.