Applies to: Catalog API | Inventory API
Learn more about creating and managing a seller's item library (also known as a catalog) with the Catalog API.
The Square item library lets a seller keep a record of a complete collection of data about product offerings and business processes involved in running the business. In the item library, the collection includes products for sale or services for hire. It also includes related information such as variations, options, categories, discounts, and taxes of a product or service. It can even include pricing rules that trigger automatic price adjustment under certain conditions.
The Catalog API lets you programmatically manage a seller's item library. You can use the Catalog API to create, view, update, or delete catalog entries and have them ready and available for constructing or updating the seller's inventories using the Inventory API, or for creating or completing customer orders using the Orders API.
The Catalog API is flexible. You can call the API to manage objects in the item library individually or process a batch of objects in a single API call. Batch operations through bulk endpoints help reduce the number of API calls required for item library management. To deal with large result sets, the Catalog API lets you handle them page by page to help reduce server load.
Without the Catalog API, you would have to use the Item Editor (from the Square Dashboard) to create and manage an item library one item at a time. In addition, the API enables seamless integration of the Square item library with other Square or third-party services.
Newly created and updated items using the Catalog API are immediately visible in the Square Dashboard and Square Point of Sale across all seller locations.
Items and inventory are different services. An item library keeps a record of products for sale or service for hire, along with the supporting data, whereas an inventory keeps a record of merchandise quantities (stock) at a given location. Use the Catalog API to manage an item library and use the Inventory API to manage an inventory.
An item library entry for a particular product or service is known as a catalog item or item for short. For example, an item for an eCommerce seller could be a shirt of a particular brand. Variations of a particular product can group related products together. Different sizes could be variations of a shirt. The corresponding item entries are known as item variations (or simply variations.) The concept of item variation makes it simple to retrieve closely related products in one pass. Without it, you would have to retrieve them one item at a time or retrieve all the items in one call and then to filter desired items yourself. Similarly, discounts and taxes are represented by entries known as catalog discount (discount) or catalog tax (tax), respectively. These are just a few examples of the many types of Square catalog entries representing different data or processes involved in running the business of a seller.
The Catalog API exposes catalog entries as generic CatalogObject instances. CatalogObject serves as a generalized wrapper class for any types of Square catalog objects. Each instance must also be of a particular type. A particular CatalogObject instance has a unique type associated with it and the associated data format is defined by the corresponding Catalog API type. For example, a particular product or service is both of the CatalogObject type in general and of the CatalogItem type in particular. A variation of an item is both a CatalogObject instance and a CatalogItemVariation instance. Similarly, a tax applicable to a product or service is of the CatalogTax type and a CatalogObject instance. These are just a few examples of the many types of Square catalog entries representing different data or processes involved in running the business of a seller.
The following schematics of CatalogObject instances of the ITEM, ITEM_VARIATION, and TAX types illustrate this. Each has an idempotency_key attribute, which is required when the object is created or updated, and an object attribute, whose value depends on the type specified.
There are many Catalog API types. Each models a particular data type. The following list shows some common types of Square Catalog API types:
CATEGORY - The corresponding CatalogObject, also a CatalogCategory instance, models a category as an association of a group of related catalog items.
CUSTOM_ATTRIBUTE_DEFINITION - The corresponding CatalogObject, also a CatalogCustomAttributeDefinition instance, defines a custom attribute to supplement another CatalogObject.
DISCOUNT - The corresponding CatalogObject, also a CatalogDiscount instance, models a discount applicable to a catalog item.
IMAGE - The corresponding CatalogObject, also a CatalogImage, represents an image file that can be associated with a catalog item, item variation, or category.
ITEM - The corresponding CatalogObject, also a CatalogItem instance, represents a product for sale or service for hire.
ITEM_VARIATION - The corresponding CatalogObject, also a CatalogItemVariation instance, models varieties of a product or service so that the variations can treated as a single product or service. For example, a small-, medium-, or large-sized shirt is just a shirt, possibly with the same or different price.
MEASUREMENT_UNIT - The corresponding CatalogObject, also a CatalogMeasurementUnit instance, models the unit of for-sale products or for-hire services as specified in an item variation, or the precision of numerical quantities.
MODIFIER - The corresponding CatalogObject, also a CatalogModifier instance, represents a modification to an item at the time of sale.
MODIFIER_LIST - The corresponding CatalogObject instance, also a CatalogModifierList instance, represents a list of modifiers used to apply the contained modifiers to an item.
PRICING_RULE - The corresponding CatalogObject instance, also a CatalogPricingRule instance, is used to specify rules for automatic cost adjustments, including discounts.
PRODUCT_SET - The corresponding CatalogObject instance, also a CatalogProductSet instance, represents a set of products, to which price adjustments and other operations can be applied.
QUICK_AMOUNTS_SETTINGS - The corresponding CatalogObject instance, also a CatalogQuickAmountsSettings instance, represents preset charges for quick transactions.
TAX - The corresponding CatalogObject instance, also a CatalogTax instance, represents a tax applicable to an item.
TIME_PERIOD - The corresponding CatalogObject instance, also a CatalogTimePeriod instance, represents a time duration that a specified operation or condition remains applicable.
To learn more about Square catalog object types, see Design a Catalog.
To search for or retrieve catalog objects, you can specify a specific type to narrow the scope of the results to within the specified type of CatalogObject instances. If you don't specify any catalog type, the result includes all types of catalog objects satisfying any of specified query conditions.
In the Catalog API, a catalog entry is exposed as a generic CatalogObject instance. To create a particular catalog entry, you must choose an appropriate type and specify matching data of the corresponding type. The resulting CatalogObject instance is also a type-specific data object. For example, to add an item to a catalog, you create a CatalogObject instance while specifying ITEM as the type attribute value on the CatalogObject and assign item data to the item_data field on the CatalogObject. The resulting CatalogObject instance is also a CatalogItem instance. It's an error to set another *_data field. Similarly, to add an item variation to the catalog, you must create a CatalogObject instance while setting the type value as ITEM_VARIATION and the item_variation_data field with appropriate item variation data. The result is both a CatalogObject instance and a CatalogItemVariation instance. It's an error to set a CatalogObject data field that doesn't match the specified type value.
To further understand this pattern, review more examples:
To add an item option to a catalog, you can create a CatalogObject instance and set its type attribute value as ITEM_OPTION and its item_option_data field value as a CatalogItemOption instance. The result is both a CatalogObject instance and a CatalogItemOption instance.
To add a tax entry to a catalog, you can create a CatalogObject instance and set its type attribute value as TAX and its tax_data field value as a CatalogTax instance. The result is both a CatalogObject instance and a CatalogTax instance.
To add a pricing rule to a catalog, you can create a CatalogObject instance and set its type attribute value as PRICING_RULE and its pricing_rule_data field value as a CatalogPricingRule instance. The result is both a CatalogObject instance and a CatalogPricingRule instance.
Reference other objects by their IDs
When a catalog object references other catalog objects, it does so by specifying the IDs of the referenced objects. For example, when a tax is applied to an item, the applied tax is referenced through the tax_ids property on the CatalogItem object. This means that you must first create the tax object, retrieve its ID, and then reference the tax object ID from the item. You can create catalog objects individually.
When creating a new object and its dependent objects in the same request against a batch endpoint, you can use temporary IDs to reference the to-be-created objects. Temporary object IDs are client-assigned and #-prefixed unique strings within the request payload. After the objects are created, their IDs are reassigned Square-generated unique ID values.
For example, the following BatchUpsertCatalogObjects request payload shows how temporary IDs are used to identify a catalog object and to reference another object to be created in the same request:
The corresponding response looks similar to the following:
{
"objects": [
{
"type": "ITEM",
"id": "YROAMETK37LN3EBO3N2I3UJZ",
"updated_at": "2020-07-30T23:54:04.021Z",
"version": 1596153244021,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Product",
"tax_ids": [
"HXAKDGIAUCJ3XFLM77GOP7FW"
],
"product_type": "REGULAR"
}
},
{
"type": "TAX",
"id": "HXAKDGIAUCJ3XFLM77GOP7FW",
"updated_at": "2020-07-30T23:54:04.021Z",
"version": 1596153244021,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Applicable tax",
"percentage": "10.0",
"enabled": true
}
}
],
"id_mappings": [
{
"client_object_id": "#item",
"object_id": "YROAMETK37LN3EBO3N2I3UJZ"
},
{
"client_object_id": "#tax",
"object_id": "HXAKDGIAUCJ3XFLM77GOP7FW"
}
]
}
The resulting CatalogItem object ("id": "YROAMETK37LN3EBO3N2I3UJZ") references the applicable tax by the resulting CatalogTax object ID ("tax_ids": ["HXAKDGIAUCJ3XFLM77GOP7FW"]).
Reference objects as nested objects
In some cases, objects can be referenced as nested objects. For example, a CatalogItem instance references dependent item variations through the nested CatalogItemVariation instances. This is shown in the following example.
The following example illustrates an ITEM and two nested ITEM_VARIATION instances:
In the previous request, the CatalogItem instance references the dependent item variation as a nested CatalogItemVariation instance declared as an element of the variations list.
The successful request returns a payload similar to the following:
{
"objects": [
{
"type": "ITEM",
"id": "MPNKY5VHGDAPIIFB7QEIXRJZ",
"updated_at": "2020-07-31T00:23:08.786Z",
"version": 1596154988786,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Product",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "EF27LLTCW5D33Y5LZX4KZIEZ",
"updated_at": "2020-07-31T00:23:08.786Z",
"version": 1596154988786,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "MPNKY5VHGDAPIIFB7QEIXRJZ",
"name": "Variation",
"sku": "11910345",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 500,
"currency": "USD"
}
}
}
],
"product_type": "REGULAR"
}
}
],
"id_mappings": [
{
"client_object_id": "#item",
"object_id": "MPNKY5VHGDAPIIFB7QEIXRJZ"
},
{
"client_object_id": "#item_variation",
"object_id": "EF27LLTCW5D33Y5LZX4KZIEZ"
}
]
}
Notice that the request automatically populates the item_id attribute value with the newly created CatalogItem object ID. If the item and item variation are created with individual calls, you need to set the item_id value explicitly when creating the item variation.
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.