Catalog API

What It Does

Use the Catalog API to create and manage catalog objects.

Catalog API

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
Permalink Get a link to this section

  • Inventory management must be handled with the Inventory API.

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

  • Individual catalog items can have up to 250 item variations.

Product components
Permalink Get a link to this section

The Catalog API packages all its information as a CatalogObject, which is a generalized wrapper for all the classes across Catalog's object model. To learn more about these catalog object types, read our guide on how to Design a Catalog.

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
Permalink Get a link to this section

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

Did you know?

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

Idempotency Keys
Permalink Get a link to this section

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

Pagination
Permalink Get a link to this section

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

Get started

Use the build guides below to integrate with Catalog API