> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Medusa audit profile, Vortex IQ

> What the Vortex IQ Medusa health audit checks: Medusa: Stock, Refunds, Fulfilment & Cross-Channel Leak

**[Nerve Centre KPIs](/nerve-centre/kpi-cards/medusa) · [Audit Profile](/nerve-centre/kpi-cards/medusa/audit) · [Sentiment Settings](/nerve-centre/kpi-cards/medusa/sentiment)**

Medusa is a headless commerce backend where data is fragmented across the Medusa modules, the storefront framework, the payment provider, the search service, and the CDN. This audit answers four questions for engineering-led teams: are we losing sales to out-of-stock SKUs, has refund rate spiked, are orders stuck unfulfilled, and is the catalogue healthy enough to convert? Cross-references commerce / ad / marketplace / website-performance siblings to compute revenue-at-risk and auto-pause spend when goods can't ship.

## What this audit checks

### Authentication & access

* Admin API token still valid (auth on /admin/users/me)
* Backend reachable - self-hosted / Medusa Cloud base URL responds
* Required modules enabled (orders, products, inventory, customers) - headless installs can disable modules
* Publishable key sales-channel scope matches the merchant's expectation

### Stock & inventory health (the highest-leverage area)

* Variants with inventory\_quantity \<= 0 and manage\_inventory true - actively losing sales NOW
* Variants below reorder point (low-stock reorder-window trigger)
* Stock-out burst - >5 variants transitioned to OOS in last 1h (sync break or flash-sale stockout)
* Backorder enabled on OOS variants without clear customer messaging

### Refunds & returns

* Refund rate > 5% over 30d (returns-health headline)
* Refund-rate spike > 2σ vs 30d baseline (product defect / fraud / fulfilment failure)
* Refund value up > 25% vs prior period (cash impact of returns)
* Per-SKU refund concentration - one product driving the spike

### Fulfilment & order flow

* Unfulfilled orders > 2× 30d average (backlog = customer-promise risk)
* Orders stuck in awaiting / not\_paid > 24h (payment-provider issue or dropoff)
* Cancellation rate > 3% over 30d
* Region-specific order drop > 50% vsP (region-specific checkout/payment/storefront outage)

### Catalogue quality

* Products missing description (suppresses conversion + SEO)
* Products missing thumbnail / image
* Variants missing SKU (breaks marketplace + ad parity joins)
* Variants missing price in an active region's currency

### Cross-channel: revenue at risk

* Cross-channel: OOS SKU appears in active google\_ads campaign - \$ wasted (sibling = google\_ads.product\_ad active on medusa.variant inventory\_quantity\<=0)
* Cross-channel: OOS SKU appears in active amazon\_ads campaign - \$ wasted
* Cross-channel: SKU OOS or price-divergent on Medusa vs marketplace listing (sibling = amazon/ebay.marketplace\_listing active)
* Cross-channel: slow Core Web Vitals on top revenue pages driving cart loss (sibling = website\_performance.crux\_page LCP p75 > 2.5s)
* Cross-channel: high-value customer unengaged in email tool (sibling = klaviyo/mailchimp last\_open\_at \< 90d\_ago)

## Severity thresholds

| Signal                        | Warn | Critical |
| ----------------------------- | ---- | -------- |
| `out_of_stock_count`          | 1    | 5        |
| `refund_rate_pct`             | 2    | 5        |
| `cancellation_rate_pct`       | 1    | 3        |
| `unfulfilled_count`           | 10   | 50       |
| `awaiting_payment_aged_count` | 5    | 10       |
| `region_order_drop_pct`       | 30   | 50       |
| `repeat_rate_pct`             | 20   | 10       |
| `missing_desc_pct`            | 5    | 20       |
| `oos_with_active_spend_count` | 1    | 5        |

## Data sources

* `GET {backend_url}/admin/users/me` - Auth probe + admin identity
* `GET {backend_url}/admin/orders` - Order status, payment/fulfilment state, refunds, region/currency split
* `GET {backend_url}/admin/products` - Catalogue size + description/image gaps
* `GET {backend_url}/admin/product-variants` - Per-variant SKU + inventory\_quantity (the OOS join key)
* `GET {backend_url}/admin/inventory-items` - Inventory module levels for low-stock / reorder checks
* `GET {backend_url}/admin/returns` - Return rate + reasons + processing time
* `GET {backend_url}/admin/customers` - Customer base, repeat rate, email-engagement join key
* `GET {backend_url}/admin/regions` - Region + currency model for multi-currency revenue split