> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ecommerce/shopify.md).

# Shopify

Connect Shopify orders, products, customers, and inventory to Google Sheets, BigQuery, or databases via Coupler.io's GraphQL API.

Shopify is a leading e-commerce platform used by millions of merchants worldwide to sell products online, in-store, and across social channels. By connecting Shopify to Coupler.io, you can automatically export order, product, customer, and inventory data to spreadsheets, BI tools, or databases — no manual CSV downloads or copy-paste needed.

Coupler.io's Shopify source is built on **Shopify's GraphQL API**, providing faster exports with column-level control over what data you pull.

{% hint style="info" %}
Coupler.io previously offered legacy Shopify sources based on the REST API (labeled "Shopify (legacy)" in the UI). Shopify has deprecated the REST API for third-party apps. If you're still using a legacy source, plan to migrate to the new GraphQL-based source. See the [migration guide](https://help.coupler.io/article/589-meet-the-new-shopify-graphql-source) for details.
{% endhint %}

## Why connect Shopify to Coupler.io?

* **Automate sales reporting** — Schedule regular data refreshes so your spreadsheets and dashboards always reflect the latest orders, revenue, and inventory levels.
* **Build custom dashboards** — Export order and product data to Looker Studio, Power BI, or Google Sheets for analysis beyond what Shopify's native analytics offer.
* **Combine with other sources** — Merge Shopify data with advertising (Facebook Ads, Google Ads), accounting (Xero, QuickBooks), or CRM data for a full picture of business performance.
* **Flexible destinations** — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations.

## Prerequisites

Before connecting, make sure you have:

* A **Shopify** store with an active plan
* Store owner or staff account with the necessary permissions (read access to orders, products, customers, and inventory)
* A Coupler.io account

{% hint style="warning" %}
If you connect via the Shopify App Store, the Coupler.io app must be installed on your store. If you later uninstall the app from Shopify, your data flows will stop working and you'll need to reconnect.
{% endhint %}

## Quick start

{% hint style="success" %}
Start with **Orders with line items** and set **Created after** to a date 30 days ago using the date picker. Select the default columns to get a product-level sales report for the last 30 days. Run it once to verify the connection, then set up a daily auto-refresh.
{% endhint %}

## How to connect

Shopify uses **OAuth authentication** — you sign in with your Shopify account directly.

{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **Shopify** as the source.\
Click **Connect** and enter your full Shopify shop name (e.g., your-store.myshopify.com).
{% endstep %}

{% step %}
Sign in and authorize Coupler.io to access your store data.
{% endstep %}

{% step %}
Select a **data entity** from the grouped dropdown (e.g., Orders, Products, Customers, Inventory).
{% endstep %}

{% step %}
**Choose columns** (available for order-related entities) — select only the fields you need to speed up processing and reduce noise.
{% endstep %}

{% step %}
Optionally set **date filters** (Created after/before, Changed after/before), **status filters** (order status, financial status, fulfillment status, product status), or **Filter after ID**.
{% endstep %}

{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}

## Shopify data overview

Coupler.io's Shopify source pulls structured e-commerce data directly from your Shopify store via the GraphQL API. You select one data entity per data flow and choose which columns to include (for order-related entities).

## What data is available?

Entities are organized into two groups.

#### Basics

| Entity        | Description                                                             | Typical use case                             |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
| **Orders**    | Order-level data — totals, status, customer info, payment gateway, tags | Daily sales reports, revenue dashboards      |
| **Products**  | Product catalog — title, vendor, status, published/updated dates        | Product management, catalog sync             |
| **Inventory** | SKU-level stock quantities across locations                             | Inventory tracking, reorder alerts           |
| **Customers** | Customer records — name, email, total spent, last order info            | Customer lists, marketing segments, CRM sync |

#### Order & product breakdowns

| Entity                                 | Description                                                                  | Typical use case                            |
| -------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------- |
| **Products with variants**             | Products split by variant — one row per variant with price, SKU, inventory   | Variant-level pricing, SKU analysis         |
| **Orders with line items**             | Orders split by line item — one row per product in each order                | Product sales analysis, SKU-level reporting |
| **Order fulfillments with line items** | Orders with fulfillment details — tracking info, delivery dates, line items  | Shipping and logistics tracking             |
| **Orders with shipping lines**         | Orders with shipping method details — carrier, cost, delivery category       | Shipping cost analysis                      |
| **Orders refunds transactions**        | Orders with refund and transaction details — refund amounts, gateway, status | Refund analysis, financial reconciliation   |

## Column selection

For all order-related entities (Orders, Orders with line items, Order fulfillments, Orders with shipping lines, Orders refunds transactions), you can choose exactly which columns to include. Columns are organized into groups:

| Column group                      | Available in                | Examples                                                                           |
| --------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| **Order**                         | All order entities          | Order name, Created at, Financial status, Fulfillment status, Tags, Discount codes |
| **Customer**                      | All order entities          | Customer name, Amount spent                                                        |
| **Billing address**               | All order entities          | Country                                                                            |
| **Customer journey**              | All order entities          | Customer order index, Days to conversion                                           |
| **Order totals in shop currency** | All order entities          | Current order total, Net payment, Discounts, Tax, Shipping, Duties                 |
| **Line items**                    | Orders with line items      | SKU, Quantity, Line item name                                                      |
| **Line items totals**             | Orders with line items      | Discounted total, Original total, Unit price                                       |
| **Fulfillment**                   | Order fulfillments          | Fulfillment name, Status, Created/Delivered/In-transit dates, Tracking info        |
| **Fulfillment line item**         | Order fulfillments          | Line item name, SKU, Quantity, Unfulfilled quantity                                |
| **Shipping line**                 | Orders with shipping lines  | Code, Title, Source, Delivery category                                             |
| **Shipping line totals**          | Orders with shipping lines  | Original price, Discounted price                                                   |
| **Refund**                        | Orders refunds transactions | Refund created at, Note, Total refund amount                                       |
| **Refund transaction**            | Orders refunds transactions | Account number, Gateway, Status, Amount                                            |

{% hint style="info" %}
The **Store name**, **Entity ID** (e.g., Order ID), and **Updated At** columns are always included regardless of your column selection.
{% endhint %}

## Filtering parameters

| Parameter                  | Purpose                                                   | Available for                                                                           |
| -------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Created after / before** | Filter by record creation date                            | All entities except Inventory                                                           |
| **Changed after / before** | Filter by last update date                                | All entities                                                                            |
| **Filter after ID**        | Export records with ID greater than a value               | All entities except Inventory                                                           |
| **Status**                 | Filter orders by status (Any, Open, Closed, Cancelled)    | Order entities                                                                          |
| **Financial status**       | Filter by payment status (Paid, Pending, Refunded, etc.)  | Orders, Orders with line items, Orders with shipping lines, Order fulfillments          |
| **Fulfillment status**     | Filter by fulfillment (Shipped, Unshipped, Partial, etc.) | Orders, Orders with line items, Orders with shipping lines, Orders refunds transactions |
| **Product status**         | Filter by product status (Active, Archived, Draft)        | Products, Products with variants                                                        |

## Common data combinations

| Goal                       | Entity                             | Configuration                                          |
| -------------------------- | ---------------------------------- | ------------------------------------------------------ |
| Daily sales dashboard      | Orders                             | Created after = last 30 days, Financial status = Paid  |
| Product-level sales report | Orders with line items             | Select SKU, Quantity, and Line item totals columns     |
| Refund analysis            | Orders refunds transactions        | Financial status = Refunded or Partially refunded      |
| Inventory snapshot         | Inventory                          | Changed after = yesterday for recent changes           |
| Shipping performance       | Order fulfillments with line items | Select Fulfillment status, Delivered at, In transit at |
| Customer lifetime value    | Customers                          | Default columns include Total spent and Last order     |

## Use cases by role

{% tabs %}
{% tab title="E-commerce / Sales" %}
Track daily revenue, average order value, and top-selling products. Use Orders with line items to build SKU-level sales reports. Combine with advertising data (Facebook Ads, Google Ads) to calculate true ROAS by matching order revenue to ad spend.
{% endtab %}

{% tab title="Operations / Logistics" %}
Monitor fulfillment status and shipping timelines using Order fulfillments with line items. Track inventory levels across locations with the Inventory entity. Set up daily refreshes to catch stock-outs early.
{% endtab %}

{% tab title="Finance" %}
Reconcile order totals, refunds, and net payments using Orders refunds transactions. Export to BigQuery or Google Sheets for month-end close. Use date filters to scope each run to the relevant period.
{% endtab %}

{% tab title="Marketing" %}
Build customer segments using the Customers entity — filter by total spent, order count, or recency. Use the Customer journey columns (Days to conversion, Customer order index) to analyze first-time vs. repeat buyer behavior.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **GraphQL vs. REST** — The current Shopify source uses Shopify's GraphQL API. Legacy sources (REST-based) are deprecated and labeled "Shopify (legacy)" in the UI. Some column names differ between versions — see the [migration article](https://help.coupler.io/article/589-meet-the-new-shopify-graphql-source) if you're switching.
* **Column selection** — Only available for order-related entities. Products, Inventory, and Customers always return all available columns.
* **Customer journey data** — New in v4. Includes Customer order index (is this their 1st, 2nd, 5th order?) and Days to conversion. Available in all order entities.
* **Shopify reports and analytics are not available** — Coupler.io pulls raw entity data from Shopify, not Shopify's built-in reports or analytics dashboards. Metrics like conversion rate, sessions, and traffic sources are not accessible via the Shopify API.
* **Metafields** — Standard product and variant fields are included. Custom metafields (e.g., wholesale price, custom attributes) are not currently available as separate columns in the export.
* **Date filter timezone** — Date filters use your browser's timezone, not Shopify's store timezone. If they differ, orders near the day boundary may appear in unexpected date ranges.
* **Test orders** — By default, test orders created by Shopify's Bogus Gateway are included in exports. Filter them out using the "Is Test Order?" column in your destination or transformations.

## Shopify common issues

### Connection Issues

<details>

<summary>Invalid credentials or missing permissions error</summary>

It typically means the Shopify connection has become invalid — either because permissions were changed in Shopify, the Coupler.io app was reinstalled, or the store's access scopes were updated.

**Fix:**

1. Go to **Settings → Connections** in Coupler.io.
2. Find the Shopify connection used in the failing data flow.
3. Click **Reconnect** and sign in again with your Shopify credentials.

If Reconnect doesn't resolve it, remove the connection entirely and create a new one. [Read detailed guide.](/sources/category/ecommerce/shopify/shopify-invalid-credentials-or-missing-permissions.md)

</details>

<details>

<summary>Shopify app uninstalled — data flows stopped</summary>

If someone uninstalls the Coupler.io app from your Shopify store (via Shopify Admin → Apps), all data flows using that connection will fail immediately. This triggers a "Shopify app uninstalled" notification (25+ tickets).

**Fix:**

1. Go to your Shopify Admin → Apps → **Coupler.io** and reinstall the app.
2. In Coupler.io, go to **Settings → Connections** and reconnect your Shopify account.
3. Re-run the affected data flows.

</details>

<details>

<summary>"Store is unavailable" error when connecting</summary>

This error appears when the shop name entered during connection doesn't match an active Shopify store. Common causes: typos in the shop name, the store being paused or closed, or entering a custom domain instead of the `.myshopify.com` address.

**Fix:**

1. Use your full **myshopify.com** shop name (e.g., `your-store.myshopify.com`), not your custom domain.
2. Verify the store is active and not in a paused or frozen state.
3. If the store was recently migrated to a new Shopify plan, try again after a few minutes.

</details>

<details>

<summary>Legacy source connection no longer working</summary>

If your data flow uses a legacy Shopify source (REST API-based, labeled "Shopify (legacy)"), it may stop working as Shopify phases out REST API access. Legacy sources use API keys or tokens that may have expired or lost permissions.

**Fix:**

1. Create a new data flow using the current **Shopify** source (GraphQL-based).
2. Migrate your destination and transformation settings.
3. Note that some column names differ between legacy and GraphQL versions — use Coupler.io's [Columns management](https://help.coupler.io/article/370-columns-management) to adjust.

</details>

<details>

<summary>Getting "Please open your Shopify store and install app via Shopify App Store"</summary>

If you signed up to Coupler.io from the Shopify marketplace and paid for a subscription on the Shopify side using Shopify billing, we won't be able to start a connection from our side - Shopify needs to be the starting point.

In this case, you need to go to the Shopify -> App marketplace -> Coupler -> <https://apps.shopify.com/coupler-io?st_source=autocomplete&surface_detail=autocomplete_apps> -> Install\
\
Once you confirm the installation, a new connection will be created.

</details>

### Missing Data

<details>

<summary>Order counts don't match Shopify admin</summary>

Users frequently report that the number of orders exported by Coupler.io differs from the count shown in Shopify's admin or reports. Common causes: test orders being included/excluded, date filter timezone mismatches, or status filters not matching.

**Fix:**

1. Check if **test orders** (Bogus Gateway) are included in your export — Coupler.io includes them by default.
2. Verify your **date filters** — Coupler.io date filters use your browser's timezone, which may differ from your Shopify store timezone.
3. Confirm your **Status**, **Financial status**, and **Fulfillment status** filters match the orders you expect.
4. Set Status to **Any** to include all orders regardless of status.

</details>

<details>

<summary>Sales totals don't match Shopify reports</summary>

Shopify's built-in reports calculate sales using their own definitions (e.g., Gross sales, Net sales, Total sales), which may not match the raw order totals exported by Coupler.io.

**Fix:**

* Coupler.io exports **raw order data**, not Shopify's report calculations. The `Current order total amount` field represents the current total after adjustments.
* For net revenue, use the `Net payment amount` column.
* For refund-adjusted analysis, use the **Orders refunds transactions** entity which includes per-refund and per-transaction amounts.
* Shopify's "Total sales" metric includes adjustments that aren't represented in a single column — you may need to build a formula in your destination.

</details>

{% hint style="warning" %}
Sales data mismatches are the #1 data accuracy question for Shopify (7+ tickets). The root cause is almost always a difference between Shopify's report definitions and raw order totals. See the [Best Practices](/sources/category/ecommerce/shopify/best-practices.md) page for recommended column combinations.
{% endhint %}

<details>

<summary>Metafields not available in export</summary>

Custom metafields (e.g., wholesale price, product dimensions, custom attributes) are not available as separate columns in the Shopify export. Users requesting this data (7+ tickets) will see only standard product and variant fields.

**Fix:** There is currently no workaround within Coupler.io. This is a feature request that the team is aware of. You can contact support at <contact@coupler.io> to add your vote for metafield support.

</details>

<details>

<summary>Inventory data missing incoming quantities [not sure]</summary>

The Inventory entity exports current stock levels (available, committed, on-hand) but does not include incoming inventory quantities (purchase orders in transit).

**Fix:** Incoming inventory levels are not available through the Shopify API's inventory endpoints used by Coupler.io. As a workaround, you may need to export purchase order data separately if your store uses a third-party inventory management app.

</details>

### Timeout and Performance Errors

<details>

<summary>"Dataset is too large" or timeout error</summary>

Data flows that pull very large datasets (stores with tens of thousands of orders or products) may time out, especially when using Orders with line items or Order fulfillments which produce many rows (16+ tickets).

**Fix:**

1. Use **date filters** (Created after/before) to limit the time range — start with the last 30 or 90 days.
2. Use **Column selection** to include only the fields you need — fewer columns means faster processing.
3. Use **Changed after** (set to a date 7 days ago) for incremental daily syncs instead of full exports.
4. If the dataset is still too large, split into multiple data flows by date range or status.

</details>

{% hint style="danger" %}
Timeout errors are the #3 most common Shopify issue. Stores with 50,000+ orders should always use date filters to limit the export scope. Pulling the entire order history in a single data flow is not recommended.
{% endhint %}

<details>

<summary>Slow data flow execution</summary>

Even when data flows don't time out, they may take a long time to complete. This is typically caused by pulling all columns for large entities or using entities that produce many rows per order (like Orders with line items).

**Fix:**

* Use **Column selection** to remove unnecessary fields — this is the single biggest performance improvement.
* Set date filters to pull only recent data.
* Schedule data flows during off-peak hours for your Shopify store.

</details>

### API and Source Errors

<details>

<summary>Shopify API rate limit errors [not sure]</summary>

Shopify enforces GraphQL API cost limits. If you have multiple data flows or other apps making simultaneous API calls to the same store, you may hit rate limits.

**Fix:**

* Stagger your data flow refresh schedules so they don't all run at the same time.
* Reduce the number of concurrent Shopify data flows.
* Use date filters and column selection to reduce the amount of data pulled per request.

</details>

<details>

<summary>Data type mismatch when exporting to BigQuery</summary>

BigQuery requires consistent data types within a column. If Shopify returns mixed or null values in certain columns, the import may fail.

**Fix:** Use a transformation step in Coupler.io to standardize data types before export, or exclude problematic columns using column selection.

</details>

## Shopify FAQ

<details>

<summary>How do I check if I'm using the new GraphQL source or a legacy REST source?</summary>

Look at the entity selector in your data flow settings:

* **New GraphQL source:** Entities are organized into groups (Basics, Order & product breakdowns) with a grouped dropdown.
* **Legacy REST source:** Entities appear as a flat, ungrouped list, and the source is labeled "Shopify (legacy)" on the data flow view page.

If you're unsure, contact support at <contact@coupler.io> and they can verify which version your data flow uses.

</details>

<details>

<summary>Should I migrate from the legacy Shopify source to the new one?</summary>

Yes. Shopify has deprecated the REST API for third-party apps and recommends migrating to GraphQL. While there's no final shutdown date yet, the new source is faster, supports column selection, and includes customer journey data that the legacy version doesn't have.

Coupler.io will not migrate your data flows automatically to avoid data inconsistency (some field names differ). You can migrate at your own pace by creating new data flows with the GraphQL source and adjusting your destination/transformation settings.

</details>

<details>

<summary>Can I pull Shopify reports or analytics data?</summary>

No. Coupler.io pulls raw entity data (orders, products, customers, inventory) via the Shopify API. Shopify's built-in reports (Sales reports, Finance reports), analytics dashboards, conversion rates, and session/traffic data are not accessible through the API.

To build equivalent reports, export raw order data and calculate the metrics you need in your destination (Google Sheets, Looker Studio, BigQuery, etc.).

</details>

<details>

<summary>Can I export product metafields?</summary>

Not currently. The Shopify source exports standard product and variant fields but does not support custom metafields (e.g., wholesale price, product dimensions, custom attributes). This is one of the most requested features (7+ tickets).

If you need metafield data, contact support at <contact@coupler.io> to register your interest — the team tracks feature requests by demand.

</details>

<details>

<summary>Why don't my order totals match Shopify's reports?</summary>

Shopify's reports use specific definitions for metrics like "Total sales," "Gross sales," and "Net sales" that include various adjustments. Coupler.io exports raw order totals from the API, which may not match these calculated metrics exactly.

Key column mappings:

* **Current order total amount** — The current total after all adjustments (refunds, edits)
* **Net payment amount** — Total minus refunds and pending amounts
* **Current discounts amount** — Total discount applied

For the closest match to Shopify's "Total sales," you may need to build a formula that combines multiple columns. Also check for test orders and timezone differences.

</details>

<details>

<summary>How do I filter orders by date?</summary>

Use the **Created after** and **Created before** parameters in your data flow settings. Select dates using the date picker:

* Last 30 days: set Created after to a date 30 days ago
* This month: set Created after to the first of the month, Created before to today
* Specific range: Created after = `2025-01-01`, Created before = `2025-12-31`

Note that date filters use your **browser's timezone**, not your Shopify store's timezone. If they differ, you may see orders appear in unexpected date ranges.

</details>

<details>

<summary>What's the difference between Orders and Orders with line items?</summary>

**Orders** gives you one row per order with order-level data — totals, status, customer info, tags.

**Orders with line items** splits each order into multiple rows — one row per product (line item) in the order. This includes SKU, quantity, line item price, and discount details.

Use **Orders** for revenue dashboards and daily sales summaries. Use **Orders with line items** for product-level analysis (top-selling SKUs, product mix, per-item revenue).

</details>

<details>

<summary>How do I handle test orders in my export?</summary>

Shopify test orders (created using the Bogus Gateway) are included in Coupler.io exports by default. To exclude them:

1. Add the "Is Test Order?" column to your export if it's not already included.
2. In your destination, filter out rows where this field is `true`.
3. Alternatively, use a Coupler.io transformation step to exclude test orders before they reach your destination.

</details>

<details>

<summary>My data flow keeps timing out — what can I do?</summary>

Timeout errors happen when the dataset is too large. Try these fixes in order:

1. **Add date filters** — Set Created after to limit the time range (e.g., last 90 days).
2. **Use column selection** — Remove columns you don't need.
3. **Split by date range** — Create multiple data flows covering different time periods.
4. **Use Changed after** — For ongoing syncs, pull only recently modified records (e.g., set Changed after to a date 7 days ago).

If none of these help, contact support — they can investigate your specific data flow.

</details>

<details>

<summary>Can I export data from multiple Shopify stores?</summary>

Yes, but each data flow connects to one Shopify store. To pull data from multiple stores:

1. Create a separate Shopify connection for each store.
2. Create data flows for each store using the appropriate connection.
3. Export all flows to the same destination.
4. Add a formula column or label to identify which store the data comes from.
5. Use Coupler.io's Append transformation to combine the datasets.

</details>

<details>

<summary>What happened to the Collection ID filter? [not sure]</summary>

The Collection ID filter (which let you export only products from a specific collection) was available in the legacy REST-based Shopify source but is not available in the current GraphQL-based source. The GraphQL source exports all products and you can filter by product status (Active, Archived, Draft) only.

If you need to filter by collection, contact support — they may be able to help with a workaround.

</details>

<details>

<summary>How do I export inventory data for specific locations?</summary>

The Inventory entity exports stock levels across all locations by default. To filter by specific locations, you'll need the **Location ID** from your Shopify store:

1. In Shopify Admin, go to **Settings → Locations**.
2. Select a location and copy the numeric ID from the URL (e.g., for `site.myshopify.com/admin/settings/locations/51840778406`, the ID is `51840778406`).
3. Enter the Location ID in the data flow settings.

You can add multiple Location IDs, each on a separate line.

</details>

{% hint style="info" %}
For step-by-step connection setup, see the [Shopify data source guide](https://help.coupler.io/article/314-shopify-data-source). For information on migrating from the legacy source, see the [GraphQL migration guide](https://help.coupler.io/article/589-meet-the-new-shopify-graphql-source). For product field changes after GraphQL migration, see the [Products changes article](https://help.coupler.io/article/568-shopify-products-changes-after-migration-to-grahpql).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ecommerce/shopify.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.