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:

List Catalog
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/catalog/list \
  -H 'Square-Version: 2021-07-21' \
  -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:

List Catalog
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/catalog/list?catalog_version=1598467546497&types=ITEM \
  -H 'Square-Version: 2021-07-21' \
  -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

Retrieve Catalog Object
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/catalog/object/QZEQSRNMTCXWXQD2QLEVCSRA?catalog_version=1598396203556 \
  -H 'Square-Version: 2021-07-21' \
  -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:

Batch Retrieve Catalog Objects
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/catalog/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -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"
      }
    }
  ]
}

Retrieve a catalog object and its referenced objects Permalink Get a link to this section

In a Square catalog, an object references other objects by their IDs. To retrieve the referenced objects with their properties, set the include_related_objects query parameter to true when calling RetrieveCatalogObject or its batch variant.

For example, a CatalogPricingRule object can reference a CatalogDiscount, CatalogProductSet, CatalogTax, and others. When calling RetrieveCatalogObject specifying the ID of a pricing rule object and using defaults for all other input options, you get a compact result as follows:

{
  "object": {
    "type": "PRICING_RULE",
    "id": "DYOXHWTDIGV75BPSRY7E7FOD",
    "updated_at": "2021-04-23T04:36:33.649Z",
    "version": 1619152593649,
    "is_deleted": false,
    "present_at_all_locations": true,
    "pricing_rule_data": {
      "discount_id": "E3GXIY42XBSI7LRLFF42DYTS",
      "match_products_id": "FQAZS2FAPQKOXK5OUW3B7FXU",
      "exclude_products_id": "F4W3VBGEMPEPSI6Z27E5MT3F",
      "exclude_strategy": "MOST_EXPENSIVE",
      "application_mode": "AUTOMATIC",
      "discount_target_scope": "LINE_ITEM"
    }
  }
}

By explicitly setting include_related_objects to true, as shown in the following example:

Request Permalink Get a link to this section

Retrieve Catalog Object
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/catalog/object/DYOXHWTDIGV75BPSRY7E7FOD?include_related_objects=true \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

You get the following results with detailed information about the (recursively) referenced objects.

Response Permalink Get a link to this section

{
  "object": {
    "type": "PRICING_RULE",
    "id": "DYOXHWTDIGV75BPSRY7E7FOD",
    "updated_at": "2021-04-23T04:36:33.649Z",
    "version": 1619152593649,
    "is_deleted": false,
    "present_at_all_locations": true,
    "pricing_rule_data": {
      "discount_id": "E3GXIY42XBSI7LRLFF42DYTS",
      "match_products_id": "FQAZS2FAPQKOXK5OUW3B7FXU",
      "exclude_products_id": "F4W3VBGEMPEPSI6Z27E5MT3F",
      "exclude_strategy": "MOST_EXPENSIVE",
      "application_mode": "AUTOMATIC",
      "discount_target_scope": "LINE_ITEM"
    }
  },
  "related_objects": [
    {
      "type": "DISCOUNT",
      "id": "E3GXIY42XBSI7LRLFF42DYTS",
      "updated_at": "2021-04-23T04:36:33.649Z",
      "version": 1619152593649,
      "is_deleted": false,
      "present_at_all_locations": true,
      "discount_data": {
        "name": "BOGO",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage": "50.0",
        "application_method": "MANUALLY_APPLIED",
        "modify_tax_basis": "MODIFY_TAX_BASIS"
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "FQAZS2FAPQKOXK5OUW3B7FXU",
      "updated_at": "2021-04-23T04:36:33.649Z",
      "version": 1619152593649,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_all": [
          "F4W3VBGEMPEPSI6Z27E5MT3F",
          "HXQMTXD223N5XQTDBMBUNDIH"
        ],
        "quantity_exact": 1
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "F4W3VBGEMPEPSI6Z27E5MT3F",
      "updated_at": "2021-04-23T04:36:33.649Z",
      "version": 1619152593649,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_any": [
          "QZEQSRNMTCXWXQD2QLEVCSRA"
        ],
        "quantity_exact": 2,
        "all_products": false
      }
    },
    {
      "type": "ITEM",
      "id": "QZEQSRNMTCXWXQD2QLEVCSRA",
      "updated_at": "2021-04-27T21:08:38.635Z",
      "version": 1619557718635,
      "is_deleted": false,
      "custom_attribute_values": {
        "sq0ids-tDPX2MkYWBjjQSKR88V-BQ:online_readiness": {
          "name": "online_readiness",
          "custom_attribute_definition_id": "FSHYJTVR2BZ3E3LDZFCTD5AU",
          "type": "NUMBER",
          "number_value": "0.88742",
          "key": "sq0ids-tDPX2MkYWBjjQSKR88V-BQ:online_readiness"
        }
      },
      "present_at_all_locations": true,
      "image_id": "6PM4GCSHU5LYKW2NHB2MXZHM",
      "item_data": {
        "name": "Safari adventure",
        "description": "service",
        "visibility": "PRIVATE",
        "category_id": "LPKD3DOEDBF6TKBYHX26E3DM",
        "tax_ids": [
          "KBPWWOXZHOGNOSQ2LIVS4H27"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "C6MGLXXDLJ6I4QYZ6NHWOHO4",
            "updated_at": "2021-04-27T21:08:38.635Z",
            "version": 1619557718635,
            "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
                }
              ],
              "measurement_unit_id": "SDC4U3C332O5WJDARTUF6BAA"
            }
          }
        ],
        "product_type": "REGULAR",
        "skip_modifier_screen": false,
        "ecom_available": false,
        "ecom_visibility": "UNINDEXED"
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "F4W3VBGEMPEPSI6Z27E5MT3F",
      "updated_at": "2021-04-23T04:36:33.649Z",
      "version": 1619152593649,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_any": [
          "QZEQSRNMTCXWXQD2QLEVCSRA"
        ],
        "quantity_exact": 2,
        "all_products": false
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "HXQMTXD223N5XQTDBMBUNDIH",
      "updated_at": "2021-04-26T22:21:26.328Z",
      "version": 1619475686328,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "quantity_min": 1,
        "quantity_max": 3,
        "all_products": false
      }
    }
  ]
}