Square Data Model

Orders and inventory tracking

To understand how itemization and money movement is linked in the Square data model, you will need to understand the concept of an order. This section will walk you through the Connect v2 concepts of an order and how orders are build on top of a product catalog.


Itemized transactions are built around the idea of an order. Square uses orders to logically group items, discounts, and taxes so they can be linked to an itemized transaction and the associated tenders. The item variations, taxes, and discounts included in an order can be defined ad hoc (at the time of the API call) or pulled from an existing product catalog.

For example, assume someone in California hears the podcast ad for Raphael's Puppy-Care Emporium and places an order online for:

  • 1 medium leather collar, engraved with a name.
  • 1 blue sweater, sized for a medium dog with 2-ply, with the podcast discount.

The final order includes 2 line items (with modifiers) and 3 price adjustments. The state sales tax and year-end sale discount are order-level price adjustments because they affect the price of everything in the order. But the podcast discount is a line-item price adjustment because it only applies to the handmade sweater.

Basic order

When the customer pays for their order, the order object is referenced in the transaction object to create an itemized transaction. Linking a transaction and an order establishes the relationship between a monetary exchange and an itemized bill of sale (an order). And since transactions are always associated with a specific location, Square can use the itemized details to automatically track the physical inventory of the item variations at that location (when the product catalog has inventory tracking enabled).

Inventory tracking

Inventory is modeled as having a quantity of item variations in a given inventory status at a specific location. Inventory management is essentially the process of moving quantities of item variations between the different item states. For example, when the online order for a leather collar and heavy sweater is processed, the on-hand quantities for "Leather collar" and "Heavy sweater" are automatically updated by moving the number of purchased units for each item variation from IN_STOCK to SOLD.

Inventory tracking

In addition to automatic inventory tracking, Square also support nuanced inventory tracking (e.g., receiving stock, marking waste) and reconciliation.

< Product catalogs
Square SDKs >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow