> ## 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.

# Connect Shopify to Vortex IQ

> Connect Shopify to Vortex IQ for 78 KPI cards, cross-platform alerts, Vortex Staging for safe deploys, and Vortex Backup for instant rollback.

Connecting your Shopify store to Vortex IQ gives the AI OS a live read on every order, variant, customer, and revenue movement in your store. The moment the connector goes active, Nerve Centre populates with Shopify-specific KPI cards, Vortex Mind gains a diagnostic surface for root-cause analysis, and Ask Viq can answer revenue and inventory questions in plain English.

## What data Vortex IQ reads from Shopify

Vortex IQ connects to the Shopify Admin GraphQL API and ingests the following data:

<AccordionGroup>
  <Accordion title="Orders and revenue">
    * Order totals (`totalPrice`) across all sales channels: Online Store, Shop POS, Buy Button, TikTok Shop, B2B, and any marketplace app channel
    * Financial status, fulfilment status, and cancellation state per order
    * Discount codes and discount amounts applied
    * Refunds and refund line items
    * Shipping amounts and methods
    * Tax amounts and tax inclusion flag
    * Payment gateway per order
  </Accordion>

  <Accordion title="Products and inventory">
    * All active product variants with `totalInventory` and per-location `InventoryLevel.available`
    * Product status (active, draft, archived)
    * Product type, vendor, and tags
    * SKU and barcode per variant
    * Collection membership
  </Accordion>

  <Accordion title="Customers">
    * Customer records with email verification state
    * Order frequency and lifetime value per customer
    * Customer geography (country, city)
    * New vs returning customer segmentation
  </Accordion>
</AccordionGroup>

<Note>
  Vortex IQ reads Shopify data using scheduled, rate-limited API calls. No customer-facing store performance is affected. All access is read-only; Vortex IQ never writes to your store.
</Note>

## How to connect

<Steps>
  <Step title="Open Connected Sources">
    In your Vortex IQ workspace, go to **Settings → Connected Sources**. You need Admin role in the workspace to connect sources.
  </Step>

  <Step title="Find the Shopify card">
    Locate the Shopify connector card and click **+ Connect**. The connector drawer slides in showing the scopes Vortex IQ will request.
  </Step>

  <Step title="Authenticate with Shopify">
    Click **Connect with Shopify**. A new tab opens at Shopify's authorisation screen. Sign in with the account that has admin access to your store, then review the requested scopes and click **Install app**.
  </Step>

  <Step title="Select sandbox or production">
    If you want to test against a development store, toggle **Sandbox** before connecting. For a live store, leave it on **Production** (the default).
  </Step>

  <Step title="Wait for the first data pull">
    Shopify KPI cards appear in Nerve Centre within 5 to 15 minutes. A full historical order backfill takes 1 to 4 hours. You can navigate away while the pull runs in the background.
  </Step>
</Steps>

<Note>
  The scopes Vortex IQ requests are read-only: `read_orders`, `read_products`, `read_inventory`, `read_customers`, `read_analytics`. Vortex IQ does not request write scopes.
</Note>

## Available KPI cards

Vortex IQ populates 78 Nerve Centre cards from your Shopify data across the following categories.

<CardGroup cols={2}>
  <Card title="Revenue and growth" icon="chart-line">
    **Total Revenue** - Gross revenue (`SUM(totalPrice)`) across all channels for the period, compared to the prior period. Alerts when revenue drops more than 15% vs prior 30 days.

    **Revenue Over Time** - Daily revenue trend with period-over-period sparkline.

    **Average Order Value (AOV)** - Revenue ÷ Order Count. Tells you whether a revenue move was driven by volume or basket size.

    **Revenue by Channel** - Breaks revenue by source (Online Store, POS, TikTok Shop, B2B, etc.).

    **Revenue by Day of Week** - Identifies your highest-revenue days for campaign timing.

    **Revenue by Hour** - Intra-day revenue pattern for staffing and ad scheduling.
  </Card>

  <Card title="Orders and operations" icon="box">
    **Order Count** - Total orders placed in the period.

    **Orders Over Time** - Daily order volume sparkline.

    **Unfulfilled Orders** - Count of orders awaiting fulfilment.

    **Fulfilment Rate** - Share of orders fulfilled within the expected window.

    **Cancellation Rate** - Cancelled orders as a share of total, with trend.

    **Financial Status** - Breakdown of orders by payment state (paid, pending, refunded, voided).
  </Card>

  <Card title="Inventory" icon="warehouse">
    **Products with Zero/Negative Stock** - Live count of active variants at zero or negative inventory. Alerts the moment any active variant hits zero. Negative inventory (oversold) is flagged as the most urgent subset.

    **Stock vs Sales** - Shows non-OOS variants heading toward stockout before they hit zero.

    **Inventory Distribution** - Fat-tail view of stock levels across your catalogue.

    **OOS Spike Alert** - Fires when the out-of-stock variant count rises sharply in a short window.
  </Card>

  <Card title="Customers" icon="users">
    **Customer Count** - Total active customers.

    **New Customers** - First-time buyers in the period.

    **Repeat Rate** - Share of customers who bought more than once.

    **Churn Risk** - Customers showing lapse signals.

    **Customer Segments** - Breakdown by RFM-style segment.

    **Top Customers** - Highest-value customers by lifetime spend.
  </Card>

  <Card title="Refunds and returns" icon="arrow-left">
    **Refund Rate** - Refunds as a share of orders in the period.

    **Refund Value** - Total value of refunds issued.

    **Refund Spike Alert** - Fires when the refund rate rises sharply.

    **Top Refunded Products** - Products with the highest refund frequency.

    **Refunds Over Time** - Daily refund trend.
  </Card>

  <Card title="Store health and alerts" icon="heart-pulse">
    **Store Health Score** - Composite 0-100 score blending revenue trend (30%), fulfilment rate (25%), refund rate (25%), and OOS count (20%). Alerts when the score falls below 70.

    **Revenue Drop Alert** - Fires when revenue drops more than 15% vs prior 30 days.

    **Fulfilment Delay Alert** - Fires when fulfilment rate drops below threshold.

    **Negative Review Burst Alert** - Fires on a sudden spike in low-rating signals.
  </Card>
</CardGroup>

### Cross-platform cards

When you connect ad platforms (Google Ads, Meta Ads, TikTok Ads) alongside Shopify, Vortex IQ unlocks additional cross-platform cards:

| Card                                  | What it shows                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| Active Ads on Out-of-Stock SKUs       | Ad spend burning on variants with zero inventory - the highest-ROI cross-platform pause |
| Revenue at Risk from active incidents | Live revenue impact estimate when a Datadog or New Relic incident is open               |
| Catalogue Drift vs Amazon             | SKUs active on Amazon but OOS on Shopify - an inventory mis-sync and brand-trust risk   |
| Klaviyo Email Revenue Share           | Share of Shopify revenue attributable to Klaviyo email flows                            |
| Amazon Revenue Share                  | Comparison of Amazon marketplace revenue against Shopify direct                         |

## Vortex Staging and Vortex Backup apps

Shopify merchants get access to two dedicated Vortex IQ apps available in the Shopify App Store.

<Tabs>
  <Tab title="Vortex Staging">
    **Vortex Staging** gives your Shopify store a real staging environment - something Shopify itself does not provide natively.

    Key capabilities:

    * **Multi-environment linking** - Link Production, Staging, UAT, and Integration stores under one Vortex IQ tenant
    * **Bulk migration** - Clone the live storefront into a staging store in one operation; 20+ entity types covered including Products, Collections, Customers, Orders, Themes, Discount Codes, Gift Cards, Navigation Menus, URL Redirects, Metaobjects, and more
    * **Selective migration** - Pick specific products, themes, or collections when you need only a subset
    * **Customer data anonymisation** - Scramble PII when migrating to non-production environments so your team works against production-shaped volumes without touching real personal data
    * **Git-driven theme deployment** - Connect a GitHub repository and deploy theme changes through an approval workflow, with rollback to any previous version on demand
    * **Migration history and rollback** - Every migration is logged with per-entity progress and downloadable error logs
    * **Notifications** - Email, Slack, and Microsoft Teams alerts when migrations complete or fail

    Available in the Shopify App Store for standard, Shopify Advanced, and Shopify Plus plans.
  </Tab>

  <Tab title="Vortex Backup">
    **Vortex Backup** gives your Shopify store an undo button - something Shopify itself does not provide natively.

    Key capabilities:

    * **19 entity types covered** - Products, Collections, Customers, Orders, Discount Codes, Blogs, Pages, Files, Themes, Gift Cards, Navigation Menus, URL Redirects, Markets, Delivery Profiles, Locations, Price Lists, Catalogs, Metaobject Definitions, and Metaobjects
    * **Real-time webhook backup** for Products, Collections, Customers, and Orders - every change captured as Shopify fires the webhook
    * **Manual full backup** for the remaining entity types Shopify does not expose via webhook
    * **Per-record restore** - Roll back a single product, page, or delivery profile to any stored version without touching anything else in the store
    * **Side-by-side version comparison** - Compare any two stored versions in Summary or JSON view before deciding to restore
    * **Theme backup with full ZIP archive** - Restore creates a new theme; your live theme is never overwritten
    * **File and media backup to Azure Blob Storage** - Images, videos, 3D models, documents

    Available in the Shopify App Store.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The OAuth pop-up was blocked">
    Allow pop-ups for `app.vortexiq.ai` in your browser settings. Brave and Firefox with strict mode block pop-ups by default. After allowing, click **+ Connect** again.
  </Accordion>

  <Accordion title="Shopify says 'this app does not have access to your account'">
    You are signed into Shopify with an account that does not have admin access to the store you want to connect. Sign out of Shopify, sign in with the store owner or admin account, then retry the connection from Vortex IQ.
  </Accordion>

  <Accordion title="KPI cards are empty after connecting">
    The first data pull typically completes within 5 to 15 minutes for KPI cards and up to 4 hours for full historical orders. If cards are still empty after 4 hours, open **Settings → Connected Sources**, find your Shopify connection, and use the manual refresh control to trigger a new pull.
  </Accordion>

  <Accordion title="Revenue in Vortex IQ differs from Shopify Admin">
    Several legitimate reasons cause small differences: time-zone boundaries (Shopify reports run on shop timezone; Vortex IQ runs on UTC by default), test orders (Vortex IQ does not yet filter `Order.test = true`), and multi-currency stores (Vortex IQ sums `totalPrice` in each order's own currency without FX conversion). For multi-currency stores, use the currency-filtered view in Nerve Centre.
  </Accordion>

  <Accordion title="OOS card count does not match Shopify Admin">
    Vortex IQ aggregates inventory across all active fulfilment locations. A variant with zero stock in one location but stock available in another will not appear on the OOS card. Shopify Admin shows per-location inventory by default. To match the card, filter Shopify Admin → Products → Inventory to Active status and view the aggregate Available total.
  </Accordion>
</AccordionGroup>