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

  • Inventory management must be handled with the Inventory API (v1).
  • Applications using OAuth must have ITEMS_READ permission to read catalog objects and the ITEMS_WRITE permission to create, update, or delete catalog objects.
  • The Catalog API is not supported in sandbox mode at this time.

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.
Process flow

How to use it

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

Data model diagram

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",
          ...
        }
      }
    ]
  }
}

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
Catalog API Data Model >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow