CopyHero
Back to CopyHero

Update Watched Store

PATCH
/api/v1/watchlist/stores/{watched_store_id}

Pause/resume the viewer's subscription and set its interval override.

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Path Parameters

watched_store_id*Watched Store Id
Formatuuid

Request Body

application/json
  1. body

PATCH /watchlist/stores/{id} — mutate the viewer's own subscription.

All fields optional; only the ones sent are applied. paused toggles the viewer's pause (participates in the DB-maintained active_subscription_count); scan_interval_minutes is the per-subscription cadence override (None clears it → inherit registry).

paused?|

Pause (true) or resume (false) this subscription.

scan_interval_minutes?|

Per-subscription scan cadence override (minutes).

clear_scan_interval?Clear Scan Interval

Set true to clear the interval override (inherit default).

Defaultfalse

Response Body

Successful Response

application/json
  1. response

A watched store as seen by ONE subscriber. Store status is global; the subscription fields are the viewer's own. Deliberately carries NO precise scan timestamps (next_scan_at / precise last_scan_at) — those would leak a co-watcher's cadence (CONCEPT §9 F8.1).

id*Id
Formatuuid
url*Url
name?string|null
status*WatchedStoreStatus

Scan-health status of a watched store (a display badge only — products stay visible regardless of status). Stored as plain text (no Postgres ENUM, like RevisionActorType) so a new value is zero-DDL. pending is the pre-first-scan state; unreachable = DNS/timeout/conn error; invalid = reachable but not a public Shopify store (password page / 401/403 / not Shopify JSON).

Value in"pending""active""unreachable""invalid"
status_detail?string|null
product_count*Product Count
initial_crawl_completed*Initial Crawl Completed
listings_last_7_days*Listings Last 7 Days
Range0 <= value
listings_last_30_days*Listings Last 30 Days
Range0 <= value
listing_activity_12m*array<>
traffic_country?string|null
search_traffic_12m?array<integer|null>
screenshot_url?string|null
tracking_pixels?|null
paused*Paused
scan_interval_minutes?integer|null
subscribed_at*Subscribed At
Formatdate-time
tags?array<string>
Example Request
curl -X PATCH 'https://app.copyhero.app/api/v1/watchlist/stores/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "string",  "name": "string",  "status": "pending",  "status_detail": "string",  "product_count": 0,  "initial_crawl_completed": true,  "listings_last_7_days": 0,  "listings_last_30_days": 0,  "listing_activity_12m": [    {      "month": "2019-08-24",      "count": 0    }  ],  "traffic_country": "string",  "search_traffic_12m": [    0  ],  "screenshot_url": "string",  "tracking_pixels": {    "property1": [      "string"    ],    "property2": [      "string"    ]  },  "paused": true,  "scan_interval_minutes": 0,  "subscribed_at": "2019-08-24T14:15:22Z",  "tags": [    "string"  ]}

Set Watched Store Tags PUT

Replace the viewer's complete tag set for one store (idempotent). 404 when the viewer holds no live subscription. An empty list clears all tags.

Get Cluster Growth GET

Rank the active layout's clusters by how many watchlist products the viewer's subscribed competitors added into each within the window (counts are store-filtered + subscription-gated, NOT the store-unfiltered lifetime cluster size), ordered per ``sort_by``. No active layout / no subscription / no points in range → empty ``data``, never a 404.