Merchant Clock REST API
Manage stores and read scan scores from your own scripts. JSON over HTTPS.
Authentication
Create a key in Settings. It is shown once; we store only a hash. Send it as a bearer token:
curl -H "Authorization: Bearer mc_..." https://www.merchantclock.com/api/v1/monitors
Revoke a key in Settings at any time. Keys act on the account they were created in.
Rate limits
Keep to 60 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you may get 429 with Retry-After; back off and retry.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/monitors | List stores with the latest score. |
| POST | /api/v1/monitors | Add a store. Body {"hostname": "https://store.example"}. Returns 201, 402 over the plan limit, or 409 if it already exists. |
| GET | /api/v1/monitors/{id} | One store. |
| GET | /api/v1/monitors/{id}/checks | The last 50 scans. |
| POST | /api/v1/monitors/{id}/check | Run a scan now and return the result. |
| DELETE | /api/v1/monitors/{id} | Remove a store. Returns 204. |
| POST | /api/scan | Anonymous scan. Body {"url": "https://store.example"}. |
Store object
{
"id": "...", "hostname": "store.example", "port": 443, "paused": false,
"status": "ok" | "problem" | "pending", "error_code": null,
"days_remaining": 82, "last_checked_at": "...",
"created_at": "..."
}
days_remaining holds the latest risk score from 0 to 100 for Merchant Clock stores.
Errors
Errors return {"error": "code", "message": "..."} with codes unauthorized, invalid_json, invalid_hostname, plan_limit, duplicate, not_found and rate_limited.
Signed webhooks
Add a webhook URL in Settings to receive alerts as JSON. Each POST has X-MerchantClock-Event and X-MerchantClock-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw body with your signing secret. Reject requests older than five minutes.