Catalog API

Applies to: Catalog API | Inventory API | Orders API

Learn about creating and managing a seller's item library (also known as a catalog) with the Catalog API.

The Square item library allows sellers to record detailed information about their products and business processes. It includes products or services, variations, options, categories, discounts, and taxes. It also supports pricing rules for automatic price adjustments under certain conditions.

The Catalog API allows you to manage a seller's item library programmatically. You can create, view, update, or delete catalog items and update inventory levels of stocked items using the Inventory API. Create and track customer orders using the Orders API. As an order is created, its line items are selected from the item library and on completion of an order, the line items sold are subtracted from the inventory of the items.

The Catalog API supports individual or batch operations to reduce the number of API calls. It also handles large result sets page by page to reduce server load. Without the Catalog API, you need to use the Item Editor in the Square Dashboard to manage items one by one. The API integrates the item library with other Square or third-party services.

New items created with the Catalog API are immediately visible in the Square Dashboard and Point of Sale across all locations. Use the Catalog API for item libraries and the Inventory API for inventory management.

• Applications using OAuth must have ITEMS_READ permission to read catalog objects and ITEMS_WRITE permission to create, update, or delete catalog objects.
• Individual catalog items can have up to 250 item variations.

An item library entry for a product or service is called a catalog item. For example, a shirt from a specific brand should be an item. Variations, like different sizes of the shirt, are called item variations. This makes it easy to retrieve related products together. Without item variations, you need to retrieve items one by one or filter them yourself. Discounts and taxes are also catalog entries, called catalog discount and catalog tax. These are examples of the various types of entries in the Square catalog representing different business data or processes.

The Catalog API exposes catalog entries as generic CatalogObject instances, which act as a wrapper for various types of Square catalog objects. Each CatalogObject instance has a specific type such as a CatalogItem. For example, an item variation is both a CatalogObject and a CatalogItemVariation. Taxes are CatalogObject and CatalogTax types. These are examples of the different types of catalog entries used in managing a seller's business.

The following diagram of CatalogObject instances of the ITEM, ITEM_VARIATION, and TAX types illustrates this relationship. Each instance has an idempotency_key property, which is required when the object is created or updated, and an object property, whose value depends on the type specified.

To create a catalog entry, choose the appropriate type and provide matching data. For example, to add an item, create a CatalogObject with ITEM as the type and assign item data. The resulting instance is both a CatalogObject and a CatalogItem. Similarly, to add an item variation, set the type to ITEM_VARIATION and provide item variation data. The result is both a CatalogObject and a CatalogItemVariation. Setting a mismatched data field causes an error.

Additional examples:

• To add an item option to a catalog, create a CatalogObject instance and set its type property value as ITEM_OPTION and its item_option_data field value as a CatalogItemOption instance.

• To add a tax entry to a catalog, create a CatalogObject instance and set its type property value as TAX and its tax_data field value as a CatalogTax instance.

• To add a pricing rule to a catalog, create a CatalogObject instance and set its type property value as PRICING_RULE and its pricing_rule_data field value as a CatalogPricingRule instance.

When a catalog object references other catalog objects, it uses their IDs. For example, a tax applied to an item is referenced through the tax_ids property on the CatalogItem object. You must first create the tax object, get its ID, and then reference it from the item. Catalog objects can be created individually.

When creating a new object and its dependent objects in the same batch request, you need to use client-assigned temporary IDs. These IDs are #-prefixed unique strings. After creation, Square assigns unique IDs to these objects. The batch response provides a mapping between your temporary ID and the ID assigned by Square.

For example, the following BatchUpsertCatalogObjects request payload shows how temporary IDs are used to identify and reference catalog objects to be created in the same request:

In some cases, objects can be referenced as nested objects. For example, a CatalogItem instance references dependent item variations through the nested CatalogItemVariation instances.

The following example illustrates an ITEM and two nested ITEM_VARIATION instances:

A POST or PUT request of the Catalog API must include an idempotency key in the request body. For more information, see Idempotency.

All Catalog API endpoints that have the potential to return a large number of objects use pagination. For more information, see Pagination.

• Design a Catalog
• Build a Simple Catalog