Skip to main content

Get Instance Dashboard

GET 
/api/storefront/instances/:id/dashboard

Everything the instance overview renders: connection state, freshness per sync card, the financial summary for the chosen window, entity counts, and a Sync Status block that is honest about which sweeps actually run in this environment.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Query: period — today, 7d, 30d, 90d or All. Default 30d; any other value returns 422 Invalid period. Must be one of: today, 7d, 30d, 90d, All.

The payload was reshaped. Read it as follows.

syncStatus.syncTypes[] — one row per sync type (Orders, Products, Inventory push, Product push), each carrying:

  • active (boolean) — will this sync actually run, in this environment, for this instance? It folds together the environment gate and the instance's own switches. The scheduled inventory and product pushes only run in production unless explicitly enabled, so outside production they report active: false.
  • inactiveReason (string|null) — short reason, null when active. One of Order import is off, Catalogue import is off, Inventory push is off, Product push is off, Auto-sync runs in production.
  • inactiveHint (string|null) — the same thing with the fix spelled out. Null when active.
  • intervalSeconds (int) — the real gap between runs, derived from the schedule the scheduler runs, not a constant. cadence and schedule are the same interval as a label ("Every 5 minutes").
  • secondsUntilNext (int|null) — seconds to the next run, and null whenever active is false: a ticking countdown for a sync nothing will run is a lie. Compose a live countdown from it client-side; nextSyncCountdown is always null and exists only as a fallback slot.
  • isStale (boolean), lastSyncDate, lastSyncHuman, recordsSyncedLast24h.

Health (syncStatus.overallHealth) is judged ONLY on rows where active is true — counting a production-gated push would park every non-production instance on critical forever. status is critical when the connection is broken or nothing is fresh, unknown when no sync type is active, healthy when all active ones are fresh, degraded otherwise.

entityCounts.entities[] — seven rows, each {displayName, total, error}: Orders, Orders without SKU order, Unfulfilled orders, Products imported, Products unmapped, Products pushed to store, Shipments pushed. The catalogue rows are the store's own products as imported into SKU.io. error is null except on Shipments pushed, which reports a failed count when there is one. totalRecords sums orders, imported products, listings and shipments.

financialSummary — measured over period. grossRevenue excludes cancelled orders; totalRefunds is the value of refunded orders; unitsRefunded counts the units on refunded orders, so netUnitsSold is a real net rather than a copy of unitsSold. currency is the currency the mirrored orders carry.

Freshness takes the LATER of the per-run sync cursor and the newest mirrored row, so a quiet-but-healthy store does not read as stale. lastSyncError / lastSyncErrorType / lastSyncFailedAt surface the most recent unresolved sweep failure across orders, products and inventory — this channel polls rather than receiving webhooks, so the dashboard is where a failing sweep has to appear.

fulfillments, listings and catalogue are the raw per-area roll-ups the cards are built from.

Authentication: Bearer token (session or PAT).

Request​

Responses​

OK

Response Headers
    Content-Type