Manage Products

Catalog API Overview

Create and maintain a product catalog of items and services that can be linked to itemized transactions.

The Catalog API enables fast and flexible catalog management, including individual and batch support for retrieval, updates, and deletion. Handle simple tasks with minimal endpoint calls while still providing the functionality needed by more sophisticated applications.

Requirements and limitations

  • The Square Catalog API does not provide integrated inventory management. Inventory management is currently handled with the Inventory API (v1)
  • All Catalog calls must include an authorization token in the header for the targeted merchant account. Anonymous catalog calls are not allowed.
  • Applications using the Catalog API must have ITEMS_READ and ITEMS_WRITE permissions for the targeted merchant account.
  • The Square Catalog API is not supported in sandbox mode at this time.

The Catalog object model

The Catalog API packages all its information as a CatalogObject, which is a generalized wrapper for all the classes across Catalog's object model, including:

  • CatalogItem — core product information; used to configure the top-level entities of a catalog (e.g., Latte).
  • CatalogItemVariation — one or more incarnations of a product; used to represent the actual item being sold with an assigned price and SKU (e.g. Small, Medium, Large). SKUs are not required to be unique.
  • CatalogModifier — information about an individual modifier; used to provide customization information for a product (e.g., Whole Milk, Skim Milk, Almond Milk).
  • CatalogModifierList — a collection of modifiers that have been logically grouped (e.g., milk choices).
  • CatalogCategory — product category information; used to logically group similar products (e.g., pens vs. pencils or hot drinks vs. cold drinks).
  • CatalogDiscount — discount information; used to provide manually defined discounts for goods and services.
  • CatalogTax — taxation information; used to configure tax requirements for items in the catalog.

Catalog items, variations, & modifiers

When working with Square Catalog, it's important to understand the distinction between catalog items, variations, and modifiers:

  • catalog item — the core representation of a thing — in other words, the product — to be sold (e.g., a latte).
  • variation — the instantiation of a specific catalog item with an assigned price and SKU (e.g., a medium latte).
  • modifier — a product customization applicable to one or more variations that may (or may not) be associated with an additional cost (e.g., a medium latte with whole milk and no foam).

Catalog items versus variations

Catalog items can represent:

  • digital or physical items (e.g., a PDF printable, coffee),
  • services (e.g., personal training, dog walking), and/or
  • donations and dues (e.g., artistic patronage, club memberships).

A CatalogItem does not have a price or SKU because it represents the high-level product, not the actual item/service being sold. For example:

If merchants offer... Some possible catalog items are...
PDF printables
  • Monthly activity tracker, February 2017
  • Sherlock Holmes coloring page
  • Daily agenda, blank
Coffee
  • Latte
  • Mocha
  • Espresso
Personal training
  • Personal training session
  • Fitness assessment
  • Nutritional planning
Pet care
  • Dog Walking
  • Grooming
  • Training
Donation options
  • Patronage/membership
  • Sponsorship
  • Advertising partner

A CatalogItem must have at least one variation (CatalogItemVariation) associated with it before it can be added to a purchase or used in a transaction. Variations represent the specific version of the product being sold (often with an assigned SKU and price). For example:

If the catalog item is... Some possible variants are...
PDF printable: Monthly activity tracker, February 2017
  • A3 size
  • A4 size
  • A5 size
Latte
  • Large
  • Medium
  • Small
Personal training session
  • 30-minute session
  • 60-minute session
Dog walking
  • 60-minute session
  • 90-minute session
Patronage/Membership
  • Membership dues, monthly
  • Recurring donation, annual
  • One-time donation

Forcing a product to have at least one variation may seem arbitrary, but it's an important distinction when you add in modifications. 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.

Differentiating between the idea of a product (CatalogItem) and its manifestation (CatalogItemVariation), creates greater flexibility in distribution chain and inventory management without requiring excessive duplication.

Variations versus modifiers

Modifiers (CatalogModifier) are customizations to a product associated with a specific transaction. They are related to variations in that they have an associated price, but they don't have SKUs. The lack of SKU means they are product agnostic, 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
Milk type Whole, 2%, 1%, Almond, Coconut, Soy
Toppings Pickles, Lettuce, Onions, Mayo, Mustard, Pesto
Cover color Steel, Blue Jay, Barn Red
Language English, Spanish, Japanese, German

The difference between variations and modifications is that modifications are only relevant when a product can be customized as part of an order. For example:

  • Selecting a preferred pickup window for a dog walking service (e.g., early morning, afternoon, early evening).
  • Selecting a wrapping paper pattern when the purchase is a gift (e.g., blue, green, stripes, polka dots).
  • Selecting custom embroidery patterns for a jersey (e.g., bees, gophers, a ham sandwich).

In each of these cases, the specific CatalogItemVariation — i.e., the thing being added to a purchase — is irrelevant to the customization. For example, a pickup window is equally relevant whether the customer orders a 30-minute walk or a 60 minute walk, the wrapping paper selected applies regardless of the gift purchased, and the size of the jersey doesn't affect the custom embroidery selected.

Categories

The CatalogCategory object provides a basic structure for organizing the items in a catalog. Categories are listed on the "Categories" page of the Square Dashboard and in the "Categories" tab of the Items applet in the Square Point of Sale app.

While category names are entirely arbitrary (e.g., "Hot Drinks", "Team Favorites", "Quetzalcoatlus"), they should make sense when displayed in the Dashboard or POS. 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.

Discounts

The CatalogDiscount object provides information for reducing the total cost of an order. 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.

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.

Taxes

The CatalogTax object provides a basic structure for calculating the appropriate taxes for a CatalogItemVariation object. 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 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.

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).

Technical Overview

The Catalog API includes bulk endpoints to help reduce the number of API calls required for catalog management and pagination of large result sets to reduce server load. Changes made with the Catalog API are stored in Square's database and immediately visible in the Square Dashboard and Square Point of Sale across all merchant locations.

All exchanges with Catalog endpoints use the CatalogObject data type, which is a generalized wrapper for configuring common parameters (e.g, type, id) and package the entity-specific information for each of the core types in Catalog's object model:

{
  "type": "{{
    [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY | DISCOUNT | TAX]
  }}",
  "id": "{{ set by Catalog during object creation }}",
  "updated_at": "{{ date and time of most recent update }}",
  "version": {{ version of the CatalogObject }},
  "is_deleted": [ true | false ], // set by Catalog
  "connect_v1_ids": {
    "catalog_v1_id": "{{ itemID from Catalog v1 }}",
    "location_id": "{{ location where v1 ID is used }}"
  },
  "present_at_all_locations": [ true | false ],
  "present_at_location_ids": ["{{ LOCATIONID-1 }}", "{{ LOCATIONID-N }}"],
  "absent_at_location_ids": ["{{ LOCATIONID-1 }}", "{{ LOCATIONID-N }}"],

How to use it

High level object overview

The Catalog API packages all its information as a CatalogObject, which is a generalized wrapper for all the classes across Catalog's object model.

Catalog classes include:

  • CatalogItem — A template of core product information and the basis of top level products in a catalog; used to configure the top-level products of a catalog (e.g., Coffee).
  • CatalogCategory — product category information; used to logically group similar products (e.g., hot drinks vs. cold drinks).
  • CatalogItemVariation — one or more incarnations of a product; used to represent the actual item being sold with an assigned price and optional SKU (e.g. Small, Medium, Large). SKUs are not required to be unique.
  • CatalogModifier — information about an individual modifier; used to provide customization information for a product (e.g., Whole Milk, Skim Milk, Almond Milk).
  • CatalogModifierList — a collection of modifiers that have been logically grouped (e.g., Type of Milk.
  • CatalogDiscount — discount information; used to provide manually defined discounts for goods and services.
  • CatalogTax — taxation information; used to configure tax requirements for items in the catalog.

To learn more about these catalog object types, read our Catalog API Data Model.

The Catalog API also includes:

  • Bulk endpoints to help reduce the number of API calls required for catalog management.
  • Pagination of large result sets to reduce server load.

Changes made with the Catalog API are immediately visible in the Square Dashboard and Square Point of Sale across all merchant locations.

Catalog API request objects

All exchanges with Catalog endpoints use the CatalogObject data type, which is a generalized wrapper for configuring common parameters (e.g, type, id). Specific information for each of the core types are nested inside the CatalogObject.

For example, consider three different types of CatalogObjects: ITEM, ITEM_VARIATION, and TAX. They all include an idempotency_key and an object, but the contents of the object depend on the type specified.

The relationship betweenITEMs and ITEM_VARIATIONs can be declared by the nesting structure. Consider the a product called "Coffee" with two variations called "Small" and "Large". This would be represented as a CatalogObject of type ITEM that contained two child CatalogObject entries of type ITEM_VARIATION.

This sample JSON illustrates an ITEM and two nested ITEM_VARIATIONs.

{
  "type": "ITEM",
  "id": "111",

  "item_data": {
    "name": "Coffee",
    "description": "Hot bean juice",
    "variations": [
      {
        "type": "ITEM_VARIATION",
        "id": "222",
        "item_variation_data": {
          "item_id": "111",
          "name": "Small",
          ...
        }
      },
      {
        "type": "ITEM_VARIATION",
        "id": "333",
        "item_variation_data": {
          "item_id": "111",
          "name": "Large",
          ...
        }
      }
    ]
  }
}

Elaboration and best practices for data (required)

We strongly recommend reading about the Catalog API Data Model for advice on how to build and design your catalog.

How it works

A typical web app

Here is an example process flow for how a merchant application might interact with the Catalog API.

  1. Application frontend collects catalog item information from merchant user.
  2. The application backend packages a CatalogObject request object and sends it to the UpsertCatalogObject endpoint.
  3. Square adds the catalog objects to the merchant's user products and returns the catalog object to the application backend.
  4. The application backend captures the result and displays a success message to the merchant.
  5. The merchant can now retrieve information about this catalog item or reference it in calls to the Orders API.

alt_text

Idempotency Keys

Each request object to the Catalog API must include an idempotency key. Read more about idempotency.

Pagination

All Catalog endpoints that have the potential to return a large number of objects employ pagination. Read more about how Square endpoints paginate.

Next
Orders API Overview >

Ask for help on Stack Overflow or join our Slack channel