# 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.](https://docs.coupler.io/sources/category/ecommerce/shopify/common-issues/shopify-invalid-credentials-or-missing-permissions)

</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>

## 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](https://docs.coupler.io/sources/category/ecommerce/shopify/best-practices) 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>