Catalog API: Retrieve Catalog Objects

Retrieve Catalog Objects

You can use the Catalog API to retrieve catalog objects by calling the ListCatalog, RetrieveCatalogObject, or BatchRetrieveCatalogObjects endpoint.

Retrieve catalog objects without specifying IDs Permalink Get a link to this section

If you want to retrieve a catalog object but do not know its ID, ListCatalog returns a (paged) list of all objects created up to the point of the call. You can then inspect and select one.

As new objects are added to the catalog or changes are made to the exiting objects, the affected objects are assigned new versions. In a sense, versions are historical markers of objects in a catalog. Throughout the life cycle of a catalog, a catalog version represents a snapshot of the catalog at a particular time. The snapshot includes objects created or updated up to the specified version number. The included objects are of either the specified or lesser version.

By specifying a catalog version as an input to the ListCatalog endpoint, you can determine all changes made at a particular point of time throughout the history of the catalog.

Request: list catalog objects of any version Permalink Get a link to this section

The following cURL example returns all the objects of any version in a (small) catalog:

curl https://connect.squareupsandbox.com/v2/catalog/list \
  -H 'Square-Version: 2020-10-28' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Response: list catalog objects of any version Permalink Get a link to this section

{
  "objects": [
    {
      "type": "MEASUREMENT_UNIT",
      "id": "4RW2GG2JAZJUZJ2PICQWLOCE",
      "updated_at": "2020-08-25T21:26:38.674Z",
      "version": 1598390798674,
      "is_deleted": false,
      "present_at_all_locations": true,
      "measurement_unit_data": {
        "measurement_unit": {
          "volume_unit": "GENERIC_CUP",
          "type": "TYPE_VOLUME"
        },
        "precision": 0
      }
    },
    {
      "type": "CATEGORY",
      "id": "BCXXYC5OXEQK4BQHFA22QEUI",
      "updated_at": "2020-08-25T22:42:33.028Z",
      "version": 1598395353028,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "coffee"
      }
    },
    {
      "type": "ITEM",
      "id": "BDWYGZO5QQWWEVFV6PAEP3BS",
      "updated_at": "2020-11-02T21:25:44.14Z",
      "version": 1604352344140,
      "is_deleted": false,
      "present_at_all_locations": true,
      "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
      "item_data": {
        "name": "adventure",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "PRAVBIFA4IDWI3IPO6KQVV2B",
            "updated_at": "2020-11-02T21:25:44.14Z",
            "version": 1604352344140,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "BDWYGZO5QQWWEVFV6PAEP3BS",
              "name": "8-day explore",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250000,
                "currency": "USD"
              },
              "transition_time": 0
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE",
        "skip_modifier_screen": false
      }
    },
    {
      "type": "MEASUREMENT_UNIT",
      "id": "AR3VHRKBMOMM3GSUVJOPDROE",
      "updated_at": "2020-10-26T23:42:21.33Z",
      "version": 1603755741330,
      "is_deleted": false,
      "present_at_all_locations": true,
      "measurement_unit_data": {
        "measurement_unit": {
          "time_unit": "GENERIC_DAY",
          "type": "TYPE_TIME"
        },
        "precision": 1
      }
    },
    {
      "type": "MEASUREMENT_UNIT",
      "id": "D4O5QM2G4OK7UGL43QO6YSCG",
      "updated_at": "2020-10-26T23:44:17.751Z",
      "version": 1603755857751,
      "is_deleted": false,
      "present_at_all_locations": true,
      "measurement_unit_data": {
        "measurement_unit": {
          "time_unit": "GENERIC_HOUR",
          "type": "TYPE_TIME"
        },
        "precision": 3
      }
    },
    ...
  ]
}

Request: list catalog objects at a specific catalog version Permalink Get a link to this section

To inspect what is added to or changed in the catalog, you can call ListCatalog with a specific catalog version as a query parameter to get only those objects of the specified version as well as those of lesser versions.

The following cURL example returns CatalogItem objects at the catalog version of 1598467546497:

curl https://connect.squareupsandbox.com/v2/catalog/list?catalog_version=1598467546497&types=ITEM \
  -H 'Square-Version: 2020-12-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The results include only objects created or updated up to the particular point of time corresponding to the specified catalog version.

Response: list catalog objects at a specific catalog version Permalink Get a link to this section

{
  "objects": [
    {
      "type": "ITEM",
      "id": "QZEQSRNMTCXWXQD2QLEVCSRA",
      "updated_at": "2020-08-26T16:37:03.648Z",
      "version": 1598459823648,
      "is_deleted": false,
      "present_at_all_locations": true,
      "image_id": "6PM4GCSHU5LYKW2NHB2MXZHM",
      "item_data": {
        "name": "Product1",
        "description": "product",
        "visibility": "PRIVATE",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "C6MGLXXDLJ6I4QYZ6NHWOHO4",
            "updated_at": "2020-08-25T22:56:43.556Z",
            "version": 1598396203556,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "QZEQSRNMTCXWXQD2QLEVCSRA",
              "name": "Regular",
              "sku": "12345",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "location_overrides": [
                {
                  "location_id": "SNTR5190QMFGM",
                  "track_inventory": true,
                  "inventory_alert_type": "LOW_QUANTITY",
                  "inventory_alert_threshold": 10
                }
              ]
            }
          }
        ],
        "product_type": "REGULAR",
        "skip_modifier_screen": false,
        "ecom_available": false,
        "ecom_visibility": "UNINDEXED"
      }
    },
    {
      "type": "ITEM",
      "id": "TTWX5A7GKJAISB6XPT7NIHF5",
      "updated_at": "2020-08-26T18:45:46.497Z",
      "version": 1598467546497,
      "is_deleted": false,
      "present_at_all_locations": true,
      "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
      "item_data": {
        "name": "Service",
        "product_type": "APPOINTMENTS_SERVICE"
      }
    },
    {
      "type": "ITEM",
      "id": "3KZ5V3SFVKGRCFQZI6JIMGVW",
      "updated_at": "2020-08-26T18:45:46.497Z",
      "version": 1598467546497,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "AA Service",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "3RJAVZQKCD5T6GPVWQCYK647",
            "updated_at": "2020-08-26T18:45:46.497Z",
            "version": 1598467546497,
            "is_deleted": false,
            "present_at_all_locations": true,
            "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
            "item_variation_data": {
              "item_id": "3KZ5V3SFVKGRCFQZI6JIMGVW",
              "name": "AA SERVICE",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 50000,
                "currency": "USD"
              },
              "inventory_alert_type": "NONE"
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE"
      }
    }
  ]
}

Retrieve a catalog object with a specified ID and catalog version Permalink Get a link to this section

If you have the ID of an object, RetrieveCatalogObject lets you return the specified catalog object. If the object has multiple versions, i.e., they are created or updated at different times, you can specify a catalog version to narrow the selection to the specified point of time.

The following cURL example retrieves a catalog object of the ID (QZEQSRNMTCXWXQD2QLEVCSRA) and version (1598396203556):

Request: retrieve a catalog object with a specified ID and at a specified catalog version Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/catalog/object/QZEQSRNMTCXWXQD2QLEVCSRA?catalog_version=1598396203556 \
  -H 'Square-Version: 2020-10-28' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

Response: retrieve a catalog object with a specified ID and at a specified catalog version Permalink Get a link to this section

{
  "object": {
    "type": "ITEM",
    "id": "QZEQSRNMTCXWXQD2QLEVCSRA",
    "updated_at": "2020-08-25T22:56:43.556Z",
    "version": 1598396203556,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Product1",
      "description": "product",
      "visibility": "PRIVATE",
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "C6MGLXXDLJ6I4QYZ6NHWOHO4",
          "updated_at": "2020-08-25T22:56:43.556Z",
          "version": 1598396203556,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "QZEQSRNMTCXWXQD2QLEVCSRA",
            "name": "Regular",
            "sku": "12345",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "location_overrides": [
              {
                "location_id": "SNTR5190QMFGM",
                "track_inventory": true,
                "inventory_alert_type": "LOW_QUANTITY",
                "inventory_alert_threshold": 10
              }
            ]
          }
        }
      ],
      "product_type": "REGULAR",
      "skip_modifier_screen": false,
      "ecom_available": false,
      "ecom_visibility": "UNINDEXED"
    }
  }
}

Retrieve multiple catalog objects with specified IDs and at a specified catalog version Permalink Get a link to this section

If you have multiple object IDs, BatchRetrieveCatalogObjects lets you return the specified objects in a single call. If the objects have multiple versions, you can specify a version to filter the results.

Request: batch retrieving catalog objects with specified IDs and at a specified catalog version Permalink Get a link to this section

The following cURL request shows how to retrieve two items (3KZ5V3SFVKGRCFQZI6JIMGVW and QZEQSRNMTCXWXQD2QLEVCSRA) at the catalog version of 1598467546497:

curl https://connect.squareupsandbox.com/v2/catalog/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2020-10-28' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_ids": [
      "3KZ5V3SFVKGRCFQZI6JIMGVW",
      "QZEQSRNMTCXWXQD2QLEVCSRA"
    ],
    "catalog_version": 1598467546497
  }'

Response: batch retrieving catalog objects of specified IDs and at a specified catalog version Permalink Get a link to this section

The response includes specified objects created or updated up to the specified catalog version of 1598467546497:

{
  "objects": [
    {
      "type": "ITEM",
      "id": "QZEQSRNMTCXWXQD2QLEVCSRA",
      "updated_at": "2020-08-26T16:37:03.648Z",
      "version": 1598459823648,
      "is_deleted": false,
      "present_at_all_locations": true,
      "image_id": "6PM4GCSHU5LYKW2NHB2MXZHM",
      "item_data": {
        "name": "Product1",
        "description": "product",
        "visibility": "PRIVATE",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "C6MGLXXDLJ6I4QYZ6NHWOHO4",
            "updated_at": "2020-08-25T22:56:43.556Z",
            "version": 1598396203556,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "QZEQSRNMTCXWXQD2QLEVCSRA",
              "name": "Regular",
              "sku": "12345",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "location_overrides": [
                {
                  "location_id": "SNTR5190QMFGM",
                  "track_inventory": true,
                  "inventory_alert_type": "LOW_QUANTITY",
                  "inventory_alert_threshold": 10
                }
              ]
            }
          }
        ],
        "product_type": "REGULAR",
        "skip_modifier_screen": false,
        "ecom_available": false,
        "ecom_visibility": "UNINDEXED"
      }
    },
    {
      "type": "ITEM",
      "id": "3KZ5V3SFVKGRCFQZI6JIMGVW",
      "updated_at": "2020-08-26T18:45:46.497Z",
      "version": 1598467546497,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "AA Service",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "3RJAVZQKCD5T6GPVWQCYK647",
            "updated_at": "2020-08-26T18:45:46.497Z",
            "version": 1598467546497,
            "is_deleted": false,
            "present_at_all_locations": true,
            "image_id": "7WWYBOW5AYLEWFW62HQX7EP4",
            "item_variation_data": {
              "item_id": "3KZ5V3SFVKGRCFQZI6JIMGVW",
              "name": "AA SERVICE",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 50000,
                "currency": "USD"
              },
              "inventory_alert_type": "NONE"
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE"
      }
    }
  ]
}