# Shopify Insights

> Shopify orders, sales, refunds and top products as server-side aggregates for a date window - no customer data.

Order and sales aggregates from your Shopify store for any date window,
computed inside FlyMyAI and returned without customer data - the numbers a
performance-marketing agent needs next to ad spend (revenue, AOV, refunds,
top products). Connects with a custom-app token you create in the store admin;
no Partner app, no OAuth.

## What it can do

| Method | What it does |
| --- | --- |
| `shopify_shop_info` | Store name, domain, currency, timezone and plan - confirms the connection. |
| `shopify_orders_summary` | Orders, cancelled and refunded orders, gross sales, discounts, refunds, net sales, shipping, tax, total revenue, AOV, refund rate, breakdown by day / week / month, top products, return / financial / fulfillment status counts. |
| `shopify_top_products` | Top products by revenue and units for the window, plus top refunded products. |
| `shopify_returns_summary` | Refunded orders, refund amount, refund rate, return statuses and top refunded products, by period. |

Customer names, e-mails and addresses are never requested from Shopify, so
they cannot reach the model. A call scans up to 2400 orders; `truncated: true`
means narrow the window.

## How to get credentials

1. In the store admin open **Settings → Apps and sales channels → Develop
   apps** (allow custom app development if asked) → **Create an app**.
2. **Configure Admin API scopes**: `read_orders`, `read_products` (add
   `read_all_orders` if you need orders older than 60 days - Shopify grants it
   on request).
3. **Install app**, then **API credentials → Admin API access token → Reveal
   token once** (`shpat_...`).

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `SHOPIFY_SHOP` | Your `*.myshopify.com` subdomain, e.g. `myshop` |
| `SHOPIFY_ADMIN_TOKEN` | Develop apps → your app → API credentials → Admin API access token |

## Troubleshooting

- **HTTP 401 / 403** - the token was rejected or lacks `read_orders` /
  `read_products`; re-check the custom app's scopes and reinstall it.
- **Only the last 60 days of orders** - add the `read_all_orders` scope.
- **`truncated: true`** - the window has more than 2400 orders; split it.
- **Throttled** - Shopify's GraphQL cost limit; the tool retries with backoff,
  narrow the window if it persists.

## Links

- [Custom apps in the Shopify admin](https://help.shopify.com/en/manual/apps/app-types/custom-apps)
- [Admin GraphQL API - orders](https://shopify.dev/docs/api/admin-graphql/latest/queries/orders)