> 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/square/data-overview.md).

# 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

{% tabs %}
{% tab title="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
  {% endtab %}

{% tab title="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
  {% endtab %}

{% tab title="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
  {% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/ecommerce/square/data-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.