Retrieve Catalog Objects

Applies to: Catalog API

Learn how to retrieve catalog objects by calling the ListCatalog, RetrieveCatalogObject, or BatchRetrieveCatalogObjects endpoint.

Retrieve catalog objects without specifying IDs

If you want to retrieve a catalog object but don't 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 lifecycle 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.

When a call to the ListCatalog endpoint is expected to return a large set of objects, you might need to use pagination to retrieve the results page by page.

Link to section

Request: List catalog objects of any version

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

List catalog

Link to section

Response: List catalog objects of any version

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

Link to section

Request: List catalog objects at a specific catalog version

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

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

Link to section

Response: List catalog objects at a specific catalog version

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

Link to section

Retrieve a catalog object with a specified ID and catalog version

If you have the ID of an object, RetrieveCatalogObject lets you return the specified catalog object. If the object has multiple versions (that is, they're 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):

Link to section

Request: Retrieve a catalog object with a specified ID and at a specified catalog version

Retrieve catalog object

Link to section

Response: Retrieve a catalog object with a specified ID and at a specified catalog version

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

Link to section

Retrieve multiple catalog objects with specified IDs and at a specified catalog version

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.

Link to section

Request: Batch retrieving catalog objects with specified IDs and at a specified catalog version

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

Batch retrieve catalog objects

Link to section

Response: Batch retrieving catalog objects of specified IDs and at a specified catalog version

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

Link to section

Retrieve a catalog object and its referenced objects

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:

Link to section

Request

Retrieve catalog object

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

Link to section

Response

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

Docs

Retrieve Catalog Objects

On this page