---
title: Shop Watches
description: The person's own watches through the codespar_watch tool. Tell them when a researched offer's price drops or a purchase's order moves, in the app and by e-mail. A watch the assistant prepares runs only after the person confirms it.
---
import { Callout } from "fumadocs-ui/components/callout";
A **watch** follows something for the signed-in person and tells them when it changes: the total of an offer from a research, or the order of a purchase. The tool is `codespar_watch`, on the [hosted server](/docs/concepts/meta-tools). It never buys anything.
**A person, not a key.** Like [Shop memory](/docs/concepts/shop-memory), every call needs a verified person. A project API key or an OAuth token is refused with `403 bearer_token_has_no_person`.
## Actions
## How a watch runs
1. **Prepared.** `watch_create` answers a watch in `paused` with reason `awaiting_confirmation`. Nothing is observed yet.
2. **Confirmed by the person.** The person taps Confirmar on its card in the Shop conversation (or on Shop › Preferências). The tool cannot confirm it.
3. **Observed.** A `price_drop` watch is looked at every 6 hours at most, a `delivery_track` watch every 3 hours. A `price_drop` watch quotes the offer again and tells the person when its total, shipping included, falls below the total it started from (and, with `target_total_minor`, only at or below that target); a `delivery_track` watch tells them when the order's status changes, and is done once the order reaches its last status.
4. **Notice.** Each change is a notice in the app and, with the `email` channel, an e-mail to the person's verified address. A price notice links to the offer, from which the person may prepare a purchase; nothing is bought until the person presses Pagar.
5. **Ends.** A watch ends when it is done, cancelled, or expires: 30 days by default for `price_drop`, 60 for `delivery_track`, at most 90 (`expires_in_days`).
Each person has at most 20 watches that are not finished per project.
## Example
```json title="tools/call"
{
"name": "codespar_watch",
"arguments": {
"action": "watch_create",
"kind": "price_drop",
"offer_ref": "sof_0000",
"target_total_minor": 19990,
"channels": ["in_app", "email"]
}
}
```
The answer carries the watch with `state: "paused"` and `paused_reason: "awaiting_confirmation"`. Tell the person to confirm it on its card.
## Arguments
| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `string` | Yes | `watch_create` \| `watch_list` \| `watch_cancel` |
| `kind` | `string` | For `watch_create` | `price_drop` or `delivery_track` |
| `offer_ref` | `string` | For `price_drop` | The `offer_id` (`sof_…`) of an offer from a research of this person ([`codespar_shop`](/docs/concepts/meta-tools/shop) `research`) |
| `purchase_id` | `string` | For `delivery_track` | The person's purchase (`prp_…`) |
| `target_total_minor` | `integer` | No | `price_drop`: tell only at or below this total, in centavos |
| `channels` | `string[]` | No | `in_app` (default) and/or `email` |
| `expires_in_days` | `integer` | No | 1..90 |
| `watch_id` | `string` | For `watch_cancel` | The watch to stop |
## Errors and what to do
| Code | Status | Cause | What to do |
|---|---|---|---|
| `bearer_token_has_no_person` | 403 | The call carries a key or an OAuth token, not a verified person. | Call as the signed-in person. |
| `watch_kind_unsupported` | 400 | A kind this delivery does not create. | Use `price_drop` or `delivery_track`. |
| `watch_channel_unavailable` | 400 | A channel this delivery does not send through, or `email` without a verified address or a configured sender. | Use `in_app`, or have the person verify an e-mail. |
| `watch_limit_reached` | 409 | The person already has 20 open watches in this project. | Cancel one first. |
| `watch_subject_unavailable` | 422 | The offer or purchase is unknown, not the person's, or not resolvable yet; or `expires_in_days` is out of range. | Use an offer from a research of this person, or one of their purchases. |
| `watch_not_active` | 409 | The watch is not in a state that takes this action (confirm, change channels, run). | Read it again. |
| `watch_not_found` | 404 | No watch of the calling person has this id. Another person's answers the same. | `watch_list`. |
| `notification_not_found` | 404 | No notice of the calling person has this id (the dashboard's notice routes). | None: it is not theirs or not there. |
| `watch_run_test_only` | 403 | A manual run of a watch, which exists only in Test projects. | Let the schedule run it. |
## Related
- [`codespar_shop`](/docs/concepts/meta-tools/shop): `research` is where the offers a `price_drop` watch follows come from
- [Shop memory](/docs/concepts/shop-memory): the person's remembered preferences
- [Test mode](/docs/concepts/test-mode): what a Test project's purchases and notices are
## Notes
**Notices.** The person reads their notices in the dashboard; an e-mail links to the notice's page (ids only, no content in the link). A notice of another person, or one that does not exist, answers the same `404 notification_not_found`.