Price check API
Read the verdict behind a hotel's StayParity badge from your chat bot or widget: one GET, the direct price and the OTAs it matches or beats, never an undercut.
The price check answers one question for one night: what does the hotel's own website charge, and is that the best price around? It reads the same data as the hotel's website badge, so a WhatsApp bot, a chat assistant or a widget you build yourself can quote it too. It reports the verdict the check found. The badge's Best price here seal is the hotel's own claim, shown on every verdict, and isn't part of the answer.
It needs no account or API token, only the hotel's embed key, and it says nothing a guest on the hotel's website couldn't see. When an OTA sells the night for less, it gives the hotel's own price alone, exactly as it does for a night no OTA sells, so neither you nor anyone else can tell an undercut from its answer.
Request
One GET, with three query parameters:
GET https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=2027-06-14&occupancy=2Parameters
| Parameter | Value |
|---|---|
key | The hotel's embed key, wk_…: the data-hotel value in its badge snippet, under Settings → Website badge in the portal. |
stayDate | The night, as its check-in date in YYYY-MM-DD. One night: for a longer stay, ask about its first. |
occupancy | The number of adults, from 1 to 10. |
The price check works only while the hotel's badge is on. The hotel doesn't have to show the badge on a page.
Answers
Every answer is JSON with a status. A 200 carries one of three:
| Status | What it means | What to do |
|---|---|---|
ready | A price has been read for the stay. comparison holds it. | Quote it by the wording rules and link to bookUrl. |
pending | Nothing has been read for the stay yet, and a check is running now. | Ask again, as under Waiting out pending. |
unavailable | There is nothing to quote, and no check can start now: the hotel is paused in StayParity, it isn't checked for that number of adults, the night is past in the hotel's time zone or further ahead than its plan checks, its checks for the day are used up, or the last check found no price. | Answer without a price and link to bookUrl. For a number of adults the hotel isn't checked for, you can ask again for 2 and say you checked for 2 adults. |
HTTP status
| Code | When | Body |
|---|---|---|
200 | Always, when the key and the request are good. | ready, pending or unavailable |
400 | A parameter is missing or malformed, occupancy is outside 1 to 10, or the night is already past everywhere on Earth. | {"status": "unavailable", "error": "…"}, the error in English for whoever wrote the request |
404 | The key is unknown, has been replaced, or the hotel's badge is off. | {"status": "unavailable"} |
405 | A method other than GET. | None |
502 | The badge's server couldn't reach StayParity. Try again later. | {"status": "unavailable"} |
Treat any other code, a body that isn't JSON or a network error as no answer.
Fields
| Field | Type | Meaning |
|---|---|---|
status | string | ready, pending or unavailable. |
asOf | integer | ready only. When the newest price in comparison was read, in Unix milliseconds. Never the time of your request. |
comparison | object | ready only. The hotel's price and the OTAs it may be shown beside. |
comparison.currency | string | The hotel's currency, as an ISO 4217 code such as EUR. Every price in the comparison is in it. |
comparison.directPriceMinor | integer | The hotel's own price for the night, in minor units. |
comparison.verdict | string | cheapest, matched or direct_only: see Verdicts. |
comparison.savingMinor | integer | The cheapest listed OTA's price minus the hotel's, in minor units. Zero unless verdict is cheapest. |
comparison.channels | array | The OTAs to show beside the hotel's price. Empty when verdict is direct_only. |
comparison.channels[].ota | string | The OTA's id, such as booking or expedia. For your code, never for display. |
comparison.channels[].label | string | The OTA's name to show, such as Booking.com. |
comparison.channels[].priceMinor | integer | The OTA's price for the same night, in minor units, for as many guests as the hotel's price or fewer: see the wording rules. |
bookUrl | string | The hotel's booking page, always https. Every 200 has it. |
bookUrlTemplate | string or null | The hotel's booking search, with {checkin}, {checkout}, {nights} and {adults} for you to fill: dates as YYYY-MM-DD, nights and adults as whole numbers. null when the hotel has saved none. Every 200 has it. |
perks | object | The hotel's own perks for a guest who books direct, such as breakfast, credited to the hotel. Every 200 has it. Show them apart from the price: see the wording rules. |
perks.from | string | The name to credit the perks to: the hotel's name, or the shorter one it gave its badge. |
perks.items | array | Up to two perks, in the order to show them. Empty when the hotel shows none. |
perks.items[].key | string | The perk's id, such as breakfast. For your code, never for display. |
perks.items[].icon | string | The icon's id, such as cup. For your code, never for display. |
perks.items[].paths | array | The icon as SVG path data on a 24 by 24 grid, one to three paths, drawn as a stroke with round caps and no fill. |
perks.items[].label | object | The perk's name to show, keyed by language: en, es, el, it, de and cs. More languages may come, so take the guest's language when it is there and en when it isn't. |
error | string | A 400 only. What is wrong with the request. |
Verdicts
| Verdict | What it means | What you may say |
|---|---|---|
cheapest | Every listed OTA is dearer than booking direct. | The saving, savingMinor, against the cheapest listed OTA, and each OTA's price. |
matched | No listed OTA is cheaper, and at least one is level with the hotel. | "The same price as on" an OTA only when its priceMinor equals directPriceMinor. |
direct_only | The hotel's price is all there is to say: an OTA may be cheaper, may sell different terms, or may not sell the night at all. | The hotel's price alone. |
Examples
A night the hotel is cheapest:
{
"status": "ready",
"asOf": 1791547200000,
"comparison": {
"currency": "EUR",
"directPriceMinor": 14200,
"verdict": "cheapest",
"savingMinor": 1600,
"channels": [
{ "ota": "booking", "label": "Booking.com", "priceMinor": 15800 },
{ "ota": "expedia", "label": "Expedia", "priceMinor": 16100 }
]
},
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}A night with only the hotel's price to give:
{
"status": "ready",
"asOf": 1791547200000,
"comparison": {
"currency": "EUR",
"directPriceMinor": 14200,
"verdict": "direct_only",
"savingMinor": 0,
"channels": []
},
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}A night still being checked:
{
"status": "pending",
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}Waiting out pending
The first request for a night nobody has asked about starts a check and answers pending. Most checks finish within seconds, some take longer. Ask again after 2 seconds, then after 3, then 5, then every 8, and stop after 8 requests or 30 seconds, whichever comes first. The badge waits the same way. If the answer is still pending then, answer without a price and link to bookUrl; a request a few minutes later usually finds the price.
Never cache a pending answer, and don't ask about a night nobody asked you about: each check spends from the hotel's daily allowance.
Freshness and caching
asOf says when the price was read. The hotel's prices are checked on a schedule and the price check gives the latest it has, so a price can be hours or days old. A request starts a fresh check only when the price is stale for its stay, that is older than the schedule's spacing for that night: 1 day for tonight and the 6 nights after it, 4 days up to night 30, and 20 days beyond. A price for a night months ahead can be 15 days old and start nothing. When a request does start a check, while the hotel has checks left, it still gets the old price, and a later request gets the new one. Always say how old the price is, as the badge does with "Checked 12 min ago" and the example below does, and use the current time if asOf is later than your clock.
Answers are shared between everyone who asks about the same night, the hotel's badge included. A ready answer is cached for 60 seconds and then served for up to 3600 more while it refreshes, so a price can reach you up to 61 minutes after StayParity has it: the first request after a quiet spell gets the older answer, and the next the new one. unavailable and 404 are cached for 60 seconds, pending and 400 not at all. The Cache-Control header says the same, and your own cache can follow it.
Wording rules
Word your replies by the verdict, not by the badge's seal:
- Claim a saving, or that booking direct is cheapest, only for
cheapest. - Say "the same price as" an OTA only when that OTA's
priceMinorequalsdirectPriceMinorexactly. - For
direct_only, give the hotel's price and nothing about OTAs. Don't say no OTA is cheaper, and don't say one is. - Name an OTA by its
label, never itsotaid. - Quote prices as given: per night, in
currency. Don't convert them or add to them. - A price is for a room that sleeps at least the number of adults asked about, and sometimes for a room that sleeps more, for the hotel and the OTAs alike. A listed OTA's price is for as many guests as the hotel's or fewer, never more. Say what you asked about, such as "for 2 adults", not that the room sleeps exactly that many.
- Show
perksapart from the price, credited toperks.from, whatever the answer. They are the hotel's promise, not StayParity's, and the price check doesn't check them: never count one into a price or a saving, and never add a perk the answer doesn't list. - Link to
bookUrlfor the booking, whatever the answer. WhenbookUrlTemplateisn'tnulland you know the guest's check-in and check-out, link to it filled instead, asstayUrlbelow does. Never work out a check-out the guest didn't give, and usebookUrlwhen the template asks for{adults}and you don't know them.
Seller logos
The badge's logo for an OTA is at https://badge.stayparity.com/widget/marks/{ota}.svg, keyed by the channel's ota id: a square SVG of the OTA's tile and mark as the badge draws them, 22 pixels unless you size it. An OTA the badge has no logo for answers 404, so show your own placeholder then, as the badge shows the name's first letter. The logos answer any origin and hold no scripts. Each is cached for a day and then served for up to 30 more while it refreshes, as its Cache-Control header says. If the site sends a Content-Security-Policy, allow the origin in img-src.
<img src="https://badge.stayparity.com/widget/marks/booking.svg" alt="" width="22" height="22">Credit
When your bot or widget quotes these prices, we ask you to credit them as the badge does: StayParity's mark, then "Price check by StayParity", linking to https://stayparity.com. The mark is at https://badge.stayparity.com/widget/brand/mark.svg for a light background and https://badge.stayparity.com/widget/brand/mark-dark.svg for a dark one, served as the seller logos are. A bot that answers in text can end with "Price check by StayParity · stayparity.com", as the example below does. It isn't a condition: the price check answers the same without it.
<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Price check by Stay<b>Parity</b></a>Counting views
The hotel's Badge page in StayParity counts how often guests see its badge. A page that draws its own widget from the price check can count its views too, and the Badge page shows them apart from the badge's, under Your own widget: views, how many saw a price, how many had it in view and how many clicked Book direct, by verdict, device and language. Counting is optional: the price check answers the same without it.
The page sends a small body to:
POST https://badge.stayparity.com/widget/beaconSend the body as a string, which the browser sends as text/plain, so it needs no CORS preflight. A body of any other type is dropped.
Body
| Field | Type | Meaning |
|---|---|---|
key | string | The hotel's embed key, the one the page asked the price check with. |
view | boolean | true on a page view's first send, false on its one later send. |
verdict | string | First send only, and required there. The verdict of the last ready answer the page showed, or none if it showed none. |
device | string | First send only, and required there. mobile when the screen is under 768 pixels wide, desktop otherwise. |
lang | string | First send only, and required there. The browser's language, navigator.language, at most 35 characters. |
shown | boolean | A ready answer was put on screen. |
inView | boolean | At least half of what shows the answer was in the viewport for one second without a break, while the page was visible. |
clicked | boolean | The guest clicked the Book direct link or button drawn with the answer, whether it follows bookUrl or opens the hotel's own booking. |
A flag that is left out means false, and a later send must carry at least one flag that is true. A body with a field that isn't in the table, or with a field in the wrong form, counts nothing.
A page view's first send:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": true,
"verdict": "cheapest",
"device": "desktop",
"lang": "en-GB",
"shown": true,
"inView": true
}Its later send, for a flag turned on since:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": false,
"clicked": true
}When to send
- Count a view once the page has asked the price check about at least one stay. A page that never asked counts nothing.
- Send the first send when the page is hidden (
visibilitychangeto hidden, orpagehide) or when the guest clicks Book direct, whichever comes first. - Send at most one later send, with only the flags turned on since, at the next of those moments.
- Keep one counter per key and page, so a widget drawn twice counts once.
- Send nothing when
navigator.webdriveris set.
The page's origin
The beacon counts the view for the host in the request's Origin header, which the browser sets. So send it from the page, never from a server: a server sends no Origin, and its beacons count nothing. A host that isn't one of the hotel's sites in StayParity counts under Other sites on the Badge page, and localhost never counts.
Send it with fetch and keepalive, as the example below does. navigator.sendBeacon works in most browsers, but Safari sends it with no Origin when the page's Referrer-Policy is no-referrer or same-origin, and then nothing counts.
Limits
- A body is at most 1 KiB.
- An address can send 30 beacons a minute, shared with the hotel's badge.
- A hotel counts at most 5,000 beacons in its day, shared with its badge. After that, nothing counts until the hotel's midnight.
Checking your counts
The beacon always answers 204 with no body, whatever happened to what you sent, so its answer tells you nothing. To check your counting, open the page on the hotel's site, leave it, and look at the Today card on the Badge page in StayParity, under Your own widget.
Example
In JavaScript for a browser. Call pageView when the page first asks the price check with a key, shown when it draws a ready answer, and clicked when the guest clicks Book direct:
const BEACON = "https://badge.stayparity.com/widget/beacon";
const FLAGS = ["shown", "inView", "clicked"];
const views = new Map();
// The page view for a key, one per key however often the page asks.
function pageView(key) {
if (!views.has(key)) views.set(key, { key, verdict: "none", on: new Set(), sent: null, done: false });
return views.get(key);
}
function send(view) {
if (view.done || navigator.webdriver) return;
const flags = FLAGS.filter((flag) => view.on.has(flag) && !view.sent?.has(flag));
let body;
if (view.sent === null) {
body = {
key: view.key,
view: true,
verdict: view.verdict,
device: screen.width < 768 ? "mobile" : "desktop",
lang: navigator.language.slice(0, 35),
};
view.sent = new Set();
} else if (flags.length > 0) {
body = { key: view.key, view: false };
view.done = true;
} else {
return;
}
for (const flag of flags) {
body[flag] = true;
view.sent.add(flag);
}
fetch(BEACON, { method: "POST", body: JSON.stringify(body), keepalive: true }).catch(() => {});
}
// A ready answer drawn in element: in view once half of it stays on screen for a second.
function shown(view, element, verdict) {
view.verdict = verdict;
view.on.add("shown");
let timer;
let ratio = 0;
const arm = () => {
clearTimeout(timer);
if (ratio < 0.5 || document.visibilityState !== "visible" || view.on.has("inView")) return;
timer = setTimeout(() => {
view.on.add("inView");
observer.disconnect();
}, 1000);
};
const observer = new IntersectionObserver(([entry]) => {
ratio = entry.intersectionRatio;
arm();
}, { threshold: 0.5 });
observer.observe(element);
document.addEventListener("visibilitychange", arm);
}
// Book direct may leave the page, so the click sends at once.
function clicked(view) {
view.on.add("clicked");
send(view);
}
const sendAll = () => views.forEach(send);
document.addEventListener("visibilitychange", () => {
if (document.visibilityState === "hidden") sendAll();
});
window.addEventListener("pagehide", sendAll);
// const view = pageView("wk_…"); then shown(view, list, answer.comparison.verdict) and clicked(view)Money
Every price is an integer in the currency's minor units, as in ISO 4217: 14200 in EUR is €142.00. ISK, JPY and KRW have no minor unit, so 14200 in JPY is ¥14,200. Every other currency the price check sends has two decimals. Take the decimals from this rule, not from your platform's currency formatter: formatters disagree, and some give HUF and IDR none.
Try it
The key wk_demo answers for Hotel Aurora, the sample hotel on the demo page, with made-up prices for 1 to 4 adults and every night of the coming year. It never answers pending and spends no hotel's checks, so you can call it as often as you test:
curl "https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=$(date -u +%F)&occupancy=2"A reply for a WhatsApp-style bot, in JavaScript for Node 18 or later, Deno, Bun or a browser. It waits out pending as the badge does, says how old the price is and follows the wording rules. stayUrl gives the link for the guest's stay:
const API = "https://badge.stayparity.com/widget/comparison";
const WAITS_MS = [2000, 3000, 5000, 8000];
const MAX_REQUESTS = 8;
const BUDGET_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// The answer for one night, or null when there is none to give.
async function priceCheck(key, stayDate, adults) {
const query = new URLSearchParams({ key, stayDate, occupancy: String(adults) });
const started = Date.now();
let answer = null;
for (let request = 1; request <= MAX_REQUESTS; request++) {
const response = await fetch(`${API}?${query}`).catch(() => null);
const body = response?.ok ? await response.json().catch(() => null) : null;
if (body === null) return answer;
answer = body;
if (answer.status !== "pending") return answer;
const wait = WAITS_MS[Math.min(request, WAITS_MS.length) - 1];
if (request === MAX_REQUESTS || Date.now() - started + wait > BUDGET_MS) break;
await sleep(wait);
}
return answer;
}
function money(minor, currency) {
const digits = ["ISK", "JPY", "KRW"].includes(currency) ? 0 : 2;
const whole = minor % 10 ** digits === 0;
return new Intl.NumberFormat("en", {
style: "currency",
currency,
minimumFractionDigits: whole ? 0 : digits,
maximumFractionDigits: digits,
}).format(minor / 10 ** digits);
}
// How old the price is, from asOf; a stamp ahead of this clock is "just now".
function checkedAgo(asOf) {
const minutes = Math.floor(Math.max(0, Date.now() - asOf) / 60000);
if (minutes < 1) return "just now";
if (minutes < 60) return `${minutes} min ago`;
const hours = Math.floor(minutes / 60);
if (hours < 24) return `${hours} h ago`;
const days = Math.floor(hours / 24);
return days === 1 ? "1 day ago" : `${days} days ago`;
}
// The hotel's search on the guest's stay, or bookUrl when it has none or needs a value you don't have.
function stayUrl(answer, checkIn, checkOut, adults) {
if (!answer.bookUrlTemplate || !checkIn || !checkOut) return answer.bookUrl;
const values = {
checkin: checkIn,
checkout: checkOut,
nights: String(Math.round((Date.parse(checkOut) - Date.parse(checkIn)) / 86400000)),
adults: adults == null ? null : String(adults),
};
let missing = false;
const url = answer.bookUrlTemplate.replace(/\{(checkin|checkout|nights|adults)\}/g, (_, name) => {
if (values[name] === null) missing = true;
return values[name] ?? "";
});
return missing ? answer.bookUrl : url;
}
function reply(answer) {
if (answer === null) return "Sorry, I can't check prices right now.";
if (answer.status !== "ready") return `Book direct with the hotel: ${answer.bookUrl}`;
const { currency, directPriceMinor, verdict, savingMinor, channels } = answer.comparison;
const direct = money(directPriceMinor, currency);
const cheapest = channels.reduce((best, c) => (best && best.priceMinor <= c.priceMinor ? best : c), null);
let text = `${direct} per night, booking direct.`;
if (verdict === "cheapest" && savingMinor > 0 && cheapest) {
text = `${direct} per night booking direct, ${money(cheapest.priceMinor, currency)} on ${cheapest.label}. You save ${money(savingMinor, currency)}.`;
} else if (verdict === "matched" && cheapest?.priceMinor === directPriceMinor) {
text = `${direct} per night booking direct, the same as on ${cheapest.label}.`;
}
return `${text} Checked ${checkedAgo(answer.asOf)}.\nBook: ${answer.bookUrl}\nPrice check by StayParity · stayparity.com`;
}
// reply(await priceCheck("wk_demo", "2027-06-14", 2))
// stayUrl(answer, "2027-06-14", "2027-06-16", 2)Limits
- A request that starts a check spends one of the hotel's 40 checks per UTC day, shared with its badge. An answer from the cache, or from a price already read, spends nothing. Once they're used up, nights with no price answer
unavailableuntil midnight UTC, and nights with one keep their last price. - The key is public: it sits in the hotel's website. Anyone with it gets the same answers you do, and the hotel can replace it at any time, after which the old key answers
404. - Use the key only with the hotel's agreement. It works only while the hotel's badge is on.
From a browser
The price check answers any origin (Access-Control-Allow-Origin: *) and needs no cookies, so a widget can call it from the page. Send a plain GET with no custom headers: the price check answers no CORS preflight. If the site sends a Content-Security-Policy, allow the API's origin:
connect-src https://badge.stayparity.com;Versioning
This is version 1 of the price check, and it stays as it is: no field is renamed, removed or changes type, no status or verdict is added, and each keeps its meaning. It may add fields and currencies, so ignore fields you don't know. A change that would break your code ships on a new path, announced on this page. The same holds for the beacon's body: it may gain optional fields, but no field becomes required, is renamed or removed, and no body that counts today stops counting.
The same contract is in the OpenAPI 3.1 description, with these examples.
Website badge
Add StayParity's book-direct badge to a hotel's website with one snippet. The snippet, the dock, what guests see, and the CSP it needs.
Measure the badge in your analytics
Count the bookings that come through StayParity's book-direct badge in GA4: the stayparity=1 mark on Book direct, a segment on it, and what it never carries.