The Store heartbeat checks every store every morning and whenever something changes, and leaves a short note: what needs the owner, what was handled, money worth chasing. The owner reads it on Home. Your agent reads the same notes as its to-do list, through any of three surfaces that share one sign-in and the same permissions.

How to use it

  1. Read the newest notes and their open needs_you items. The brief shows the facts behind them: sales against the store’s normal, ads, the growth goal, alerts and approvals waiting.
  2. Act on each item with the other dtc_* tools, only after the merchant agrees when it spends money or messages customers.
  3. Resolve it: done only after the action really happened, dismissed when the merchant chose not to act. It then leaves the owner’s card and bell. resolved_by records agent:<connection name>.
  4. Follow up. Book a later look (“see if sales came back after pausing the ad set”), 1 to 168 hours ahead. After a change, ask for a fresh check and read the notes again about a minute later.
  5. Tasks. When the owner asks for something on a schedule (“every Monday, tell me how my ads did”), add a task instead of remembering it yourself. It runs on PlatformDTC’s side even when your agent is offline, and the answer lands in the owner’s notes and email.

Tasks

A task is something the owner (or you, for them) asked the heartbeat to do once or on repeat. The owner sees and manages the same list in the Tasks tab on Home.
  • When a task is due, the heartbeat always answers it with a note, even when everything is normal. The note is emailed at the time picked, unless the owner turned emails off. An hourly task’s answer is emailed only when something is urgent (it is always on Home), and a store can have at most 3 of them. The task’s last_run_at and last_note_id point at the answer.
  • A repeating task moves to its next time after each run. Resuming one starts from its next time (a missed run is not made up). A one-time task whose time passed while paused needs a new at.
  • Tasks can read sales and orders, ads, the monthly goal, payments, disputes, support messages and approvals waiting. They report; they don’t take actions.
  • A task can also watch a web page: put the link in check (“every morning, tell me about new reviews on https://www.trustpilot.com/review/example.com”). Each run reads that page fresh (up to 3 links across the tasks due at once) and answers with what it says: star rating, new reviews and what customers wrote, prices. If the page can’t be read, the answer says so. To read a page right now yourself, use dtc_read_web_page.
  • Up to 20 tasks per store, counting the owner’s and every agent’s (one-off follow-up checks count too). The heartbeat’s own checks are separate (at most 3) and show created_by: "heartbeat".

What you get back

  • State: store_id, settings (enabled, watch, email_mode = daily | urgent | off), last_checked_at, next_check_at, checking (a check was asked for and hasn’t finished), notes (newest first), followups (the store’s tasks: open soonest first, then paused) and timezone (the store’s time zone, UTC when not set; task times are in it).
  • Note: id, trigger, urgency (now | today | fyi), headline, summary, items, created_at.
  • Item: id (i1, i2, …, stable within the note), kind (needs_you | opportunity | done | heads_up), title, detail, dollars_per_day (only when the facts give the numbers, else null), evidence (the brief facts it rests on), action (label, app-relative href), status.
  • Followup (a task): id, due_at (next run), check, created_by (owner | heartbeat | agent:<connection name>), status (open | paused), repeat, time, weekday, last_run_at, last_note_id, answer_items (the ids of the items in that note that answered this task; one note can answer several tasks) and metrics (the measured numbers those items rest on: label, value, unit = usd | count | per_dollar | stars, with out_of for stars, and compare, compare_label, change_pct, good where they apply). Both are absent until the task has an answer.
Every item rests on at least one fact in the brief. Items whose evidence doesn’t exist are dropped, and an item’s link always comes from its evidence. Money in the brief is US dollars, as on the dashboard. Limits: watch up to 2000 characters, check 3–300 characters, in_hours 1–168. The brief is rate-limited to 6 calls a minute per store. A check answers checking: true at once; the note, if there is one, lands within about a minute. When nothing matters, a check leaves no note.

MCP

The tools are on the same server as every other dtc_* tool, https://api.platformdtc.com/mcp (see Connect your own AI agent). A plain curl with a bearer key works without a session:
The answer is in result.content[0].text.

Agent Gateway

Agent keys (sq_agt_*) or a user token. Responses use the { "data": … } envelope; every non-GET takes an Idempotency-Key. See Authentication.

A2A

Other agents (Google ADK, LangGraph, CrewAI or any A2A client) can find and talk to the store’s heartbeat over the Agent2Agent protocol. Send a data part {"skill": "<id>", …arguments}. A message with only text is store-pulse.
A check still running after 50 seconds comes back working: poll GetTask (v1.0) or tasks/get (v0.3). A v1.0 SendMessage waits by default (configuration.returnImmediately: true returns at once); v0.3 waits only with configuration.blocking: true.
  • Idempotency: messageId is the key. The same messageId again returns the first task and does nothing twice.
  • Cancel: a check can’t be called back once asked for, so CancelTask always answers -32002 (the check finishes on its own).
  • Not offered: streaming and push notifications.
  • Errors: JSON-RPC errors, code -32000, carrying the HTTP status the gateway uses: 401 (no or bad token), 403 (store or permission), 429 (rate limit). Another store’s task id answers -32001.
  • Retention: tasks untouched for 30 days are deleted.