> ## 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 on Vortex IQ

> Monitor store performance, find catalogue and operational problems, and safely apply approved changes to Medusa.

Monitor store performance, find catalogue and operational problems, and safely apply approved changes to Medusa.

[Connect or manage this source](https://app.vortexiq.ai/workbench/settings/sources) · [View setup guide](/integrations/medusa) · [Create a workflow](https://app.vortexiq.ai/workbench/flows/create?connector=medusa)

<CardGroup cols={5}>
  <Card title="32">
    performance signals
  </Card>

  <Card title="8">
    automated checks
  </Card>

  <Card title="1">
    prepared fixes
  </Card>

  <Card title="Ready to build yours">
    workflows
  </Card>

  <Card title="8">
    API operations
  </Card>
</CardGroup>

<Tabs>
  <Tab title="Overview">
    ### What you can achieve

    Capabilities are grouped around merchant outcomes, not API terminology.

    <CardGroup cols={2}>
      <Card title="Grow revenue">
        Improve discovery, conversion, campaigns and repeat purchase.
      </Card>

      <Card title="Protect revenue">
        Find failures, leaks and risks before they cost sales.
      </Card>

      <Card title="Run operations">
        Monitor orders, fulfilment, delivery and settlement.
      </Card>

      <Card title="Customer experience">
        Find storefront, speed, accessibility and journey problems.
      </Card>

      <Card title="Catalogue quality">
        Identify missing, inconsistent or outdated product data.
      </Card>

      <Card title="Control risk and change">
        Keep tracking, access and change under governed control.
      </Card>
    </CardGroup>

    ### From connection to verified outcome

    The controlled sequence every capability follows. Nothing changes a connected system without the approval step.

    <Steps>
      <Step title="Connect">
        Authorise the source. Scopes are shown before access is granted.
      </Step>

      <Step title="Monitor">
        Watch the signals against your own baselines, not universal defaults.
      </Step>

      <Step title="Detect">
        Run checks and gather evidence specific to your store.
      </Step>

      <Step title="Recommend">
        Explain what happened, why it matters and the proposed action.
      </Step>

      <Step title="Approve">
        You review scope, risk and reversibility before anything changes.
      </Step>

      <Step title="Execute">
        Apply through governed connector operations.
      </Step>

      <Step title="Verify">
        Confirm the intended result and keep the receipt.
      </Step>
    </Steps>

    No changes are made without the configured approval policy. Read-only operations do not modify the connected system; schedules, access scopes, API usage and data handling remain governed by Vortex IQ controls.
  </Tab>

  <Tab title="Monitor (32)">
    ### Monitor performance

    32 performance signals. Open an outcome to see its signals and how each one alerts. Read-only operations do not modify the connected system.

    <AccordionGroup>
      <Accordion title="Protect revenue (14 signals)">
        | Signal                                      | Alert behaviour    | What it tracks                                                                                                                                        |
        | ------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **Cancellation Rate**                       | Alert band 1 / 3   | Canceled orders / total orders. Rising cancellation = fulfilment, fraud, or stock-promise problems.                                                   |
        | **Cart Loss from Slow Pages**               | Merchant rule      | Estimated revenue lost where slow Core Web Vitals on top storefront pages drive cart abandonment. Headless stores own their own front end, so this is |
        | **Catalogue Drift vs Marketplace Listings** | Merchant rule      | Same SKU OOS or mispriced on Medusa vs a marketplace = oversell risk and catalogue drift.                                                             |
        | **High-Value Customers Unengaged on Email** | Merchant rule      | Top spenders going cold in the email tool. Trigger a win-back before they churn.                                                                      |
        | **Low-Stock Products**                      | Merchant rule      | Variants approaching zero inventory from the inventory module. Reorder-window trigger.                                                                |
        | **OOS SKUs with Active Ad Spend**           | Merchant rule      | Spend burning on SKUs the inventory module says can't ship. Pause immediately.                                                                        |
        | **Out-of-Stock Products**                   | Alert band 0 / 5   | Variants with inventory\_quantity \<= 0 and manage\_inventory true. Direct lost-sales signal.                                                         |
        | **Refund Rate**                             | Alert band 2 / 5   | Refunded order count / total orders. The headline returns-health metric; spikes flag product or fulfilment issues.                                    |
        | **Refund Value**                            | Merchant rule      | Total refunded\_total in the window. Tracks the cash impact of returns, not just the count.                                                           |
        | **Refund-Rate Spike**                       | Alert band 2 / 5   | Sudden refund surge = product defect, fraud wave, or fulfilment failure. Surfaces to the ops feed immediately.                                        |
        | **Refunded Order Count**                    | Merchant rule      | Count of orders with a refund in the window. Volume companion to refund rate.                                                                         |
        | **Revenue at Risk**                         | Merchant rule      | Live estimate of revenue exposed by OOS SKUs, unfulfilled aged orders, and refund spikes. Top-of-screen risk gauge.                                   |
        | **Stock-Out Burst (>5 SKUs in \<1h)**       | Merchant rule      | A burst of SKUs going OOS at once usually means an inventory-sync break or a flash-sale stockout.                                                     |
        | **Unfulfilled Orders**                      | Alert band 10 / 50 | Orders in not\_fulfilled / partially\_fulfilled from the fulfilment module. Backlog = customer-promise risk.                                          |
      </Accordion>

      <Accordion title="Grow revenue (10 signals)">
        | Signal                                                  | Alert behaviour    | What it tracks                                                                                                                                           |
        | ------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **Average Order Value**                                 | Alert band 0 / -5  | Revenue / order count. Falling AOV with flat volume signals discount creep or basket-size erosion.                                                       |
        | **Catalogue Gaps (missing desc / image / SKU / price)** | Alert band 5 / 20  | Products missing description, thumbnail, variant SKU, or price. Headless storefronts have no SaaS guard-rails, so gaps silently suppress conversion.     |
        | **Coupon Usage Rate**                                   | Alert band 20 / 40 | Share of orders (30d) with a linked promotion requiring a customer-entered code (Promotion.is\_automatic=false), from /admin/orders?fields=\*promotions. |
        | **New vs Returning Customers**                          | Watch only         | Split of first-time vs repeat purchasers in the window. Acquisition-vs-retention balance.                                                                |
        | **Order Count**                                         | Alert band 0 / -10 | Count of orders placed in the window. Pairs with revenue to separate volume from value moves.                                                            |
        | **Repeat Purchase Rate**                                | Alert band 25 / 10 | Share of customers with orders\_count > 1. Low repeat rate = retention problem worth a win-back flow.                                                    |
        | **Revenue Trend**                                       | Watch only         | Daily revenue over 90 days. Visual baseline the alert thresholds read against.                                                                           |
        | **Revenue by Currency**                                 | Watch only         | Revenue grouped by currency\_code. Multi-currency is first-class in Medusa, so currency mix matters for FX and pricing.                                  |
        | **Revenue by Region**                                   | Watch only         | Per-region revenue split from the Medusa region model. Reveals which regions carry the business and which are dormant.                                   |
        | **Total Revenue**                                       | Alert band 0 / -5  | Captured order revenue across the selected window, summed from /admin/orders. Headline pulse metric.                                                     |
      </Accordion>

      <Accordion title="Run operations (4 signals)">
        | Signal                       | Alert behaviour    | What it tracks                                                                                                                                           |
        | ---------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **Awaiting Payment Orders**  | Merchant rule      | Orders stuck in awaiting / not\_paid > 24h usually = payment-provider issue or customer-side dropoff.                                                    |
        | **Fulfillment Rate**         | Alert band 95 / 90 | Orders with fulfillment\_status fulfilled or shipped ÷ total orders (30d), from the same /admin/orders fetch used elsewhere. partially\_shipped and othe |
        | **Fulfilment Status Mix**    | Watch only         | Distribution of fulfillment\_status across orders. Shows where orders pile up in the fulfilment pipeline.                                                |
        | **Order Processing Backlog** | Alert band 10 / 50 | Unfulfilled orders piling up above baseline - fulfilment provider or warehouse bottleneck.                                                               |
      </Accordion>

      <Accordion title="Catalogue quality (2 signals)">
        | Signal                           | Alert behaviour   | What it tracks                                                                                                                                         |
        | -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | **Products Missing Description** | Alert band 5 / 20 | Share of fetched products with an empty description field, from /admin/products. A single-concept percent cut of the description component already fol |
        | **Total Products**               | Watch only        | Published product count from /admin/products. Catalogue-size baseline.                                                                                 |
      </Accordion>

      <Accordion title="Customer experience (1 signals)">
        | Signal                         | Alert behaviour | What it tracks                                                                                                              |
        | ------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
        | **Region-Specific Order Drop** | Merchant rule   | If one region stops producing orders while others continue, indicates a region-specific checkout/payment/storefront outage. |
      </Accordion>

      <Accordion title="Control risk and change (1 signals)">
        | Signal              | Alert behaviour | What it tracks                                |
        | ------------------- | --------------- | --------------------------------------------- |
        | **Total Customers** | Watch only      | Total customer records from /admin/customers. |
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Audit (8)">
    ### Audit risks and opportunities

    A fix status appears only where the action, inputs, approval, verification and recovery controls are mapped. Candidate remediations are never executable. Open a check for the detail.

    <AccordionGroup>
      <Accordion title="Fulfillment rate below 90%">
        **Severity** critical · **Outcome** Protect revenue · **Fix status** Candidate remediation

        When more than 1 order in 10 is failing to reach fulfilment, customers have paid for goods that are not shipping on time; refunds, chargebacks and support load follow quickly.

        A likely corrective operation exists, but its mapping and recovery are not yet complete, so execution is not offered. Evidence and recommended manual steps are provided.

        Reference: `ECOM-FULFIL-001`
      </Accordion>

      <Accordion title="Cancellation rate above 10% over 30d">
        **Severity** high · **Outcome** Protect revenue · **Fix status** Report only

        More than 1 in 10 orders is being cancelled. Unlike a return, a cancellation often means the customer changed their mind or hit a problem before the order even shipped, checkout friction, a payment failure, an unexpectedly long delivery estimate, which usually points to a fixable step in the order f

        Vortex IQ detects and explains this; resolution is manual, with evidence and recommended steps.

        Reference: `ECOM-CANCEL-001`
      </Accordion>

      <Accordion title="Refund rate above 5% over 30d">
        **Severity** high · **Outcome** Protect revenue · **Fix status** Candidate remediation

        More than 1 in 20 orders is being refunded. Beyond the direct revenue loss, this rate also carries payment-cost consequences, processors and payment gateways watch refund and dispute rates, and a sustained high rate can affect processing terms independent of the lost sale itself.

        A likely corrective operation exists, but its mapping and recovery are not yet complete, so execution is not offered. Evidence and recommended manual steps are provided.

        Reference: `ECOM-REFUND-001`
      </Accordion>

      <Accordion title="Discount > 20% of revenue (margin erosion)">
        **Severity** medium · **Outcome** Grow revenue · **Fix status** Report only

        Discounting above roughly 20 percent of revenue erodes margin quickly, often without lifting volume enough to pay for itself, and trains customers to wait for codes.

        Vortex IQ detects and explains this; resolution is manual, with evidence and recommended steps.

        Reference: `ECOM-DISCOUNT-001`
      </Accordion>

      <Accordion title="Products with zero or negative stock">
        **Severity** medium · **Outcome** Grow revenue · **Fix status** Candidate remediation

        Every product at zero or negative stock is a page a customer can still find, still add to cart in some storefront setups, and still be disappointed by. Zero-stock listings that stay live also keep spending any ad budget or SEO ranking pointed at them, driving traffic to a product nobody can actually

        A likely corrective operation exists, but its mapping and recovery are not yet complete, so execution is not offered. Evidence and recommended manual steps are provided.

        Reference: `ECOM-INVENTORY-001`
      </Accordion>

      <Accordion title="Repeat-customer rate below 20%">
        **Severity** medium · **Outcome** Grow revenue · **Fix status** Candidate remediation

        Fewer than 1 in 5 customers comes back for a second order. Acquiring a first-time customer is almost always the most expensive part of earning their business, so a repeat rate this low means the store is paying that acquisition cost repeatedly instead of earning a second (cheaper) sale from customer

        A likely corrective operation exists, but its mapping and recovery are not yet complete, so execution is not offered. Evidence and recommended manual steps are provided.

        Reference: `ECOM-CUSTOMER-001`
      </Accordion>

      <Accordion title="Products missing SEO title">
        **Severity** low · **Outcome** Grow revenue · **Fix status** Prepared fix

        Products without SEO titles compete in search under their bare product names; pages that could rank for buying keywords stay invisible.

        A prepared, approval-gated fix exists: the proposed change, affected records, risk, reversibility and verification are shown before execution.

        Reference: `ECOM-CATALOGUE-002`
      </Accordion>

      <Accordion title="Products missing description">
        **Severity** low · **Outcome** Grow revenue · **Fix status** Candidate remediation

        A product with no description gives a shopper nothing to evaluate beyond a photo and a price. It also gives search engines almost nothing to index, so these products are simultaneously converting worse for visitors who do find them and ranking worse in organic search for anyone who has not.

        A likely corrective operation exists, but its mapping and recovery are not yet complete, so execution is not offered. Evidence and recommended manual steps are provided.

        Reference: `ECOM-CATALOGUE-001`
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Automate">
    ### Automate approved work

    Vortex IQ is integrated with **8 read** and **0 write** operations across customers, inventory items, orders, products, product variants, regions on Medusa. Combine them with anything from the **over 13,000 operations across more than 200 connectors** to automate the work in your own words.

    Changes follow your configured approval policy: the target, proposed change, affected records, risk, reversibility and verification plan are shown before execution.

    [Create a workflow](https://app.vortexiq.ai/workbench/flows/create?connector=medusa)

    #### Ready to build your first Medusa workflow

    Pick a trigger, add the operations above as steps, and every step that changes data pauses for your approval. Monitoring and audits are live now and can start any workflow you build.

    <Accordion title="Browse the operations you can build with">
      | Resource         | Read operations | Write operations |
      | ---------------- | --------------- | ---------------- |
      | customers        | 1               | 0                |
      | inventory items  | 1               | 0                |
      | orders           | 1               | 0                |
      | products         | 1               | 0                |
      | product variants | 1               | 0                |
      | regions          | 1               | 0                |
      | returns          | 1               | 0                |
      | usermes          | 1               | 0                |

      Signed-in users see the full catalogue in the workflow builder, filtered to the sources they have connected.
    </Accordion>
  </Tab>
</Tabs>