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

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Shopify data source in Adriel.

## Introduction

Shopify is a direct-to-consumer commerce platform for online stores. The connector reads a shop's orders, refunds, products, and product variants via Shopify's Admin GraphQL Bulk Operations API, exposing order-level revenue, sales analytics, and product catalog data for dashboards.

As an e-commerce connector, order, revenue, and product breakdowns are standardized so widgets can aggregate alongside ad-platform sources without additional configuration. Several headline order metrics — Gross Sales, Net Sales, Total Sales, Tax Amount, Shipping Fee, Net Returns, Net Discount — are reconstructed to match the values shown in Shopify's own analytics, so cross-source dashboards reconcile cleanly against the Shopify admin UI.

To connect this data source, see [How to connect Shopify to Adriel](/data-sources/o-z/shopify/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the store, products, and product variants. The catalog is fully refreshed **once per day** via a dedicated Shopify Bulk Operation. Each product variant becomes a separate record; the snapshot includes product title, variant title, SKU, price, compare-at (retail) price, status, image URL, inventory unit cost (when set), and created / updated timestamps.

### Reports data

Reports include order-level financial and status data.

**Refresh schedule.** Orders sync **hourly at :39 past the hour (UTC)** (cron `0 39 * * * *`). At every refresh, orders created or modified in the last **1 day** are pulled. Order chunks are materialized one day at a time.

**Historical window.** Up to **90 days** of historical orders can be back-filled (`maxFromDate` = 90 days ago). Data older than 90 days cannot be retrieved from Shopify through this connector.

**Payment-date attribution.** Order attribution uses the payment date (`processedAt`), not the creation date (`createdAt`) — driven by `paymentDateMode: true`. Orders placed in one period and paid in another are reported against the payment period.

## Architecture levels

Store → Product → Variant, and Order → Line item.

Each product variant is a separate record. Each order line item is a separate row on the order.

## Date range limits

| Breakdown                    | Max range                                                 |
| ---------------------------- | --------------------------------------------------------- |
| Daily                        | 93 days                                                   |
| Weekly                       | 1 year                                                    |
| Monthly / Quarterly / Yearly | No explicit cap (bounded by the 90-day historical window) |

## Metrics

<Note>
  **How to read the columns**

  The **Data type** column uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

  The **API Key** column uses code style like `currentTotalPriceSet` for the literal Shopify Admin GraphQL field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single Shopify field — typically Adriel-side reconstruction of a Shopify analytics figure, aggregation across order rows, or a computed formula.
</Note>

### Orders

<Note>
  **Refund reporting timing.** Refund detail cannot be retrieved in the same bulk operation as orders. The connector first runs a lightweight bulk operation to identify orders with refunds in the date window, then fetches full refund detail via a direct GraphQL query batched by up to 250 order names. Refund figures on freshly-refunded orders may lag the initial order sync by one cycle.
</Note>

| Metric             | Description                                                                                                                         | Data type | API Key                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- |
| Order Count        | Distinct number of orders.                                                                                                          | Number    | *Aggregated from order rows* |
| Order Buyer Count  | Distinct number of buyers on orders.                                                                                                | Number    | *Aggregated from order rows* |
| Order Date         | Order creation timestamp. Converted from Shopify's UTC value to the store's local timezone before persisting.                       | Date      | `createdAt`                  |
| Order Payment Date | Order processed (payment) timestamp — used for attribution via `paymentDateMode: true`. Converted from UTC to store-local timezone. | Date      | `processedAt`                |
| Order Updated Date | Order last-updated timestamp. Converted from UTC to store-local timezone.                                                           | Date      | `updatedAt`                  |
| Order Currency     | Currency the order was placed in.                                                                                                   | Text      | `currencyCode`               |

### Revenue & sales

<Note>
  **Native Shopify metric reconstruction.** Gross Sales, Net Sales, Total Sales, Net Discount, Net Returns, Tax Amount, and Shipping Fee are reconstructed from Shopify's sales agreement data (`ShopifyAgreement` / `ShopifyAgreementSale`) so they match the values shown in Shopify's own admin analytics. Dashboards built on these metrics reconcile against the Shopify admin.
</Note>

<Note>
  **Multi-currency handling.** Shopify Markets and Shopify Payments support multi-currency natively; each order's original currency is captured via `currencyCode`. Adriel applies a currency conversion rate fetched at sync time to convert all monetary values to the asset's configured reporting currency (default USD).
</Note>

| Metric                | Description                                                                                                                                                                                                                                                                                      | Data type | API Key                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------- |
| Order Payment Amount  | Captured payment total on the order.                                                                                                                                                                                                                                                             | Currency  | `currentTotalPriceSet`                                        |
| Order Price Amount    | Order price plus discounts applied.                                                                                                                                                                                                                                                              | Currency  | *Computed:* `currentTotalPriceSet + currentTotalDiscountsSet` |
| Order Amount Due      | Order price plus shipping.                                                                                                                                                                                                                                                                       | Currency  | *Computed:* `currentTotalPriceSet + totalShippingPriceSet`    |
| Order Discount Amount | Discounts applied to the order.                                                                                                                                                                                                                                                                  | Currency  | `currentTotalDiscountsSet`                                    |
| Order Gross Sales     | Reconstructed to mirror Shopify's native Gross Sales metric (product price total minus taxes on non-shipping sales).                                                                                                                                                                             | Currency  | *Adriel-reconstructed from agreement sales*                   |
| Order Net Sales       | Reconstructed to mirror Shopify's native Net Sales metric (gross sales minus net discount plus net returns minus taxes).                                                                                                                                                                         | Currency  | *Adriel-reconstructed*                                        |
| Order Total Sales     | Reconstructed to mirror Shopify's native Total Sales metric (net sales plus shipping fee).                                                                                                                                                                                                       | Currency  | *Adriel-reconstructed*                                        |
| Order Net Discount    | Reconstructed to mirror Shopify's native Net Discount metric (total discounts before taxes on agreement sales).                                                                                                                                                                                  | Currency  | *Adriel-reconstructed*                                        |
| Order Net Returns     | Reconstructed to mirror Shopify's native Net Returns metric (negative PRODUCT sales plus ADJUSTMENT lines on REFUND agreements).                                                                                                                                                                 | Currency  | *Adriel-reconstructed*                                        |
| Order Tax Amount      | Reconstructed to mirror Shopify's native Tax metric. For stores that price tax-inclusive (`taxesIncluded: true`), the connector derives tax-exclusive values via an internal `taxConvertRate`; when an order carries a 100% discount, that rate is safely forced to `0` to avoid divide-by-zero. | Currency  | *Adriel-reconstructed*                                        |
| Order Shipping Fee    | Reconstructed to mirror Shopify's native Shipping metric (sum of SHIPPING agreement sales).                                                                                                                                                                                                      | Currency  | *Adriel-reconstructed*                                        |

### Products

| Metric                     | Description                                                                               | Data type | API Key                      |
| -------------------------- | ----------------------------------------------------------------------------------------- | --------- | ---------------------------- |
| Product Price              | Listed product price.                                                                     | Currency  | `price`                      |
| Product Retail Price       | Compare-at (retail) price shown as a strike-through in Shopify.                           | Currency  | `compareAtPrice`             |
| Product Image              | Primary product image URL.                                                                | URL       | `image.url`                  |
| Product Currency           | Currency code for the product price.                                                      | Text      | *Derived from shop settings* |
| Product Created Date       | Date the product was created in Shopify. Converted from UTC to store-local timezone.      | Date      | `createdAt`                  |
| Product Updated Date       | Date the product was last updated in Shopify. Converted from UTC to store-local timezone. | Date      | `updatedAt`                  |
| Product Order Price Amount | Revenue tied to a specific product within an order.                                       | Currency  | *Computed from line items*   |
| Product Order Quantity     | Units of a specific product within an order.                                              | Number    | *Computed from line items*   |

<Note>
  **Product Order metrics link products with their orders.** When a Product Order metric is used with a product filter, only the portion of the order tied to that product is included, and only orders containing at least one matching product are shown. If a product has been deleted in Shopify, the related orders may not appear — use Product Order metrics only when necessary.
</Note>

### Customers

| Metric                   | Description                                                                                         | Data type | API Key                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------- |
| New customer count       | Orders where the buyer's Shopify customer order index is `1`. Excludes transaction and cancel rows. | Number    | *Adriel-computed:* `SUM(order_customer_type = 'New')`       |
| Returning customer count | Orders where the buyer has ordered more than once. Excludes transaction and cancel rows.            | Number    | *Adriel-computed:* `SUM(order_customer_type = 'Returning')` |

### Costs

<Note>
  **Cost metrics depend on inventory unit cost.** Order Products Cost Amount and Product Cost populate only when the merchant has set `inventoryItem.unitCost` on products inside Shopify, and the Shopify app has the `read_inventory` scope ("product costs" permission). Products without an inventory unit cost contribute no value to these metrics.
</Note>

| Metric                     | Description                                       | Data type | API Key                                         |
| -------------------------- | ------------------------------------------------- | --------- | ----------------------------------------------- |
| Product Cost               | Inventory unit cost set on the product variant.   | Currency  | `inventoryItem.unitCost`                        |
| Order Products Cost Amount | Cost of goods sold for the products on the order. | Currency  | *Computed:* `inventoryItem.unitCost * quantity` |

## Breakdowns

<Note>
  **Shopify-provided vs Adriel-provided**

  Breakdowns whose API Key is a Shopify GraphQL field (e.g. `paymentGatewayNames`, `sourceName`, `customerJourneySummary.firstVisit.utmParameters.source`) come directly from Shopify's Admin GraphQL response. Breakdowns marked *Adriel-derived* are computed on top of the raw order or product data — grouping by extracted attributes, resolving customer type from the order index, or splitting reports by time.
</Note>

### Store & product hierarchy

| Breakdown             | Description                                                                                         | API Key                     |
| --------------------- | --------------------------------------------------------------------------------------------------- | --------------------------- |
| Product ID            | Combined product and variant identifier (`{productId}/{variantId}`, Shopify GID prefixes stripped). | `product.id` / `variant.id` |
| Product Name          | Product title.                                                                                      | `title`                     |
| Product Detailed Name | Product title joined with variant title (`title - variant.title`).                                  | *Adriel-derived*            |
| Product SKU           | Stock keeping unit.                                                                                 | `sku`                       |
| Product Status        | Shopify product status (active, archived, draft).                                                   | `status`                    |

### Order details

| Breakdown            | Description                                           | API Key                        |
| -------------------- | ----------------------------------------------------- | ------------------------------ |
| Order ID             | Shopify order name (e.g. `#1001`).                    | `name`                         |
| Order Status         | Order status from Shopify.                            | *Derived from order lifecycle* |
| Order Payment Method | Payment gateway(s) used on the order.                 | `paymentGatewayNames`          |
| Order Source         | Origin attributed to the order (POS, web, app, etc.). | `sourceName`                   |

### Customer & geography

| Breakdown           | Description                                                                                                                                                                | API Key                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Order Country       | Country of the order shipping address.                                                                                                                                     | *Adriel-derived from order address*                               |
| Order City          | City of the order shipping address.                                                                                                                                        | *Adriel-derived from order address*                               |
| Order Customer Type | `New` for the buyer's first order, `Returning` for subsequent orders. `None` for transaction rows without customer data, or when the buyer checked out without an account. | *Adriel-derived from* `customerJourneySummary.customerOrderIndex` |

### Marketing attribution (Customer journey UTM)

<Note>
  **UTM values come from Shopify's customer journey summary,** not from parsing Adriel-side URLs. Shopify records the first and last visit that led to the order and exposes the UTM parameters and source on each. The connector maps them to breakdowns so orders can be grouped by acquisition channel.
</Note>

| Breakdown                | Description                                                          | API Key                                                    |
| ------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| First Visit Source       | Referrer source of the buyer's first recorded visit.                 | `customerJourneySummary.firstVisit.source`                 |
| First Visit UTM Source   | `utm_source` of the first visit.                                     | `customerJourneySummary.firstVisit.utmParameters.source`   |
| First Visit UTM Medium   | `utm_medium` of the first visit.                                     | `customerJourneySummary.firstVisit.utmParameters.medium`   |
| First Visit UTM Campaign | `utm_campaign` of the first visit.                                   | `customerJourneySummary.firstVisit.utmParameters.campaign` |
| First Visit UTM Content  | `utm_content` of the first visit.                                    | `customerJourneySummary.firstVisit.utmParameters.content`  |
| First Visit UTM Term     | `utm_term` of the first visit.                                       | `customerJourneySummary.firstVisit.utmParameters.term`     |
| Last Visit Source        | Referrer source of the buyer's last recorded visit before the order. | `customerJourneySummary.lastVisit.source`                  |
| Last Visit UTM Source    | `utm_source` of the last visit.                                      | `customerJourneySummary.lastVisit.utmParameters.source`    |
| Last Visit UTM Medium    | `utm_medium` of the last visit.                                      | `customerJourneySummary.lastVisit.utmParameters.medium`    |
| Last Visit UTM Campaign  | `utm_campaign` of the last visit.                                    | `customerJourneySummary.lastVisit.utmParameters.campaign`  |
| Last Visit UTM Content   | `utm_content` of the last visit.                                     | `customerJourneySummary.lastVisit.utmParameters.content`   |
| Last Visit UTM Term      | `utm_term` of the last visit.                                        | `customerJourneySummary.lastVisit.utmParameters.term`      |

### Time & date grouping

<Note>
  Shopify's Bulk Operations return order-level records with timestamps. Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying order data.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split reports by day. Max range 93 days.                     |
| Weekly (Start: Mon) | Split reports by week starting Monday. Max range 1 year.     |
| Weekly (Start: Sun) | Split reports by week starting Sunday. Max range 1 year.     |
| Monthly             | Split reports by calendar month.                             |
| Quarterly           | Split reports by calendar quarter.                           |
| Yearly              | Split reports by calendar year.                              |

### Overview & status

| Breakdown       | Description                                   |
| --------------- | --------------------------------------------- |
| No Grouping     | Do not break down; return one aggregated row. |
| Datasource Name | Group by Adriel datasource name.              |

## Limitations

Based on the current connector, Shopify has:

* **A 90-day historical limit** (`maxFromDate` = 90 days ago). Orders older than 90 days from today cannot be back-filled.
* **Hourly refresh cadence.** The orders cron runs at `0 39 * * * *` (UTC) on a rolling 1-day window; intra-hour changes surface on the next tick.
* **Custom private-app connection type is being deprecated.** New connections must use the custom OAuth app flow.
* **Cost metrics require the `read_inventory` scope.** Without it, `inventoryItem.unitCost` is not returned and Product Cost / Order Products Cost Amount are null.
* **No deleted-data retention.** Products or orders deleted in Shopify no longer appear. Orders that reference a deleted product variant fall back to a placeholder variant ID and may not surface under Product Order metrics.
* **Test orders excluded.** Orders flagged `test: true` in Shopify are silently dropped and produce no rows.
* **One bulk operation of each type at a time per store.** On API versions before `2026-01`, Shopify runs only one bulk operation of each type at a time per shop, so concurrent Adriel refreshes are serialized ([Shopify Bulk Operations](https://shopify.dev/docs/api/usage/bulk-operations/queries)).
* **`refundLineItems` not available via bulk.** Refund detail is fetched with a separate non-bulk GraphQL query, chunked at 250 orders per request.
* **Gross/Net/Total Sales on plain order rows are 0** — the reconstructed values live on the paired agreement (transaction) rows. Widgets should not filter out transaction rows when using these metrics.

## API references (Shopify)

* [Shopify Admin API overview](https://shopify.dev/docs/api/admin)
* [Admin GraphQL Bulk Operations](https://shopify.dev/docs/api/usage/bulk-operations/queries)
* [Order object (GraphQL)](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order)
* [Product object (GraphQL)](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product)
* [Refund object (GraphQL)](https://shopify.dev/docs/api/admin-graphql/latest/objects/Refund)
* [CustomerJourneySummary object (GraphQL)](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerJourneySummary)

## See also

* [How to connect Shopify](/data-sources/o-z/shopify/how-to-connect) (paired how-to)
* [WooCommerce data reference](/data-sources/o-z/woocommerce/data-reference) — alternative direct-to-consumer commerce platform
* [Naver Smart Store data reference](/data-sources/g-n/naver-smart-store/data-reference) — Korean e-commerce commerce platform
* [Cafe24 data reference](/data-sources/a-f/cafe24/data-reference) — Korean commerce platform
* [Amazon Vendor Central data reference](/data-sources/a-f/amazon-vendor-central/data-reference) — marketplace commerce
* Lazada data reference — Southeast Asia marketplace commerce