Docs

Vendrail status badge

The Vendrail status badge is a small public read of checkout health for a verified store. It shows a high-level verdict and timestamp only. It never exposes store URLs, error messages, screenshots, incidents, user email, journey configuration, or plan details.

Embed snippets

Light SVG image

<img src="http://localhost:3001/v1/status/<YOUR_TOKEN>.svg" height="20" alt="Checkout status" />

Dark SVG image

<img src="http://localhost:3001/v1/status/<YOUR_TOKEN>.svg?theme=dark" height="20" alt="Checkout status" />

Linked badge

<a href="https://vendrail.app" rel="noopener"><img src="http://localhost:3001/v1/status/<YOUR_TOKEN>.svg" height="20" alt="Checkout status" /></a>

JSON fetch

const response = await fetch("http://localhost:3001/v1/status/<YOUR_TOKEN>.json");
const status = await response.json();
console.log(status.verdict, status.stale, status.lastCheckedAt);

JSON schema

interface PublicStatusJsonDto {
  verdict: "up" | "down" | "unknown";
  stale: boolean;
  lastCheckedAt: string | null;
  generatedAt: string;
  label?: string | null;
}

Status codes

200 - normal badge or JSON response.
410 - badge disabled, token rotated, store unverified, or subscription no longer entitled. SVG requests still receive a stable unknown badge.
429 - rate limited. Respect the Retry-After header.
404 - malformed token.

Caching

Responses include Cache-Control: public, plan-based max-age and s-maxage, plus stale-while-revalidate. Starter badges cache for 5 minutes, Growth for 2 minutes, and Pro for 1 minute. Poll JSON at the TTL plus roughly 30 seconds of jitter.

Theme

SVG badges accept ?theme=light or ?theme=dark. The default is light. Unknown values are silently treated as light so embeds do not break. Each theme is a normal URL variant, so caches key it separately.

Label

Set an optional badge label from the store detail page in the Vendrail dashboard. Labels are stored server-side, max 20 ASCII-printable characters, and are included in SVG and JSON responses only after being sanitized.

Security

The token in the URL is the entire authorization mechanism. Treat it like a secret. Use token rotation in the dashboard to immediately revoke old embeds. The endpoint is read-only, session-less, and does not trigger checks.

Limits

Public badge routes are limited to 60 requests per token per minute and 600 requests per IP per minute.

Status page

The optional public status page uses the same token as the badge but is enabled separately. It shows the current verdict, a 30-day day strip, and recent incident summaries without exposing store URLs, screenshots, error messages, or journey configuration. The machine-readable endpoint is /v1/status/<token>/page.

Telemetry

Dashboard hit counts are sampled, not exact. With the default sample rate, Vendrail keeps roughly one audit row per ten public badge requests and reports an estimated total as sampled hits multiplied by the sample rate.

Need a token?

Open store settings