Search and pricing
What search prices include, when they match the quote, and how to show them.
Search answers "what can this party book on these dates, and roughly what does it cost?" It reads OnSeason's synchronized copy of each property's calendar and rates, so it is fast, but its prices are indicative. The quote is the price you sell at.
Pick the search endpoint
- Use Search to discover properties by location, dates, party size, amenities, and price.
- Use Search by IDs when you already hold OnSeason listing IDs, for example from your catalogue, and need prices and availability for them.
Both return the same response. A listing that is unavailable, too small for the party, or no longer enabled for your channel is left out. It is not returned as an error. An empty listings array is a successful response.
Send both checkInDate and checkOutDate whenever you search for a stay. Without dates, search can't check availability or price a stay, and results carry no cancellation terms.
Count the nights correctly
The checkout date is the departure day and is not charged. A stay from 10 August to 13 August is three nights: 10, 11, and 12 August. Search, quote, and reservation all count nights this way.
Availability is the exception. Its endDate is the last night you want to see, so the same stay is startDate=2026-08-10 and endDate=2026-08-12.
Know what the price includes
| Field | What it is |
|---|---|
avgNightlyPrice | Average nightly price for the stay, in the display currency. Your channel's markup is already in it. |
totalPrice | Full price of the stay, including fees, taxes, and markup, rounded up to a whole currency unit. Present only when OnSeason can rebuild the PMS's quote for the stay. When it is absent, avgNightlyPrice leaves out fees and taxes. |
priceModifications | The default discount and the channel markup that OnSeason applied. These values are already in the prices. |
Never add the markup again. priceModifications.markup tells you what was applied. It is not an instruction.
When totalPrice is present, it equals the quote's totalPrice for the same listing and dates unless the PMS changed its price after the last sync. When it is absent, the quote adds the PMS's fees and taxes, so expect the quoted total to be higher than avgNightlyPrice times the nights.
Show multi-room results correctly
For MULTI_UNIT and COMPLEX listings, search can fit a large party into several rooms.
bookableCapacityis how many guests the property can host across the rooms that are free for the stay.roomsForPartyis the fewest rooms that seat the party. It is1for an ordinary result.
When roomsForParty is greater than 1, avgNightlyPrice is the price per room, not for the whole party. A single quote and reservation book one unit, so plan multi-room bookings with OnSeason before you sell them.
Show the cancellation terms
When you send dates, each result carries a cancellationPolicy. The policy, deadlines, and percentages are the ones a quote for the same stay returns. The amounts are shares of the search price, so they move when the quote adds fees or taxes. Show the terms on the results page and re-read them from the quote at checkout. Cancellation policies covers the fields.
If OnSeason can't work out the terms for a search, the results still come back, without cancellationPolicy. The quote always carries terms.
Convert currencies at request time
Send displayCurrency to get every price in one ISO 4217 currency. OnSeason converts at request time. If the guest changes currency, dates, or party size, quote again.
Amounts are in normal currency units, not cents, and can have decimals. 486 in EUR is EUR 486.00.
Cache content, not prices
Cache property content and refresh it from updatedAt. Don't cache search prices for long, and don't quote a property again and again unless a booking is close. See Handle timeouts and retries for load guidance.