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