# Common Issues

## Connection issues

<details>

<summary>OAuth authorization fails or redirects to an error page</summary>

Make sure you're logged in to the correct Square account before starting the OAuth flow. If you manage multiple Square accounts, Square may default to the wrong one. Log out of Square first, then reconnect through Coupler.io to ensure you authorize the right account.

</details>

<details>

<summary>The connection was authorized but no data appears</summary>

This usually means the connected Square account has no data for the selected entity or the start date is set too far in the future. Check that your start date is set correctly using the date picker, and verify that the entity (e.g., Orders) actually contains records in your Square dashboard.

</details>

## Missing data

<details>

<summary>Orders or payments from certain locations are missing</summary>

Square data is returned for all locations under the authorized account by default. If specific location data is missing, check that the location is active in your Square dashboard and that the account you authorized has access to it. Deactivated locations may not return data.

</details>

<details>

<summary>Deleted items, discounts, or taxes are not showing up</summary>

By default, deleted catalog objects are excluded. Go to the **Advanced settings** step of your data flow and enable **Include deleted objects** to include soft-deleted catalog entries in your export.

</details>

<details>

<summary>Inventory quantities look outdated or incorrect</summary>

Inventory in Square is calculated at the time of the API request. The `calculated_at` field shows when the quantity was last computed. If levels look stale, run the data flow again to fetch the latest calculated values from Square.

</details>

## Permission errors

<details>

<summary>Error: insufficient permissions for Bank accounts or Cash drawers</summary>

Accessing bank account and cash drawer data requires **Owner-level** access in Square. If you authorized with an account that has a more limited role (e.g., a staff account), you'll need to reconnect using the Square account owner's credentials.

</details>

<details>

<summary>Team member or shift data returns empty results</summary>

Reading labor data (Shifts, Team members, Team member wages) requires the **Employees Read** permission in Square. Confirm the authorized account has this permission, or reconnect with an owner account that has full access.

</details>

## Data discrepancies

<details>

<summary>Payment totals don't match what I see in the Square dashboard</summary>

Square returns monetary values in the smallest currency unit (cents for USD). A value of `1500` means $15.00. If your destination is showing raw values without dividing by 100, add a calculated column or transformation to convert the amounts.

</details>

<details>

<summary>Order count in Coupler.io differs from the Square reports tab</summary>

The Square dashboard reports tab may apply its own filters (e.g., excluding canceled orders or a specific date range). Check that your start date in Coupler.io matches the date range used in Square's report, and verify whether you need to filter by order state (COMPLETED vs. all states).

</details>

## Rate limits

<details>

<summary>Data flow fails with a rate limit or throttling error</summary>

Square enforces API rate limits per endpoint. If you're pulling multiple large entities in the same data flow run, you may occasionally hit these limits. Try splitting high-volume entities (like Orders with a long date range) into separate data flows, or reduce the date range covered by each run.

</details>
