Catalog API

What It Does

The Catalog API lets you programmatically maintain a seller's Square catalog. You can use the API to create, view, update, or delete catalog objects to represent products for sale or services for hire. This includes variations of products and services, applicable taxes, and possibly allowable discounts to be applied when particular products or services are ordered.

Overview Permalink Get a link to this section

In the Catalog API, products and services are represented as objects of the CatalogItem type. Variations of a product or service are represented as CatalogItemVariation objects. Applicable taxes are represented as CatalogTax objects and discounts are represented as CatalogDiscount objects. In addition, rules can be represented as Square catalog objects. For example, a CatalogPricingRule object can represent rule-based discounts for automatic application when an applicable order is placed or updated.

The Square Catalog API is flexible. You can call the API to manage objects in a Square catalog individually or you can process a batch of objects in a single API call. Batch operations through bulk endpoints help reduce the number of API calls required for catalog 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 to create and manage a Square catalog in the Square Seller Dashboard one item at a time. In addition, the API enables seamless integration of the Square catalog with other Square or third-party services.

Newly created and updated catalog objects using the Catalog API are immediately visible in the Square Seller Dashboard and Square Point of Sale across all seller locations.

Requirements and limitations Permalink Get a link to this section

  • Catalog and inventory are different services. Do not use the Catalog API for inventory management. Use the Inventory API instead.

  • Applications using OAuth must have ITEMS_READ permission to read catalog objects and the ITEMS_WRITE permission to create, update, or delete catalog objects.

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

Catalog objects Permalink Get a link to this section

The Catalog API refers to data entries generically as CatalogObject instances. A particular CatalogObject instance must also be one of the following catalog object type:

CatalogObject functions as a generalized wrapper class for any types of Square catalog objects. To learn more about Square catalog object types, see Design a Catalog.

As an example, consider CatalogObject instances of the ITEM, ITEM_VARIATION, and TAX types. Their data structures are illustrated in the following schematics. Each has an idempotency_key and an object, but the content of the object depends on the type specified.

data-model-diagram

When creating a catalog object, you must specify one of the specific object types and set appropriate data on the corresponding data field. For example, to create a catalog item, you must set ITEM on the CatalogObject.type attribute, set a CatalogItem instance on the CatalogObject.item_data field, and leave any other data fields unset. Similarly, to create a catalog item variation, you must set ITEM_VARIATION on the CatalogObject.type attribute, set a CatalogItemVariation instance on the CatalogObject.item_variation_data field, and leave all other data fields unset. It is an error to set a CatalogObject.<lower-cased-type-value>_data field with an unmatched CatalogObject instance corresponding to the CatalogObject.type attribute value.

When searching for or retrieving 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 do not specify any object type, the result includes all types of catalog objects satisfying any of specified query conditions.

Reference other objects by their IDs Permalink Get a link to this section

You can create catalog objects individually. When an object references another object, it does so by specifying the ID of the referenced object. For example, when referencing applicable taxes, you set the CatalogTax instance ID to the tax_id attribute on the corresponding CatalogItem instance. If the referenced object exists, its ID value must be retrieved before the object can be referenced.

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:

curl https://connect.squareup.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2020-07-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "cbdc3522-615e-443a-b2a6-d18d55ce3f4f",
    "batches": [
      {
        "objects": [
          {
            "id": "#item",
            "type": "ITEM",
            "item_data": {
              "name": "Product",
              "product_type": "REGULAR",
              "tax_ids": [
                "#tax"
              ]
            }
          },
          {
            "id": "#tax",
            "type": "TAX",
            "tax_data": {
              "applies_to_custom_amounts": true,
              "enabled": true,
              "name": "Tax",
              "percentage": "10"
            }
          }
        ]
      }
    ]
  }'

The corresponding response looks similar to this:

{
  "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"
    }
  ]
}

Reference objects as nested objects Permalink Get a link to this section

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.

This sample JSON illustrates an ITEM and two nested ITEM_VARIATION instances.

curl https://connect.squareup.com/v2/catalog/batch-upsert \
  -X POST \
  -H 'Square-Version: 2020-07-22' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "b9f442a2-73d9-42c9-9453-e98c53e589ad",
    "batches": [
      {
        "objects": [
          {
            "id": "#item",
            "type": "ITEM",
            "item_data": {
              "name": "Product",
              "product_type": "REGULAR",
              "variations": [
                {
                  "id": "#item_variation",
                  "type": "ITEM_VARIATION",
                  "item_variation_data": {
                    "name": "Variation",
                    "price_money": {
                      "amount": 500,
                      "currency": "USD"
                    },
                    "pricing_type": "FIXED_PRICING",
                    "sku": "11910345"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }'

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

Did you know?

You should read Product Catalogs for advice about 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. For more information, see Idempotency.

Pagination Permalink Get a link to this section

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

Related topics Permalink Get a link to this section