Build a Simple Catalog

Applies to: Catalog API

Learn how to build a simple product catalog for a cafe that serves coffee in small and large sizes, with skim or whole milk.

The Catalog API manages the item library in the Square Dashboard. Use it to add, update, or delete items. An item is made up of related catalog objects like taxes, modifiers, and options.

• You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit squareup.com/activation.
• You're familiar with HTTPS. If this is your first time working with HTTPS, see TLS and HTTPS before continuing.
• You need a valid access token. You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square Credentials.

The Catalog API includes several objects that enable efficient and standardized definitions of item variations in the seller's inventory. These objects include the following:

• Items - Generalized items such as "Shirt".
• Item variation - Specific items for sale such as "Polo shirt: Lg, red".
• Item options - Standardized attributes such as color, size, and style.

To add an item to a seller's library, use the UpsertCatalogObject endpoint to create catalog objects for the item (for example, a cup of coffee). For information about using item options to set variation characteristics, see Define Item Variations Using Options.

Before selling coffee, the catalog needs an item called "Cup of Coffee" without a size, a price, or modifiers. To charge for the coffee, include variations specifying the size, the price, and any modifiers. Add two variations (Small Coffee and Large Coffee), a CatalogTax object for taxes, and two optional CatalogModifier objects (with Skim Milk and Whole Milk). These include:

• A CatalogItem object named Coffee for coffee drinks.
• Two CatalogItemVariation objects named Small and Large for the coffee drink size variations.
• A CatalogTax object for the sales tax applied when a payment is made on the coffee drink order.
• Two CatalogModifier objects for the two milk choices.
• A CatalogModifierList object to hold the two CatalogModifier objects to apply the milk choices to the coffee item.

The following steps apply to creating other types of catalog objects, except for image uploads. For details about uploading and attaching images to items, variations, or categories, see Work with Images.

To add a coffee item to a catalog as a product offering of a seller, call the UpsertCatalogObject endpoint to create a CatalogItem object in the catalog. This is shown in the following REST API example:

In most locales, a sales tax must be levied on a sold product. To support taking taxes on an order, you must first create a CatalogTax object to set up the tax to be applied when the payment is made on the order.

Alternatively, you can combine the calls to create the Coffee item with the Small and Large variations and the Drink Tax object into a single call to the BatchUpsertCatalogObjects endpoint, as shown:

In the previous example, note that the catalog item item_data property includes the tax_ids sub-property:

 "tax_ids": [
     "#sales_tax"
 ]

This property connects the new CatalogTax to the CatalogItem created in the batch request. In an Orders API CreateOrder request, that tax is automatically applied to the coffee if the CreateOrder request includes the pricing_options property as shown in the following example:

 "pricing_options": {
      "auto_apply_discounts": false,
      "auto_apply_taxes": true
  }

To enable sellers to offer the choices of adding skim milk and whole milk to the coffee drink, you can create two catalog modifiers to apply to the Coffee item. One way to add the modifiers is to create a modifier list containing individual modifiers as its entries.

For the modifiers in the modifier list to be applied to the Coffee item, you must have the resultant modifier list applied to the Coffee item, as explained in step 4.

To apply the modifier list created in step 3, call the UpdateItemModifierLists endpoint as shown in the following example:

Alternatively, you can call the BatchUpsertCatalogObjects endpoint to create a modifier list with appropriate modifier entries and add the modifier list to the Coffee item, together with the required item variations, in a single call to create all related CatalogObject instances at once.

After building your catalog, you can view and verify it by calling the ListCatalog endpoint to inspect the catalog items. The following request shows an example:

• Video: Sandbox 101: Catalog API Explained
• Design a Catalog
• Catalog API
• Work with Images