The Square Data Model

This article describes the entities that make up Square's internal representation of a merchant's business.

The business entity

When a merchant signs up for Square, a new business entity is created for them in Square's system.

Business structure

The business entity contains all of the merchant's:

  • Locations. Every business has at least one location entity. If a business has multiple locations, each one typically corresponds to a different brick-and-mortar store. Each location has its own distinct transactions and item library.
  • Employees. Every business has at least one employee entity. A business' first employee is the business owner, which has all possible permissions related to the business.
  • Roles. Employees besides the business owner can have a role assigned to them that indicates which permissions they have (such as the ability to process refunds with Square Point of Sale).
  • Timecards. Timecards track the duration of employee shifts. Employees can clock in and out from the Square Point of Sale app, or via the Connect API.

Location entities

Each of a business' locations has its own distinct transactions and item library. Transactions and items never belong directly to a business; they always belong to one of the business' locations.

Location structure

A location's transactions include:

  • Payments processed with Square
  • Refunds processed with Square
  • Orders received from the location's online store
  • Deposits made from Square to the location's linked bank account (these are also called settlements)

A location's item library includes:

  • Items available for sale at the location and their current inventory count
  • Discounts and taxes that can be applied to sales at the location

Working with entities

The Connect API provides endpoints that let you interact with all entities described above. See the FAQ for a summary of which entities are currently supported by version 2 of the API, and which entities still require v1 endpoints.

Was this page helpful?

Ask for help on Stack Overflow or join our Slack channel