Build Basics: Square Data Model

Orders and Inventory Tracking

To understand how itemization and money movement is linked in the Square data model, you need to understand the concept of an order.

This topic walks you through the Square API concepts of an order and how order items are specified with a product catalog.

Orders Permalink Get a link to this section

Square uses orders to logically group items, discounts, and taxes so they can be linked to one or more payment. The item variations, taxes, and discounts included in an order can be pulled from an existing product catalog or defined ad hoc (at the time of the API call). For example, assume someone in California hears the podcast ad for Raphael's Puppy-Care Emporium and places an order online for:

  • One medium leather collar, engraved with a name.

  • One blue sweater, sized for a medium dog with two-ply, with the podcast discount.

The final order includes two line items (with modifiers) and three 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. However, the podcast discount is a line-item price adjustment because it only applies to the handmade sweater.

basic-order

When the customer pays for the order, the payment object references the order object to link it to the payment. Linking a payment and an order establishes the relationship between a monetary exchange and an itemized bill of sale (an order). Because orders 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). Itemized payments and refunds can also be searched, updated, and managed using the Orders API.

Fulfillment Permalink Get a link to this section

Orders can also be pushed directly into the Square Point of Sale application for fulfillment management. For example, suppose a customer has installed an order-ahead coffee application that allows them to order drinks and pay for them in advance.

Fulfillment orders are made with a nested object that tracks order status and other information required to fulfill the order. When the order is charged, it is pushed to the Square Point of Sale application. Sellers can then use the Point of Sale application to manage fulfillment.

The Orders API currently supports Pickup and Shipment type fulfillments.

Inventory tracking Permalink Get a link to this section

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 supports nuanced inventory tracking (such as, receiving stock and marking waste) and reconciliation.

Did you know?

Product catalogs and inventory tracking are not required to process payments with Square. However, using these elements improves reporting and makes it easier to manage payments.