A watch is a standing condition with a signed callback. The engineering is straightforward; the design is where these succeed or fail.
A watch can be bound to a product, a seller, a brand or a category. Category and brand watches are how you monitor a competitive set without enumerating it by hand.
POST /v1/watches
{ "brand": "Ninja", "category": "home.kitchen",
"condition": { "op": "pct_drop", "value": 15 },
"callback": "https://you.example/hooks/price" }| op | Fires when |
|---|---|
| lt / gt | Price crosses an absolute threshold. |
| pct_drop | Price falls by N% from its recent level. |
| percentile_below | Price enters the bottom N% of its own history. |
| spread_gt | Cross-seller gap exceeds N minor units. |
| back_in_stock | Availability returns. |
| seller_change | Buy-box or primary seller flips. |
Absolute thresholds go stale — a user sets $200 and forgets. `percentile_below: 10` means “tell me when this is genuinely cheap for this product”, which stays true as the market moves.
Include the context in your user-facing message. “Now $198” gets muted; “Now $198 — lowest in 89 days” gets opened. The field is already in the payload.