Watcher overview

Understand how Watcher works, choose the right watch type, and plan for its lifecycle.

Watcher turns a user's travel intent into a durable price check. Your application creates a watch for an end user, and Watcher re-prices that stay on a schedule until the price qualifies or the check-in date arrives.

When a price reaches the user's threshold, Watcher sends a signed event to your webhook. Your application decides how to notify the user or continue the booking flow. For a specific hotel, you can also collect the user's consent in advance and let Watcher complete the purchase automatically.

Every API response is wrapped in {"data": ...}. Errors use standard HTTP status codes and {"detail": "..."}.

How Watcher works

Your user chooses a stay and a maximum total price.
Your application creates a hotel watch or trip watch on the user's behalf.
Watcher stores the search, not a short-lived offer, and checks current prices on a schedule.
When a price qualifies, Watcher sends a signed webhook:
- A notification watch sends the current price or matching hotels.
- An armed auto-purchase watch attempts the booking and sends the outcome.
Your application verifies the event, handles it once, and updates or notifies the user.

Choose a watch type

	Hotel watch	Trip watch
Best for	A user who has chosen one hotel	A user who is flexible within a destination
Watches	One hotel for exact stay dates	Qualifying hotels in one destination for exact stay dates
Triggers when	That hotel's total is at or below `trigger.amount`	Any matching hotel's total is at or below `trigger.amount`
Optional filters	None	Minimum guest rating and star classes
Event	`travel.hotel.watch.triggered` with the current price	`travel.hotel.trip_watch.triggered` with up to 3 matches, cheapest first
Auto-purchase	Available with recorded consent	Not available
ID prefix	`wtc_`	`twc_`

In both watch types, trigger.type is below_total. The amount is the maximum total for the whole stay in the requested currency, not a nightly price.

Choose a hotel watch when the user already knows where they want to stay. Choose a trip watch when the destination and quality matter more than a particular hotel.

Understand price behavior

Watcher stores the search criteria and requests fresh prices on each check. It does not reserve an offer for a notification watch.

Prices in triggered events are advisory. Fetch a fresh offer before asking the user to book. For auto-purchase, data.booking.total_amount in the purchased event is the binding total that was charged.

The create response includes an immediate price when one is available:

Hotel watches return current_total.
Trip watches return current_best.
A null value means Watcher could not obtain a current price; the watch still remains active.
A value at or below the threshold means the user can act now. The watch is still created and will trigger on its next check.

Understand ownership and identity

The API gateway derives the organisation and end user from your API credential. Watcher scopes each watch to that organisation and user, so one user cannot list or manage another user's watches.

Call GET /v1/watcher/whoami before creating a watch when you need to confirm which identity the request will use.

Plan for the watch lifecycle

A notification watch follows this lifecycle:

active — Watcher is checking prices.
triggered — a qualifying price produced an event; scheduled checks stop.
expired — the check-in date arrived before the watch triggered.

You can rearm a triggered watch, optionally with a new threshold. Rearming schedules an immediate check. A stay that has already started cannot be rearmed.

An auto-purchase hotel watch also uses:

purchasing — Watcher is re-pricing, validating consent, holding, and completing the booking.
purchased — the booking completed; booking_id identifies it.
purchase_failed — the attempt failed; purchase_failure explains why, and the user can still book manually.

The watch status remains active while purchase consent is pending. Use mode to distinguish notify, auto_book_pending, and auto_book.

Work within the limits

Creating a duplicate active watch for the same stay or trip returns 409.
For idempotent create requests, supply your own id: use wtc_ for hotel watches or twc_ for trip watches, followed by alphanumeric characters, with at most 40 characters in total. Reusing that ID returns the existing watch with 200.
Watcher checks active watches roughly every five minutes by default.
Watches expire automatically when the check-in date arrives.

Ready to try the complete notification flow? Create your first price watch.

In short