Square

Square is a point-of-sale and commerce platform used by retailers, restaurants, and service businesses to accept payments, manage inventory, and run operations. Connecting Square to Coupler.io lets you pull your sales, customer, staff, and catalog data into any destination for reporting and analysis.

Why connect Square to Coupler.io?

• Centralize Square data — orders, payments, refunds, inventory — in Google Sheets, BigQuery, or Looker Studio without manual exports

• Combine multiple Square entities in a single data flow using Join or Append transformations

• Send Square data to AI destinations like ChatGPT, Claude, or Gemini for automated insights and summaries

• Keep dashboards up to date with scheduled refreshes on any cadence

Prerequisites

• An active Square account (any plan)

• Owner or admin access to the Square account you want to connect — this ensures Coupler.io can read all required data

Quick start

If you want a combined view of sales performance, start with the Orders and Payments entities, then use the Join transformation to link them by order ID.

How to connect

1

Create a new data flow in Coupler.io. Log in to Coupler.io, go to the Data Flows section, and click Add data flow. Search for and select Square as your source.

2

Authorize your Square account. Click Connect and sign in to your Square account when prompted. Coupler.io uses OAuth, so no API keys are needed — just approve the permissions request.

3

Select an entity. Choose which data you want to pull — for example, Orders, Payments, Customers, or Inventory. Each entity maps to a specific set of Square data.

4

Choose a destination. Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT, Claude, Gemini, Cursor, Perplexity, or OpenClaw.

5

Run your data flow. Click Run to execute the data flow manually. Once it completes successfully, your Square data will appear in the destination you chose.

Square data overview

Square gives you access to a broad set of business data spanning sales transactions, catalog management, staff operations, and customer relationships. Here's a breakdown of what each entity contains and how you can use it.

Entities overview

Entity	Primary use
Orders	Revenue reporting, order status tracking
Payments	Payment method analysis, transaction reconciliation
Refunds	Refund rate tracking, loss analysis
Customers	Customer segmentation, retention analysis
Items	Product catalog management, pricing review
Categories	Category-level sales grouping
Discounts	Discount usage and impact analysis
Taxes	Tax calculation auditing
Modifier lists	Add-on performance tracking
Inventories	Stock level monitoring by location
Locations	Multi-location performance comparison
Team members	Staff roster management
Team member wages	Payroll cost analysis
Shifts	Labor hours and scheduling analysis
Bank accounts	Financial account audit
Cash drawers	Cash handling reconciliation
Loyalties	Loyalty program engagement

Available fields by entity

Orders

Field	Description
id	Unique order ID
location_id	Location where the order was placed
state	Order status (OPEN, COMPLETED, CANCELED)
total_money	Total order amount including taxes and discounts
total_tax_money	Total tax applied
total_discount_money	Total discounts applied
created_at	Order creation timestamp
updated_at	Last update timestamp
line_items	Individual items within the order
customer_id	Linked customer ID

Payments

Field	Description
id	Unique payment ID
order_id	Associated order ID
amount_money	Payment amount
status	Payment status (COMPLETED, FAILED, CANCELED)
source_type	Payment method (CARD, CASH, WALLET, etc.)
location_id	Location where payment was taken
created_at	Payment timestamp
card_details	Card brand and last 4 digits (for card payments)

Refunds

Field	Description
id	Unique refund ID
payment_id	Original payment ID
amount_money	Refunded amount
status	Refund status
reason	Reason provided for the refund
created_at	Refund timestamp

Customers

Field	Description
id	Unique customer ID
given_name	First name
family_name	Last name
email_address	Email address
phone_number	Phone number
created_at	Profile creation date
updated_at	Last update date
note	Internal notes on the customer

Items

Field	Description
id	Catalog item ID
name	Item name
description	Item description
category_id	Linked category
variations	Variations with price and SKU
is_deleted	Whether the item has been deleted

Inventories

Field	Description
catalog_object_id	Item variation ID
location_id	Location of the stock
quantity	Current stock quantity
state	Inventory state (IN_STOCK, SOLD, etc.)
calculated_at	Timestamp of the inventory calculation

Shifts

Field	Description
id	Shift ID
employee_id	Team member ID
location_id	Location of the shift
start_at	Shift start time
end_at	Shift end time
status	Shift status (OPEN, CLOSED)
wage	Hourly wage applied to the shift

Loyalties

Field	Description
id	Loyalty account ID
customer_id	Linked customer ID
program_id	Loyalty program ID
balance	Current points balance
lifetime_points	Total points ever earned
created_at	Account creation date

Common metric combinations

• Orders + Payments (Join on order_id): Reconcile transaction values against order totals and payment methods

• Orders + Customers (Join on customer_id): Analyze revenue per customer segment

• Shifts + Team member wages (Join on employee_id): Calculate total labor cost per shift or location

• Inventories + Items (Join on catalog_object_id): See stock levels alongside item names and prices

• Payments + Refunds (Append or Join): Build a complete picture of net revenue after refunds

Use cases by role

Store owners

• Pull Orders and Payments into Google Sheets for a daily revenue summary

• Monitor Inventory levels across locations and set up alerts when stock drops

• Use the Locations entity to compare sales performance across stores

• Send Orders data to ChatGPT or Claude to automatically generate weekly sales summaries

Finance teams

• Join Payments and Refunds to calculate net revenue per period

• Export Bank accounts and Cash drawers data for reconciliation

• Pull Taxes data to verify tax collection amounts against filings

• Load payment data into BigQuery for long-term financial trend analysis

Operations & HR

• Combine Shifts and Team member wages to build a labor cost report by location or team member

• Export Team members data to keep staff rosters up to date in external HR tools

• Use the Aggregate transformation on Shifts data to calculate total hours worked per week

Marketing teams

• Analyze Customers and Loyalties data to segment high-value customers by points balance or visit frequency

• Join Discounts with Orders to measure the revenue impact of promotions

• Send customer loyalty data to Gemini or Perplexity for churn prediction prompts

Platform-specific notes

• Square amounts are returned in the smallest currency unit (e.g., cents for USD). Divide by 100 to get dollar values in your destination.

• The start date parameter limits which records are returned for time-based entities like Orders, Payments, Refunds, and Shifts. Catalog entities (Items, Categories, Taxes) return all records regardless of start date.

• Enabling Include deleted objects will return soft-deleted catalog items, categories, discounts, and taxes — useful if you need a complete historical catalog audit.

• Square data is scoped to the connected account. If you have multiple Square accounts, you'll need a separate connection for each.

• location_id is a key join field across almost every entity — use it to segment any report by physical store or venue.

Square common issues

Connection issues

OAuth authorization fails or redirects to an error page

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.

The connection was authorized but no data appears

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.

Missing data

Orders or payments from certain locations are missing

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.

Deleted items, discounts, or taxes are not showing up

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.

Inventory quantities look outdated or incorrect

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.

Permission errors

Error: insufficient permissions for Bank accounts or Cash drawers

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.

Team member or shift data returns empty results

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.

Data discrepancies

Payment totals don't match what I see in the Square dashboard

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.

Order count in Coupler.io differs from the Square reports tab

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).

Rate limits

Data flow fails with a rate limit or throttling error

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.

Square FAQ

Can I connect multiple Square accounts to Coupler.io?

Yes. Each Square account requires its own connection in Coupler.io. When setting up a data flow, you can add a new Square connection for a different account. If you want to combine data from multiple accounts in one report, pull each account into a separate data flow and use the Append transformation to merge the results.

What's the difference between Orders and Payments in Square?

Orders represent what was purchased — they include line items, applied discounts, taxes, and the order total. Payments represent the actual money collected — they include the payment method, amount charged, and transaction status. One order can have multiple payments (e.g., split tender). For revenue reporting, use both entities joined on order_id.

Why are my revenue numbers 100 times larger than expected?

Square returns all monetary values in the smallest currency unit (cents for USD). A value of 2500 means $25.00. You need to divide amount fields by 100 in your destination or transformation step. This applies to total_money, amount_money, and all other money fields across Orders, Payments, and Refunds.

Does the start date apply to all entities?

No. The start date filters time-based entities — Orders, Payments, Refunds, Shifts, and similar transactional data. Catalog entities like Items, Categories, Taxes, Discounts, and Modifier lists return all records regardless of the start date you set.

Can I get data for a specific location only?

Coupler.io pulls data for all locations under the authorized Square account. You can filter by location_id in your destination (e.g., using a filter in Google Sheets or a WHERE clause in BigQuery) after the data lands. Every entity includes a location_id field you can use for this.

How do I track loyalty points for my customers?

Use the Loyalties entity to get loyalty account balances and lifetime points. Join it with the Customers entity on customer_id to attach names and contact details to each loyalty account. This gives you a complete view of your most engaged customers.

Can I use Square data with AI tools like ChatGPT or Claude?

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can send Square Orders, Customers, or Payments data directly to these tools to generate summaries, identify trends, or answer natural language questions about your business.

How do I calculate total labor cost from Square data?

Join the Shifts entity with Team member wages on employee_id. Multiply the shift duration (end_at minus start_at, in hours) by the wage rate to calculate labor cost per shift. Use the Aggregate transformation to sum costs by location or date range.

For field-level details on each entity, see the Data Overview article. If you're running into connection or data problems, check Common Issues. For setup recommendations specific to Square, visit Best Practices.