Square Data Model

Product catalogs

Product catalogs are not required to process payments, but using them can help you track and manage your inventory, discounts, and taxes. To take full advantage of the benefits that come from itemizing transactions, you will need to understand how Square models product catalog information. This section will walk you through the Connect v2 concepts of a catalog, catalog items, item variations, discounts, and taxes.

Square transactions come in two forms: ad hoc and structured.

  • An ad hoc transaction can be a straightforward charge or an itemized transaction where the items are defined at the point of the API call.
  • A structured transaction is an itemized transaction based on an explicit product catalog.

Structured transactions require a predefined product catalog. A product catalog is the set of objects or services associated with a business entity. Product catalogs also include price modifiers like taxes and discounts. At its most basic, Square represents product catalog information as a set of items, item variations, and item modifiers.

Catalog items

A catalog item is the most basic representation of the product or service being sold. For example, the product catalog of Raphael's Puppy-Care Emporium might include the following catalog items:

  • Leather collars
  • Retractable leashes
  • Handmade dog sweaters, made-to-order by a local artist
  • Small-batch chicken treats
  • Bathing services

Item variations

A catalog item must have at least one item variation to be used in a transaction. A catalog item variation represents a specific instance of the catalog item being sold (often with an assigned SKU and price). Catalog items can have multiple item variations, each with its own SKU, or they can be tied to a single item variation, with the same name, in a 1-to-1 mapping. For example, the catalog items in the product catalog for Raphael's Puppy-Care Emporium might include the following item and item variation groupings:

  • Leather collar: small, medium, large, extra large
  • Retractable Leash - 5 feet: Retractable Leash - 5 feet
  • Retractable Leash - 10 feet: Retractable Leash - 10 feet
  • Retractable Leash - 30 feet: Retractable Leash - 30 feet
  • Handmade sweater: red, blue, purple, orange
  • Chicken treats: tendon pinwheel, chewy trainers, chicken and bacon
  • Bathe and brush: toy breed, miniature breed, standard breed, large breed
Item variations

In this example, most of the item variations are grouped under a common catalog item, but the retractable leashes are structured as 1-to-1 pairs of catalog items and item variations with the same name.

Item modifiers

The item variations in a product catalog can also be combined with item modifiers to capture additional detail about the item variation sold as a part of the itemized transaction. Catalog item modifiers typically represent customizations that may add an additional cost or can be applied to many different item variations.

Catalog data structures are extremely flexible and the product catalog model should be defined in a way that makes sense for the underlying business based on its industry, size, and what the business offers for purchase. For example, Raphael's Puppy-Care Emporium receives leather collars and retractable leashes pre-tagged from the distributor where each size has its own SKU and suggested retail price. The retractable leashes come from different companies, so the leash sizes are modeled in the product catalog as independent catalog items, each with 1 item variation. But all of the leather collars are from the same company, so the collar sizes are modeled as different item variations under a single catalog item in the product catalog.

The Raphael's Puppy-Care Emporium product catalog also includes item modifiers. Engraving the leather is an item modifier because it alters the base price of the collar: it costs an additional 5 USD to engrave 1 line of text, and an additional 10 USD to engrave 2 lines of text. In contrast, the handmade sweaters are made-to-order by a local artist who wants to track the popularity of different colors. They ask Raphael's Puppy-Care Emporium to assign unique SKUs based on color, so the item variations for handmade sweater are based on color. In this case, it is the size of the sweater and the yarn pile that add additional cost to the base price for making the sweater. As a result, the different sizes and yarn options are modeled as item modifiers rather than item variations.

Item modifiers

Discounts and taxes

Product catalogs can also include discounts and taxes.

Assume Raphael's Puppy-Care Emporium is planning a year-end sale that discounts everything in the product catalog by 10% and a podcast advertising campaign where listeners get 5 USD off one item in their order. As part of the podcast campaign, Raphael's Puppy-Care Emporium has also begun shipping to selected locations within the US and needs to collect sales tax based on the shipping address to comply with federal regulations for taxation of online purchases.

Full product catalog

Currently, Square cannot calculate sales tax automatically during checkout so the sales tax will be added explicitly to the transaction as part of the itemized transaction. To simplify the process, Raphael's Puppy-Care Emporium adds tax objects to the product catalog for the different shipping destinations and activates those tax objects for everything sold through the website.

Adding discounts to the product catalog makes it easier to apply them across locations. And creating tax objects makes it easier for custom eCommerce solutions to programmatically check for valid shipping destinations and add the applicable sales tax during checkout.

Prev
< Customers and cards on file
Next
Orders and inventory tracking >

Ask for help on Stack Overflow or join our Slack channel