Catalog API Data Model
This article describes the core concepts used to structure Catalog API data.
Catalog object types
The Catalog API packages all its information as a
CatalogObject, which is a generalized wrapper for all the classes
across Catalog's object model.
The Catalog API supports the following types of catalog objects:
- Item variations
A catalog item (
CatalogItem) is the core representation of a product to be sold (e.g., a latte). For example, catalog
items can represent:
- digital or physical items (e.g., a PDF printable, coffee)
- services (e.g., personal training, dog walking)
- donations and dues (e.g., artistic patronage, club memberships)
CatalogItem does not have a price or SKU. Rather, it contains one or more variations that have prices and SKUs.
|If merchants offer...||Some possible catalog items are...|
|Hot caffeinated drinks||
Catalog item variations (
CatalogItemVariation) represent the specific price point of the product being sold (e.g. a
medium coffee). Item variations are often assigned an SKU and price.
|If the catalog item is...||Some possible variants are...|
CatalogItem must have at least one variation (
CatalogItemVariation) and no more than 250 associated with it before
it can be added to a purchase or used in a transaction. In the Point of Sale app and the Dashboard, items that contain
only one variation are typically displayed in a simplified form where the item variation price and SKU appear as
attributes of the item itself. However, once a second variation is added, the variations appear as a list of prices and
SKUs inside the item.
Different versions of a given product may have:
- different SKUs,
- different prices,
- only be offered in specific store locations, or
- offered in specific quantities based on location.
CatalogModifier) are customizations to a product associated with a specific transaction. They have an
associated price, but do not have SKUs. The lack of SKU means they can be applied to any of your products, but it also
means that they cannot have a quantity.
Modifiers can also be grouped into a list (
CatalogModifierList) based on the nature of the customization. For example:
|Catalog Modifier List||Modifiers|
Modifications are only relevant when a product can be customized as part of an order. For example:
|If the catalog item is...||And the variants are...||Some possible modifiers are…|
In this case, the catalog item modifier — i.e., the pickup window — is equally relevant whether the customer orders a 30-minute walk or a 60 minute walk.
Modifiers can have an associated price that is added to the price of the item. For example, a coffee shop may charge an extra $0.50 for Coconut Milk.
Catalog categories (
CatalogCategory) provide basic structure for organizing catalog items. Categories can be useful
for making a large catalog easier to look up and manage, but they should be designed with care as a given catalog item
may only belong to one category.
While category names are entirely arbitrary (e.g., "Hot Drinks", "Team Favorites", "Quetzalcoatlus"), they should make sense when displayed in the Dashboard or the Square Point of Sale app. Categories are listed in the Categories page of the Square Dashboard and in the Categories tab of the Items applet in the Square Point of Sale app.
CatalogDiscount object provides information for reducing the total cost of an order. Discounts can be a fixed
value, a percentage, or a dynamic value entered at the time of sale. They are applied to the pre-tax total of an entire
purchase, not to an individual item in the purchase.
Discounts are listed on the Discounts page of the Square Dashboard and in the Discounts tab of the Items applet in the Square Point of Sale app.
CatalogTax object provides a basic structure for calculating the appropriate taxes for an item variation. Tax
values are strictly percentage-based and applied to all of the individual items in a sale associated with the tax. As
part of its configuration, each
CatalogItem specifies the taxes that apply to it by default, although a merchant can
override these defaults at the time of sale. It's important to note that
CatalogTax objects exist in parallel with
When a new
CatalogItem is created, no taxes apply to it unless an associated
CatalogTax object is explicitly
provided. Taxes are listed on the "Taxes" page of the Square Dashboard.
CatalogTax can be defined as:
- an additive tax — added on top of the price of items they're applied to. For example, if an additive 10% tax is applied to a $100 item, the total is $110.
- an inclusive tax — assumed to already be included in the price of the items they apply to. For example, if an inclusive 10% tax is applied to a $100 item, the total is still $100, and the actual base cost of the item is assumed to be $90.91, with $9.09 of the total being the tax amount.
Once defined, taxes are applied to payments during one of the following phases:
- the subtotal phase — taxes applied during the subtotal phase are applied only to the base cost of applicable items. The vast majority of taxes are applied during this phase.
- the total phase — taxes applied during the total phase are applied to the base cost of applicable items, and to any tax amounts applied to those items during the subtotal phase.
In the case that a
CatalogItem is subject to both additive and inclusive taxes, the additive tax only applies to the
portion of the price that excludes the inclusive tax. For example, if a $100 item has a 10% inclusive tax and a 5%
additive tax, the 5% additive tax applies to the $90.91 base price of the item (the item price minus the inclusive tax).
For a more detailed look at how taxes and discounts are calculated, read the "How totals are calculated" section of the Orders API Overview.
Designing a product catalog
Designing a product catalog is part art and part science. Knowing exactly where to draw the line between an item, an item variation, and an item modifier can be nuanced and is entirely dependent on the products being offered.
Different business types and sizes use different patterns for creating a product catalog. For example:
- Smaller scale, retail accounts often use some basic variations for improved tracking and reporting, but few modifiers.
- Food and beverage accounts often make extensive use of item variations and modifiers because there tends to be a high degree of purchase customization.
- Services businesses often make extensive use of item variations, but may not make use of modifiers because the service customization is typically captured as an item variation.
A practical example
Consider the case where a merchant provides personal training and offers the following catalog of services:
- On-site training
- In-home training
- Fitness evaluation
- Nutritional evaluation
At first glance, it may seem like only the first two products (on-site training and in-home training) need variations:
But every catalog item must have at least one variation so this won't work. One solution is group "Fitness evaluation" and "Nutritional evaluation" under a common offering — Health evaluation — with two variations: one for fitness level and one for nutrition. For example:
But consider a situation where some of the evaluations don't need to be in-person. In this case, it might make more sense to keep the original product listing and add variations based on how the evaluation takes place. For example:
By default, Square products (such as he Point of Sale app and the Dashboard) assign the item variation name "Regular" to items that have only one variation. Square products display items that contain only one variation in a simplified view. Here are some differences in how the Square product experience differs for items that have one variation versus more than one variation:
|One item variation||More than one item variation|
|Item Editing||Variation name is hidden.
Variation price, SKU, inventory counts are inlined into the item.
|Variations are listed in a table containing name, sku, price, inventory count.|
|Adding to Cart||Employee is not prompted to select a variation.||Employee is prompted to select a variation,|
|Receipts||Only item name is printed.||Item name and variation name are printed.|
In general, there are two good questions to consider when deciding if something should be an item variation or an item modifier:
- Does the entry represent something that would have a SKU and assigned price? If so, the element should probably be an item variation.
- Does the entry represent a customization that possibly adds and additional cost to something with a SKU and base price or an attribute that could be applied to many different item variations? If so, the element should probably be a modifier.