Metrics Reporting

Category: Admin Base URL: /admin/metrics Authentication: Required Routes: 49 routes documented

Overview#

This section documents 49 API routes for metrics reporting.

⚠️ These endpoints operate on your live store. POST/PUT/DELETE operations here — including sync, push, resync, and cache operations — modify or delete production data, and some trigger downstream effects such as warehouse orders or customer emails. DELETE operations are generally irreversible. Verify IDs and parameters carefully before calling them from scripts.

Quick Reference#

GET Admin Metrics#

Endpoint: GET /admin/metrics Authentication: Admin (Required)

Description#

GET /admin/metrics Rate limited to 60 requests per minute per user

Response#

Success:

{
  success,
  metrics,
  filters,
  requestedMetrics,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics#

Endpoint: POST /admin/metrics Authentication: Admin (Required)

Description#

POST /admin/metrics Rate limited to 10 requests per minute per user

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  success,
  message,
  date,
  metrics,
  filters,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Compute#

Endpoint: POST /admin/metrics-registry/compute Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/compute Compute multiple metrics in a single request (batch computation) @example POST /admin/metrics-registry/compute { "requests": [ { "metric_id": "metric-123", "context": { "orderTotal": 1000 } }, { "metric_id": "metric-456", "context": { "customerCount": 50 } } ] } Response: { "results": [ { "metric_id": "metric-123", "result": 1200, "success": true, "execution_time_ms": 15 }, { "metric_id": "metric-456", "result": 75, "success": true, "execution_time_ms": 12 } ], "summary": { "total": 2, "succeeded": 2, "failed": 0, "total_execution_time_ms": 27 } }

Request Body#

Response#

Success:

{
  results,
  summary,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/compute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics-registry Definitions#

Endpoint: GET /admin/metrics-registry/definitions Authentication: Admin (Required)

Description#

GET /admin/metrics-registry/definitions List all metric definitions with optional filtering

Response#

Success:

{
  metrics,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics-registry/definitions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Definitions#

Endpoint: POST /admin/metrics-registry/definitions Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/definitions Create a new metric definition

Request Body#

Response#

Success (201):

{
  metric,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/definitions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics-registry Definitions :id#

Endpoint: GET /admin/metrics-registry/definitions/:id Authentication: Admin (Required)

Description#

GET /admin/metrics-registry/definitions/:id Get a specific metric definition

URL Parameters#

Response#

Success:

{
  metric,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics-registry/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

PATCH Admin Metrics-registry Definitions :id#

Endpoint: PATCH /admin/metrics-registry/definitions/:id Authentication: Admin (Required)

Description#

PATCH /admin/metrics-registry/definitions/:id Update a metric definition

URL Parameters#

Request Body#

Response#

Success:

{
  metric,
}

Example Request#

curl -X PATCH 'https://your-store.omnicart.cc/admin/metrics-registry/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics-registry Definitions :id#

Endpoint: DELETE /admin/metrics-registry/definitions/:id Authentication: Admin (Required)

Description#

DELETE /admin/metrics-registry/definitions/:id Soft delete a metric definition

URL Parameters#

Response#

Success:

{
  id,
  deleted,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics-registry/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics-registry Definitions :id Versions#

Endpoint: GET /admin/metrics-registry/definitions/:id/versions Authentication: Admin (Required)

Description#

GET /admin/metrics-registry/definitions/:id/versions Get version history for a metric

URL Parameters#

Response#

Success:

{
  versions,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics-registry/definitions/:id/versions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Definitions :id Versions#

Endpoint: POST /admin/metrics-registry/definitions/:id/versions Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/definitions/:id/versions/rollback Rollback to a specific version

URL Parameters#

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  metric,
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/definitions/:id/versions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Execute#

Endpoint: POST /admin/metrics-registry/execute Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/execute Execute a metric formula with optional context

Request Body#

Response#

Success:

{
  metric_id,
  result,
  execution_time_ms,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/execute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics-registry Placeholders#

Endpoint: GET /admin/metrics-registry/placeholders Authentication: Admin (Required)

Description#

GET /admin/metrics-registry/placeholders List all placeholders with optional filtering

Response#

Success:

{
  placeholders,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics-registry/placeholders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Placeholders#

Endpoint: POST /admin/metrics-registry/placeholders Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/placeholders Create a new placeholder

Request Body#

Response#

Success (201):

{
  placeholder,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/placeholders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics-registry Validate#

Endpoint: POST /admin/metrics-registry/validate Authentication: Admin (Required)

Description#

POST /admin/metrics-registry/validate Validate a formula and check for circular dependencies

Request Body#

Response#

Success:

{
  validation,
  is_valid,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics-registry/validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Alerts#

Endpoint: GET /admin/metrics/alerts Authentication: Admin (Required)

Description#

GET /admin/metrics/alerts List all alerts

Response#

Success:

{
  alerts,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/alerts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Alerts#

Endpoint: POST /admin/metrics/alerts Authentication: Admin (Required)

Description#

POST /admin/metrics/alerts Create a new alert

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (201):

{
  alert,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/alerts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Alerts :id#

Endpoint: GET /admin/metrics/alerts/:id Authentication: Admin (Required)

Description#

GET /admin/metrics/alerts/:id Get a specific alert

URL Parameters#

Response#

Success:

{
  alert,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/alerts/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Alerts :id#

Endpoint: POST /admin/metrics/alerts/:id Authentication: Admin (Required)

Description#

POST /admin/metrics/alerts/:id Update an alert

URL Parameters#

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  alert,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/alerts/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics Alerts :id#

Endpoint: DELETE /admin/metrics/alerts/:id Authentication: Admin (Required)

Description#

DELETE /admin/metrics/alerts/:id Delete an alert

URL Parameters#

Response#

Success (200):

{
  id,
  deleted,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics/alerts/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Audit#

Endpoint: GET /admin/metrics/audit Authentication: Admin (Required)

Description#

GET /admin/metrics/audit/recent Get recent changes across all metrics

Response#

Success:

{
  changes,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/audit' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Audit#

Endpoint: POST /admin/metrics/audit Authentication: Admin (Required)

Description#

POST /admin/metrics/audit/export Export audit trail for compliance

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

The handler does not return an object literal, so the response shape is not derivable from the source.

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/audit' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Batch#

Endpoint: POST /admin/metrics/batch Authentication: Admin (Required)

Description#

POST /admin/metrics/batch Compute multiple metrics in parallel with intelligent caching Rate limited to 5 requests per minute per user (stricter limit for batch operations) Request body: { requests: [ { id: "dashboard-7d", type: "dashboard", filters: { range: { start: "2024-01-01", end: "2024-01-07" } }, priority: 10 }, ... ] }

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  results,
  summary,
}

Error (400):

{
  error,
}

Error (400):

{
  error,
}

Error (400):

{
  error,
}

Error (500):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Cache#

Endpoint: POST /admin/metrics/cache Authentication: Admin (Required)

Description#

POST /admin/metrics/cache/warm Warm metrics cache for common date ranges

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  success,
  warmed,
  failed,
  durationMs,
  ranges,
}

Error (500):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/cache' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics Cache#

Endpoint: DELETE /admin/metrics/cache Authentication: Admin (Required)

Description#

DELETE /admin/metrics/cache Invalidate all metrics cache

Response#

Success:

{
  success,
  message,
}

Error (500):

{
  error,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics/cache' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Cache#

Endpoint: GET /admin/metrics/cache Authentication: Admin (Required)

Description#

GET /admin/metrics/cache/stats Get cache statistics

Response#

Success:

{
  cache,
  performance,
}

Error (500):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/cache' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Catalog#

Endpoint: GET /admin/metrics/catalog Authentication: Admin (Required)

Description#

GET /admin/metrics/catalog Search metrics catalog

Response#

Success:

{
  metrics,
  count,
}

Error (503):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/catalog' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Catalog#

Endpoint: POST /admin/metrics/catalog Authentication: Admin (Required)

Description#

POST /admin/metrics/catalog Register new metric

Request Body#

Response#

Success (201):

{
  metric,
}

Error (503):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/catalog' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Catalog :id#

Endpoint: GET /admin/metrics/catalog/:id Authentication: Admin (Required)

Description#

GET /admin/metrics/catalog/:id Get metric by ID

URL Parameters#

Response#

Success:

{
  metric,
}

Error (503):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/catalog/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

PUT Admin Metrics Catalog :id#

Endpoint: PUT /admin/metrics/catalog/:id Authentication: Admin (Required)

Description#

PUT /admin/metrics/catalog/:id Update metric

URL Parameters#

Request Body#

Response#

Success:

{
  metric,
}

Error (503):

{
  error,
}

Example Request#

curl -X PUT 'https://your-store.omnicart.cc/admin/metrics/catalog/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics Catalog :id#

Endpoint: DELETE /admin/metrics/catalog/:id Authentication: Admin (Required)

Description#

DELETE /admin/metrics/catalog/:id Archive metric (soft delete)

URL Parameters#

Response#

Error (503):

{
  error,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics/catalog/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Catalog :id Dependencies#

Endpoint: GET /admin/metrics/catalog/:id/dependencies Authentication: Admin (Required)

Description#

GET /admin/metrics/catalog/:id/dependencies Get metric dependency tree

URL Parameters#

Response#

Success:

{
  dependencies,
}

Error (503):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/catalog/:id/dependencies' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Catalog :id Dependents#

Endpoint: GET /admin/metrics/catalog/:id/dependents Authentication: Admin (Required)

Description#

GET /admin/metrics/catalog/:id/dependents Get metrics that depend on this metric

URL Parameters#

Response#

Success:

{
  dependents,
  count,
}

Error (503):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/catalog/:id/dependents' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Catalog :id Lifecycle#

Endpoint: POST /admin/metrics/catalog/:id/lifecycle Authentication: Admin (Required)

Description#

POST /admin/metrics/catalog/:id/lifecycle Transition metric lifecycle state

URL Parameters#

Request Body#

Response#

Success:

{
  metric,
}

Error (503):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/catalog/:id/lifecycle' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Catalog :id Versions#

Endpoint: GET /admin/metrics/catalog/:id/versions Authentication: Admin (Required)

Description#

GET /admin/metrics/catalog/:id/versions Get metric version history

URL Parameters#

Response#

Success:

{
  versions,
  count,
}

Error (503):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/catalog/:id/versions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Catalog Seed-examples#

Endpoint: POST /admin/metrics/catalog/seed-examples Authentication: Admin (Required)

Description#

POST /admin/metrics/catalog/seed-examples Trigger the seed example metrics workflow This endpoint triggers a workflow that seeds 3 example metrics: - example_daily_gmv - example_orders_count - example_average_order_value The workflow is idempotent - it will skip metrics that already exist.

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  message,
  summary,
  metrics,
}

Error (500):

{
  error,
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/catalog/seed-examples' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Catalog Validate#

Endpoint: POST /admin/metrics/catalog/validate Authentication: Admin (Required)

Description#

POST /admin/metrics/catalog/validate Validate metric formula Rate limited to 10 requests per minute per user

Request Body#

Response#

Success:

{
  validation,
}

Error (503):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/catalog/validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Compute#

Endpoint: POST /admin/metrics/compute Authentication: Admin (Required)

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  success,
  message,
  metrics,
  filters,
  computeTime,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/compute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Dashboard#

Endpoint: GET /admin/metrics/dashboard Authentication: Admin (Required)

Description#

GET /admin/metrics/dashboard — the COMBINED dashboard payload. The admin Overview page no longer uses this route; it fetches each widget from the per-section endpoints under /admin/metrics/dashboard/* so no single slow section can hold the page hostage. This route is kept intact for backwards compatibility (external/scripted consumers, cache warming) and still returns the exact same shape it always has, including the section_errors map and the unfulfilled_paid_orders card overwritten with the bucket total. The query-param contract, defaults and MAX_RANGE_DAYS guard are shared with the section endpoints via parseDashboardQuery.

Response#

Error (500):

{
  code,
  type,
  message,
  error,
  details,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/dashboard' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Dashboard Sales-channels#

Endpoint: GET /admin/metrics/dashboard/sales-channels Authentication: Admin (Required)

Description#

GET /admin/metrics/dashboard/sales-channels Orders + revenue per sales channel. Always returns EVERY channel: the underlying breakdown groups by sales_channel_id and ignores the sales_channel filter param (the param is still accepted so the query contract is identical across every section endpoint).

Response#

The handler does not return an object literal, so the response shape is not derivable from the source.

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/dashboard/sales-channels' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Dashboard Summary#

Endpoint: GET /admin/metrics/dashboard/summary Authentication: Admin (Required)

Description#

GET /admin/metrics/dashboard/summary Summary metric cards only (current range + comparison range aggregates). NOTE on unfulfilled_paid_orders: this endpoint returns that card with its placeholder value of 0, exactly as the aggregate pass builds it. In the combined /admin/metrics/dashboard response the value was overwritten with the sum of the unfulfilled-by-age buckets. The UI now applies that same total from /admin/metrics/dashboard/unfulfilled-orders (which publishes it as totalUnfulfilled), so the tile still displays the same number.

Response#

The handler does not return an object literal, so the response shape is not derivable from the source.

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/dashboard/summary' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Dashboard Unfulfilled-orders#

Endpoint: GET /admin/metrics/dashboard/unfulfilled-orders Authentication: Admin (Required)

Description#

GET /admin/metrics/dashboard/unfulfilled-orders Unfulfilled orders bucketed by age, plus totalUnfulfilled — the sum the combined endpoint used to write over the unfulfilled_paid_orders summary card's value.

Response#

The handler does not return an object literal, so the response shape is not derivable from the source.

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/dashboard/unfulfilled-orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Dashboard Unfulfilled-products#

Endpoint: GET /admin/metrics/dashboard/unfulfilled-products Authentication: Admin (Required)

Description#

GET /admin/metrics/dashboard/unfulfilled-products — products blocking fulfillment.

Response#

The handler does not return an object literal, so the response shape is not derivable from the source.

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/dashboard/unfulfilled-products' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Definitions#

Endpoint: POST /admin/metrics/definitions Authentication: Admin (Required)

Description#

POST /admin/metrics/definitions Create a new metric definition

Request Body#

Response#

Success (201):

{
  metric,
}

Error (400):

{
  message,
  errors,
}

Error (400):

{
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/definitions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Definitions#

Endpoint: GET /admin/metrics/definitions Authentication: Admin (Required)

Description#

GET /admin/metrics/definitions List metric definitions with optional filters

Response#

Success:

{
  metrics,
}

Error (400):

{
  message,
  errors,
}

Error (500):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/definitions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Definitions :id#

Endpoint: GET /admin/metrics/definitions/:id Authentication: Admin (Required)

Description#

GET /admin/metrics/definitions/:id Get a single metric definition

URL Parameters#

Response#

Success:

{
  metric,
}

Error (404):

{
  message,
}

Error (500):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

PUT Admin Metrics Definitions :id#

Endpoint: PUT /admin/metrics/definitions/:id Authentication: Admin (Required)

Description#

PUT /admin/metrics/definitions/:id Update a metric definition

URL Parameters#

Request Body#

Response#

Success:

{
  metric,
}

Error (400):

{
  message,
  errors,
}

Error (400):

{
  message,
}

Example Request#

curl -X PUT 'https://your-store.omnicart.cc/admin/metrics/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics Definitions :id#

Endpoint: DELETE /admin/metrics/definitions/:id Authentication: Admin (Required)

Description#

DELETE /admin/metrics/definitions/:id Delete a metric definition (soft delete)

URL Parameters#

Response#

Error (400):

{
  message,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics/definitions/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Fulfillment-report#

Endpoint: POST /admin/metrics/fulfillment-report Authentication: Admin (Required)

Request Body#

Response#

Success:

{
  success,
  report,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/fulfillment-report' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Performance#

Endpoint: GET /admin/metrics/performance Authentication: Admin (Required)

Description#

GET /admin/metrics/performance Get current performance metrics

Response#

Success:

{
  performance,
}

Error (500):

{
  error,
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/performance' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Performance#

Endpoint: POST /admin/metrics/performance Authentication: Admin (Required)

Description#

POST /admin/metrics/performance/report Generate and log performance report

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success:

{
  success,
  message,
  performance,
}

Error (500):

{
  error,
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/performance' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Performance Events#

Endpoint: GET /admin/metrics/performance/events Authentication: Admin (Required)

Description#

GET /admin/metrics/performance/events Get recent computation events

Response#

Success:

{
  events,
  count,
}

Error (500):

{
  error,
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/performance/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Placeholders#

Endpoint: GET /admin/metrics/placeholders Authentication: Admin (Required)

Description#

GET /admin/metrics/placeholders List available placeholders

Response#

Success:

{
  placeholders,
}

Error (400):

{
  message,
  errors,
}

Error (500):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/placeholders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Placeholders#

Endpoint: POST /admin/metrics/placeholders Authentication: Admin (Required)

Description#

POST /admin/metrics/placeholders Create a new placeholder

Request Body#

Response#

Success (201):

{
  placeholder,
}

Error (400):

{
  message,
  errors,
}

Error (400):

{
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/placeholders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Rate-limit-status#

Endpoint: GET /admin/metrics/rate-limit-status Authentication: Admin (Required)

Description#

GET /admin/metrics/rate-limit-status Get rate limit metrics and monitoring data

Response#

Success:

{
  success,
  metrics,
}

Error (500):

{
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/rate-limit-status' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

DELETE Admin Metrics Rate-limit-status#

Endpoint: DELETE /admin/metrics/rate-limit-status Authentication: Admin (Required)

Description#

DELETE /admin/metrics/rate-limit-status Clear rate limit metrics (admin only)

Response#

Success:

{
  success,
  message,
}

Error (500):

{
  error,
}

Example Request#

curl -X DELETE 'https://your-store.omnicart.cc/admin/metrics/rate-limit-status' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Report#

Endpoint: POST /admin/metrics/report Authentication: Admin (Required)

Request Body#

Response#

Success:

{
  success,
  report,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/report' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Reports#

Endpoint: GET /admin/metrics/reports Authentication: Admin (Required)

Response#

Success:

{
  days,
  meta,
}

Error (400):

{
  message,
  issues,
}

Error (400):

{
  message,
}

Error (400):

{
  message,
}

Error (400):

{
  code,
  message,
  maxDays,
  requestedDays,
}

Error (500):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/reports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Reports Top-products#

Endpoint: GET /admin/metrics/reports/top-products Authentication: Admin (Required)

Response#

Success:

{
  products,
  meta,
}

Error (400):

{
  message,
  issues,
}

Error (400):

{
  message,
}

Error (400):

{
  message,
}

Error (400):

{
  code,
  message,
  maxDays,
  requestedDays,
}

Error (400):

{
  message,
}

Error (500):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/reports/top-products' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Suggestions#

Endpoint: GET /admin/metrics/suggestions Authentication: Admin (Required)

Description#

GET /admin/metrics/suggestions Get AI-powered metric suggestions

Response#

Success:

{
  suggestions,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/suggestions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Templates#

Endpoint: GET /admin/metrics/templates Authentication: Admin (Required)

Description#

GET /admin/metrics/templates List all metric templates

Response#

Success:

{
  templates,
  count,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/templates' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Templates#

Endpoint: POST /admin/metrics/templates Authentication: Admin (Required)

Description#

POST /admin/metrics/templates/:id/instantiate Create a metric from a template

Request Body#

Response#

Success (201):

{
  metric,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/templates' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Metrics Templates :id#

Endpoint: GET /admin/metrics/templates/:id Authentication: Admin (Required)

Description#

GET /admin/metrics/templates/:id Get a specific template

URL Parameters#

Response#

Success:

{
  template,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/metrics/templates/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

POST Admin Metrics Validate#

Endpoint: POST /admin/metrics/validate Authentication: Admin (Required)

Description#

POST /admin/metrics/validate Validate a metric formula Rate limited to 10 requests per minute per user

Request Body#

Response#

Success:

{
  validation,
}

Error (400):

{
  message,
  errors,
}

Error (400):

{
  message,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/admin/metrics/validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Cogs Alerts#

Endpoint: GET /admin/reports/cogs/alerts Authentication: Admin (Required)

Response#

Error (400):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/cogs/alerts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Cogs Inventory-turnover#

Endpoint: GET /admin/reports/cogs/inventory-turnover Authentication: Admin (Required)

Response#

Error (400):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/cogs/inventory-turnover' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Cogs Margins#

Endpoint: GET /admin/reports/cogs/margins Authentication: Admin (Required)

Response#

Error (400):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/cogs/margins' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Cogs Snapshots#

Endpoint: GET /admin/reports/cogs/snapshots Authentication: Admin (Required)

Response#

Error (400):

{
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/cogs/snapshots' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Promotions#

Endpoint: GET /admin/reports/promotions Authentication: Admin (Required)

Response#

Success:

{
  code,
  from,
  to,
  summary,
  rows,
  limit,
  offset,
  has_more,
  next_offset,
}

Error (400):

{
  message,
}

Error (400):

{
  message,
}

Error (400):

{
  message,
}

Error (400):

{
  code,
  message,
  maxDays,
  requestedDays,
}

Error (503):

{
  code,
  message,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/promotions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Promotions Codes#

Endpoint: GET /admin/reports/promotions/codes Authentication: Admin (Required)

Response#

Success:

{
  codes,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/promotions/codes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Taxes Dashboard#

Endpoint: GET /admin/reports/taxes/dashboard Authentication: Admin (Required)

Description#

TAX QUERY SHAPE — three predicates on every one of the five aggregates: oi.version = o.version Orders are versioned. Without it an edited order contributes its old line rows too, and every tax figure inflates. Measured over one week: 1318 tax lines counted vs 583 real ones. oi.deleted_at IS NULL order_item is ~3GB and its item_id index is PARTIAL on this predicate. Omitting it forces a scan — this dashboard took 17-18s per load, which reads as a hang and times out entirely on a wide range. o.deleted_at IS NULL soft-deleted orders were being counted. olt.deleted_at IS NULL order_line_item_tax_line has the same PARTIAL index on deleted_at; soft-deleted tax lines were still adding to the totals. The same three predicates are on reports/taxes/export — the screen and the downloaded file have to agree, and the export is what people file from. KNOWN DISCREPANCY (not fixed here): total_tax_collected recomputes tax as unit_price * quantity * rate, which ignores discounts — tax is charged on the discounted subtotal. For the week of 2026-08-12 that reports $3161.28 against $1129.21 actually charged per order_summary.totals.tax_total. Treat this dashboard as directional until the total is sourced from the recorded amount rather than recomputed. Do not file from it.

Response#

Error (400):

{
  message,
  issues,
}

Error (400):

{
  message,
}

Error (400):

{
  code,
  message,
  maxDays,
  requestedDays,
}

Error (500):

{
  code,
  type,
  message,
  error,
  details,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/taxes/dashboard' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

GET Admin Reports Taxes Export#

Endpoint: GET /admin/reports/taxes/export Authentication: Admin (Required)

Response#

Error (400):

{
  message,
  issues,
}

Error (400):

{
  message,
}

Error (500):

{
  code,
  type,
  message,
  error,
}

Example Request#

curl -X GET 'https://your-store.omnicart.cc/admin/reports/taxes/export' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'