Design a Catalog

Applies to: Catalog API

Learn about items, item variations, and item modifiers and how to use them when designing a product catalog.

The Catalog API exposes Square catalog data entries as objects of the CatalogObject type. CatalogObject is a generic wrapper for all the classes across the catalog object model. A specific CatalogObject instance is of a specific type with a matching set of data. It's an error to set unmatched data on a given type of catalog objects.

Examples of catalog objects of specific types include, but aren't limited to, the following:

• Items are of the ITEM type and data must be set on the item_data attribute of a CatalogObject.
• Item variations are of the ITEM_VARIATION type and data must be set using the item_variation_data attribute of a CatalogObject.
• Modifiers are of the MODIFIER type and data must be set on the modifier_data attribute of a CatalogObject.
• Categories are of the CATEGORY type and data must be set on the category_data attribute of a CatalogObject.
• Discounts are of the DISCOUNT type and data must be set on the discount_data attribute of a CatalogObject.
• Pricing rules are of the PRICING_RULE type and data must be set on the pricing_rule_data attribute of a CatalogObject.
• Taxes are of the TAX type and data must be set on the tax_data attribute of a CatalogObject.
• Quick amount settings are of the QUICK_AMOUNT_SETTINGS type and data must be set on the quick_amount_settings_data attribute of a CatalogObject.
• Custom attributes are of the CUSTOM_ATTRIBUTE_DEFINITION type and data must be set on the custom_attribute_definition_data attribute of a CatalogObject.

You can follow this pattern to determine which data attribute on the CatalogObject instance to use for defining data of a given type.

A catalog item (CatalogItem) represents a product for sale (such as a latte) or a service for hire (such as dog walking). Generally speaking, catalog items can represent:

• Digital items (such as a PDF printable item).
• Event items (such as a concert or show).
• Food and beverage items (such as coffee and donuts).
• Physical items (such as shirts and pants).
• Services (such as personal training and dog walking).
• Donations and dues (such as artistic patronage and club memberships).

For more information about the product types of an item, see product_type.

A CatalogItem doesn't have a price or SKU. Rather, it contains one or more variations that have prices and SKUs. In other words, catalog items represent products you can sell and item variations represent specific product items you can charge. Examples are shown in the following table.

Catalog item variations (CatalogItemVariation) represent the specific price point of the product being sold (such as a medium coffee). Item variations are often assigned an SKU and a price. Examples are shown in the following table.

A CatalogItem must have at least one variation (CatalogItemVariation) and no more than 250 variations associated with it before it can be added to a purchase or used in a transaction. Item variations are added to a catalog item as nested objects assigned to the variations attribute of the CatalogItem instance.

In the Point of Sale application and Square 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, when a second variation is added, the variations appear as a list of prices and SKUs inside the item.

Different versions of a given product might:

• Have different SKUs.
• Have different prices.
• Only be offered in specific store locations.
• Be offered in specific quantities based on location.

Modifiers are customization choices that can be made to an order line item at the time of purchase. There are two types of modifiers: text-based modifiers and list-based modifiers. The latter is also referred to as non-text-based modifiers.

An example of text-based modifiers is a text that a buyer selects when buying a T-shirt with custom print. As an integral part of the T-shirt, the text-based modifier doesn't have its own price. In a Square catalog, it's represented by a CatalogModifierList object that has its modifier_type set to TEXT and contains properties specific to text-based modifiers.

A list-based modifier is encapsulated by a CatalogModifier object. It can be used to modify an item when it's a member of a modifier list contained in a CatalogModifierList object with its modifier_type set to LIST. Such modifiers have an associated price, but don't have SKUs. The lack of a SKU means that they can be applied to any of your products, but it also means that they cannot have a quantity.

A CatalogModifierList, with its modifier_type set to LIST, groups related non-text-based modifiers together according to the nature of the customization. Examples are shown in the following table.

Modifications are only relevant when a product can be customized as part of an order. Examples are shown in the following table.

In this case, the catalog item modifier (that is, the pickup timeframe) is equally relevant whether the buyer orders a 30-minute walk or a 60-minute walk.

Non-text-based modifiers can have an associated price that's added to the price of the item. For example, a coffee shop might charge an extra $0.50 for coconut milk.

For more information, see Enable Product Customization with Modifiers.

Catalog categories (CatalogCategory) provide a basic structure for organizing catalog items. Categories can be useful for making a large catalog easier to use and manage, but they should be designed with care because a given catalog item might only belong to one category.

While category names are entirely arbitrary (such as Hot Drinks, Team Favorites, and Quetzalcoatlus), they should make sense when displayed in the Square Dashboard or the Square Point of Sale application. Categories are listed on the Categories page of the Square Dashboard and on the Categories tab of the Items applet in the Square Point of Sale application.

To assign an item to a category, add a CatalogObjectCategory object containing the targeted category ID and, optionally, its position relative to other categories to the the categories list of the item.

The CatalogDiscount object provides information for reducing the total price of an order. Discounts can be a fixed value, a percentage, or a dynamic value entered at the time of sale.

Discounts are listed on the Discounts page of the Square Dashboard and on the Discounts tab of the Items applet in the Square Point of Sale application.

The CatalogPricingRule defines how discounts are automatically applied to orders or purchases made in a specified time period, on bundled products or services, or for multiple sale items. You use a CatalogProductSet object to specify discounted items, use a CatalogTimePeriod object to define the time period when a discount is active, and set discounts with the CatalogDiscount object. For more information about how to create a pricing rule, see Automatically Apply Discounts.

The 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 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 seller can override these defaults at the time of sale. It's important to note that CatalogTax objects exist in parallel with CatalogItem objects.

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.

A CatalogTax can be defined as follows:

• An additive tax - A tax added to 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 - A tax that is 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.

When 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, see Discounts, service charges, and taxes.

To allow the Square register to take a custom payment without first choosing a catalog item, the register provides a custom amount to be entered in the checkout screen. The Catalog API lets a seller define up to three custom payment amounts to populate a custom amount option in the register.

The CatalogQuickAmountsSettings object provides a basic structure for defining a set of quick payment amounts to be used in place of sale itemization in a Square Point of Sale (POS) device. When enabled, the custom amount option shows up to three quick amounts in the order set by the API. Quick amounts allow a seller to collect any of three possible payment amounts at the POS without selecting an item from the catalog. When quick amounts are used, the sale is reported as a custom amount in the Square Dashboard.

The three quick amount choices can be set by the seller using the API or they can be calculated by the Catalog API using the order history for the seller at that location.

You can add custom attributes to a Catalog object to store additional information for the 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 might not use modifiers because the service customization is typically captured as an item variation.

Consider the case where a seller provides personal training and offers the following catalog of services:

• On-site training
• In-home training
• Fitness evaluation
• Nutritional evaluation

At first glance, it might seem like only the first two products (on-site training and in-home training) need variations.

However, every catalog item must have at least one variation so this doesn't work. One solution is to group "Fitness evaluation" and "Nutritional evaluation" under a common offering (Health evaluation) with two variations: one for fitness level and one for nutrition. Examples are shown in the following table.

Now 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. Examples are shown in the following table.

By default, Square products (such as the Point of Sale application and the Square 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. The following table shows some differences in how the Square product experience differs for items that have one variation versus more than one variation:

In general, there are two good questions to consider when deciding whether 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 an 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.

• Build a Simple Catalog
• Update Catalog Objects
• Retrieve Catalog Objects
• Search for Items and Objects