# 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

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/admin/metrics` | GET /admin/metrics Rate limited to 60 requests per minute pe... |
| POST | `/admin/metrics` | POST /admin/metrics Rate limited to 10 requests per minute p... |
| POST | `/admin/metrics-registry/compute` | POST /admin/metrics-registry/compute Compute multiple metric... |
| GET | `/admin/metrics-registry/definitions` | GET /admin/metrics-registry/definitions List all metric defi... |
| POST | `/admin/metrics-registry/definitions` | POST /admin/metrics-registry/definitions Create a new metric... |
| GET | `/admin/metrics-registry/definitions/:id` | GET /admin/metrics-registry/definitions/:id Get a specific m... |
| PATCH | `/admin/metrics-registry/definitions/:id` | PATCH /admin/metrics-registry/definitions/:id Update a metri... |
| DELETE | `/admin/metrics-registry/definitions/:id` | DELETE /admin/metrics-registry/definitions/:id Soft delete a... |
| GET | `/admin/metrics-registry/definitions/:id/versions` | GET /admin/metrics-registry/definitions/:id/versions Get ver... |
| POST | `/admin/metrics-registry/definitions/:id/versions` | POST /admin/metrics-registry/definitions/:id/versions/rollba... |
| POST | `/admin/metrics-registry/execute` | POST /admin/metrics-registry/execute Execute a metric formul... |
| GET | `/admin/metrics-registry/placeholders` | GET /admin/metrics-registry/placeholders List all placeholde... |
| POST | `/admin/metrics-registry/placeholders` | POST /admin/metrics-registry/placeholders Create a new place... |
| POST | `/admin/metrics-registry/validate` | POST /admin/metrics-registry/validate Validate a formula and... |
| GET | `/admin/metrics/alerts` | GET /admin/metrics/alerts List all alerts |
| POST | `/admin/metrics/alerts` | POST /admin/metrics/alerts Create a new alert |
| GET | `/admin/metrics/alerts/:id` | GET /admin/metrics/alerts/:id Get a specific alert |
| POST | `/admin/metrics/alerts/:id` | POST /admin/metrics/alerts/:id Update an alert |
| DELETE | `/admin/metrics/alerts/:id` | DELETE /admin/metrics/alerts/:id Delete an alert |
| GET | `/admin/metrics/audit` | GET /admin/metrics/audit/recent Get recent changes across al... |
| POST | `/admin/metrics/audit` | POST /admin/metrics/audit/export Export audit trail for comp... |
| POST | `/admin/metrics/batch` | POST /admin/metrics/batch Compute multiple metrics in parall... |
| POST | `/admin/metrics/cache` | POST /admin/metrics/cache/warm Warm metrics cache for common... |
| DELETE | `/admin/metrics/cache` | DELETE /admin/metrics/cache Invalidate all metrics cache |
| GET | `/admin/metrics/cache` | GET /admin/metrics/cache/stats Get cache statistics |
| GET | `/admin/metrics/catalog` | GET /admin/metrics/catalog Search metrics catalog |
| POST | `/admin/metrics/catalog` | POST /admin/metrics/catalog Register new metric |
| GET | `/admin/metrics/catalog/:id` | GET /admin/metrics/catalog/:id Get metric by ID |
| PUT | `/admin/metrics/catalog/:id` | PUT /admin/metrics/catalog/:id Update metric |
| DELETE | `/admin/metrics/catalog/:id` | DELETE /admin/metrics/catalog/:id Archive metric (soft delet... |
| GET | `/admin/metrics/catalog/:id/dependencies` | GET /admin/metrics/catalog/:id/dependencies Get metric depen... |
| GET | `/admin/metrics/catalog/:id/dependents` | GET /admin/metrics/catalog/:id/dependents Get metrics that d... |
| POST | `/admin/metrics/catalog/:id/lifecycle` | POST /admin/metrics/catalog/:id/lifecycle Transition metric ... |
| GET | `/admin/metrics/catalog/:id/versions` | GET /admin/metrics/catalog/:id/versions Get metric version h... |
| POST | `/admin/metrics/catalog/seed-examples` | POST /admin/metrics/catalog/seed-examples Trigger the seed e... |
| POST | `/admin/metrics/catalog/validate` | POST /admin/metrics/catalog/validate Validate metric formula... |
| POST | `/admin/metrics/compute` | No description |
| GET | `/admin/metrics/dashboard` | GET /admin/metrics/dashboard — the COMBINED dashboard payloa... |
| GET | `/admin/metrics/dashboard/sales-channels` | GET /admin/metrics/dashboard/sales-channels Orders + revenue... |
| GET | `/admin/metrics/dashboard/summary` | GET /admin/metrics/dashboard/summary Summary metric cards on... |
| GET | `/admin/metrics/dashboard/unfulfilled-orders` | GET /admin/metrics/dashboard/unfulfilled-orders Unfulfilled ... |
| GET | `/admin/metrics/dashboard/unfulfilled-products` | GET /admin/metrics/dashboard/unfulfilled-products — products... |
| POST | `/admin/metrics/definitions` | POST /admin/metrics/definitions Create a new metric definiti... |
| GET | `/admin/metrics/definitions` | GET /admin/metrics/definitions List metric definitions with ... |
| GET | `/admin/metrics/definitions/:id` | GET /admin/metrics/definitions/:id Get a single metric defin... |
| PUT | `/admin/metrics/definitions/:id` | PUT /admin/metrics/definitions/:id Update a metric definitio... |
| DELETE | `/admin/metrics/definitions/:id` | DELETE /admin/metrics/definitions/:id Delete a metric defini... |
| POST | `/admin/metrics/fulfillment-report` | No description |
| GET | `/admin/metrics/performance` | GET /admin/metrics/performance Get current performance metri... |
| POST | `/admin/metrics/performance` | POST /admin/metrics/performance/report Generate and log perf... |
| GET | `/admin/metrics/performance/events` | GET /admin/metrics/performance/events Get recent computation... |
| GET | `/admin/metrics/placeholders` | GET /admin/metrics/placeholders List available placeholders |
| POST | `/admin/metrics/placeholders` | POST /admin/metrics/placeholders Create a new placeholder |
| GET | `/admin/metrics/rate-limit-status` | GET /admin/metrics/rate-limit-status Get rate limit metrics ... |
| DELETE | `/admin/metrics/rate-limit-status` | DELETE /admin/metrics/rate-limit-status Clear rate limit met... |
| POST | `/admin/metrics/report` | No description |
| GET | `/admin/metrics/reports` | No description |
| GET | `/admin/metrics/reports/top-products` | No description |
| GET | `/admin/metrics/suggestions` | GET /admin/metrics/suggestions Get AI-powered metric suggest... |
| GET | `/admin/metrics/templates` | GET /admin/metrics/templates List all metric templates |
| POST | `/admin/metrics/templates` | POST /admin/metrics/templates/:id/instantiate Create a metri... |
| GET | `/admin/metrics/templates/:id` | GET /admin/metrics/templates/:id Get a specific template |
| POST | `/admin/metrics/validate` | POST /admin/metrics/validate Validate a metric formula Rate ... |
| GET | `/admin/reports/cogs/alerts` | No description |
| GET | `/admin/reports/cogs/inventory-turnover` | No description |
| GET | `/admin/reports/cogs/margins` | No description |
| GET | `/admin/reports/cogs/snapshots` | No description |
| GET | `/admin/reports/promotions` | No description |
| GET | `/admin/reports/promotions/codes` | No description |
| GET | `/admin/reports/taxes/dashboard` | TAX QUERY SHAPE — three predicates on every one of the five ... |
| GET | `/admin/reports/taxes/export` | No description |

---

## 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:**
```typescript
{
  success,
  metrics,
  filters,
  requestedMetrics,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  message,
  date,
  metrics,
  filters,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `requests` | record | No |

### Response

**Success:**
```typescript
{
  results,
  summary,
}
```

### Example Request

```bash
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:**
```typescript
{
  metrics,
  count,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `name` | string | Yes |
| `description` | string | No |
| `category` | enum | Yes |
| `scope` | enum | Yes |
| `formula` | string | Yes |
| `data_type` | enum | Yes |
| `formatting_rules` | record | No |
| `org_id` | string | No |
| `owner_id` | string | No |
| `visibility` | enum | No |
| `is_system` | boolean | No |

### Response

**Success (201):**
```typescript
{
  metric,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  metric,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `name` | string | No |
| `description` | string | No |
| `formula` | string | No |
| `data_type` | enum | No |
| `formatting_rules` | record | No |
| `is_active` | boolean | No |
| `is_locked` | boolean | No |
| `visibility` | enum | No |
| `updated_by` | string | No |
| `force_update` | boolean | No |

### Response

**Success:**
```typescript
{
  metric,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  id,
  deleted,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  versions,
  count,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### 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:**
```typescript
{
  metric,
  message,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `metric_id` | string | Yes |
| `context` | record | No |

### Response

**Success:**
```typescript
{
  metric_id,
  result,
  execution_time_ms,
}
```

### Example Request

```bash
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:**
```typescript
{
  placeholders,
  count,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `key` | string | Yes |
| `display_name` | string | Yes |
| `description` | string | No |
| `data_source` | enum | Yes |
| `source_field` | string | Yes |
| `data_type` | enum | Yes |
| `default_aggregation` | enum | No |
| `category` | string | No |

### Response

**Success (201):**
```typescript
{
  placeholder,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `formula` | string | Yes |
| `metric_id` | string | No |

### Response

**Success:**
```typescript
{
  validation,
  is_valid,
}
```

### Example Request

```bash
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:**
```typescript
{
  alerts,
  count,
}
```

### Example Request

```bash
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):**
```typescript
{
  alert,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  alert,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### 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:**
```typescript
{
  alert,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success (200):**
```typescript
{
  id,
  deleted,
}
```

### Example Request

```bash
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:**
```typescript
{
  changes,
  count,
}
```

### Example Request

```bash
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

```bash
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:**
```typescript
{
  results,
  summary,
}
```

**Error (400):**
```typescript
{
  error,
}
```
**Error (400):**
```typescript
{
  error,
}
```
**Error (400):**
```typescript
{
  error,
}
```
**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  warmed,
  failed,
  durationMs,
  ranges,
}
```

**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  message,
}
```

**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  cache,
  performance,
}
```

**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  metrics,
  count,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `name` | string | Yes |
| `description` | string | No |
| `category` | enum | Yes |
| `scope` | enum | Yes |
| `formula` | string | Yes |
| `dataType` | enum | Yes |
| `formattingRules` | record | No |
| `dependencies` | array | No |
| `tags` | array | No |
| `visibility` | enum | No |
| `orgId` | string | No |
| `ownerId` | string | No |
| `isSystem` | boolean | No |

### Response

**Success (201):**
```typescript
{
  metric,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  metric,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `name` | string | No |
| `description` | string | No |
| `formula` | string | No |
| `formattingRules` | record | No |
| `dependencies` | array | No |
| `tags` | array | No |
| `visibility` | enum | No |
| `isActive` | boolean | No |
| `isLocked` | boolean | No |
| `forceUpdate` | boolean | No |

### Response

**Success:**
```typescript
{
  metric,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  dependencies,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  dependents,
  count,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `state` | enum(draft, active, deprecated, archived) | Yes |

### Response

**Success:**
```typescript
{
  metric,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  versions,
  count,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
  summary,
  metrics,
}
```

**Error (500):**
```typescript
{
  error,
  message,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `formula` | string | Yes |

### Response

**Success:**
```typescript
{
  validation,
}
```

**Error (503):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  message,
  metrics,
  filters,
  computeTime,
}
```

### Example Request

```bash
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):**
```typescript
{
  code,
  type,
  message,
  error,
  details,
}
```

### Example Request

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `name` | string | Yes |
| `description` | string | No |
| `category` | enum | Yes |
| `scope` | enum | Yes |
| `formula` | string | Yes |
| `data_type` | enum | Yes |
| `formatting_rules` | record | No |
| `org_id` | string | No |
| `owner_id` | string | No |
| `visibility` | enum | No |
| `is_system` | boolean | No |

### Response

**Success (201):**
```typescript
{
  metric,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (400):**
```typescript
{
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  metrics,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (500):**
```typescript
{
  message,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  metric,
}
```

**Error (404):**
```typescript
{
  message,
}
```
**Error (500):**
```typescript
{
  message,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `name` | string | No |
| `description` | string | No |
| `formula` | string | No |
| `data_type` | enum | No |
| `formatting_rules` | record | No |
| `is_active` | boolean | No |
| `is_locked` | boolean | No |
| `visibility` | enum | No |
| `updated_by` | string | No |
| `force_update` | boolean | No |

### Response

**Success:**
```typescript
{
  metric,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (400):**
```typescript
{
  message,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Error (400):**
```typescript
{
  message,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `date` | object | No |
| `fulfillmentIds` | array | No |
| `orderIds` | array | No |
| `status` | array | No |
| `providerIds` | array | No |
| `shippingOptionIds` | array | No |
| `locationIds` | array | No |
| `regionIds` | array | No |
| `countryCodes` | array | No |
| `states` | array | No |
| `search` | string | No |

### Response

**Success:**
```typescript
{
  success,
  report,
}
```

### Example Request

```bash
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:**
```typescript
{
  performance,
}
```

**Error (500):**
```typescript
{
  error,
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  message,
  performance,
}
```

**Error (500):**
```typescript
{
  error,
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  events,
  count,
}
```

**Error (500):**
```typescript
{
  error,
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  placeholders,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (500):**
```typescript
{
  message,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `data_source` | string | No |
| `category` | string | No |
| `is_active` | string | No |

### Response

**Success (201):**
```typescript
{
  placeholder,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (400):**
```typescript
{
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  metrics,
}
```

**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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:**
```typescript
{
  success,
  message,
}
```

**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `date` | object | No |
| `orderIds` | array | No |
| `displayIds` | array | No |
| `customerIds` | array | No |
| `customerEmails` | array | No |
| `status` | array | No |
| `paymentStatus` | array | No |
| `regionIds` | array | No |
| `salesChannelIds` | array | No |
| `productIds` | array | No |
| `countryCodes` | array | No |
| `states` | array | No |
| `search` | string | No |

### Response

**Success:**
```typescript
{
  success,
  report,
}
```

### Example Request

```bash
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:**
```typescript
{
  days,
  meta,
}
```

**Error (400):**
```typescript
{
  message,
  issues,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  code,
  message,
  maxDays,
  requestedDays,
}
```
**Error (500):**
```typescript
{
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  products,
  meta,
}
```

**Error (400):**
```typescript
{
  message,
  issues,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  code,
  message,
  maxDays,
  requestedDays,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (500):**
```typescript
{
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  suggestions,
  count,
}
```

### Example Request

```bash
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:**
```typescript
{
  templates,
  count,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `category` | string | No |
| `tags` | array | No |
| `search` | string | No |

### Response

**Success (201):**
```typescript
{
  metric,
}
```

### Example Request

```bash
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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  template,
}
```

### Example Request

```bash
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

| Field | Type | Required |
|-------|------|----------|
| `formula` | string | Yes |

### Response

**Success:**
```typescript
{
  validation,
}
```

**Error (400):**
```typescript
{
  message,
  errors,
}
```
**Error (400):**
```typescript
{
  message,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  code,
  from,
  to,
  summary,
  rows,
  limit,
  offset,
  has_more,
  next_offset,
}
```

**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  code,
  message,
  maxDays,
  requestedDays,
}
```
**Error (503):**
```typescript
{
  code,
  message,
}
```

### Example Request

```bash
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:**
```typescript
{
  codes,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
  issues,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (400):**
```typescript
{
  code,
  message,
  maxDays,
  requestedDays,
}
```
**Error (500):**
```typescript
{
  code,
  type,
  message,
  error,
  details,
}
```

### Example Request

```bash
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):**
```typescript
{
  message,
  issues,
}
```
**Error (400):**
```typescript
{
  message,
}
```
**Error (500):**
```typescript
{
  code,
  type,
  message,
  error,
}
```

### Example Request

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

---