Build Basics: 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, understand how the Square API models product catalog information.

This topic walks you through the Square API 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 payment or an itemized sale where the items are defined at the point of the API call.

  • A structured transaction is an itemized sale 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 Permalink Get a link to this section

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 Permalink Get a link to this section

A catalog item must have at least one item variation to be used in a sale. 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 one-to-one 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, and 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, and Orange

  • Chicken Treats: Tendon Pinwheel, Chewy Trainers, and Chicken and Bacon

  • Bathe and Brush: Toy breed, Miniature breed, Standard breed, and Large breed


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

Item modifiers Permalink Get a link to this section

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 might 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 pretagged 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 one item variation. However, because all the leather collars are from the same company, 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 one line of text and an additional 10 USD to engrave two 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.


Discounts and taxes Permalink Get a link to this section

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.


Currently, Square cannot calculate sales tax automatically during checkout. As a result, the sales tax is 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. Creating tax objects also makes it easier for custom eCommerce solutions to programmatically check for valid shipping destinations and add the applicable sales tax during checkout.

Did you know?

Product catalogs are not required to process payments with Square. However, using a product catalog improves reporting and makes it easier to manage transactions over time.

To create and manage a product catalog, use the Catalog API, the Square Point of Sale application, or the Seller Dashboard.