• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
List catalog

GET /v2/catalog/list

Returns a list of all CatalogObjects of the specified types in the catalog.

The types parameter is specified as a comma-separated list of the CatalogObjectType values, for example, "ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY, DISCOUNT, TAX, IMAGE".

Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use SearchCatalogObjects and set the include_deleted_objects attribute value to true.

Permissions
ITEMS_READ
 Try in API Explorer

Query Parameters

Example code
Name Description
cursor
string

The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See Pagination for more information.
types
string

An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc.

If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults.

At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.
catalog_version
integer (64-bit)
Beta

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. If not included, results will be from the current version of the catalog.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
cursor
string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.
objects
CatalogObject [ ]

The CatalogObjects returned.

Examples

You are viewing an old version of the API
GET /v2/catalog/list
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/catalog/list?types=category%2Ctax&limit=10 \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON 
{
  "objects": [
    {
      "type": "CATEGORY",
      "id": "5ZYQZZ2IECPVJ2IJ5KQPRDC3",
      "updated_at": "2017-02-21T14:50:26.495Z",
      "version": 1487688626495,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "L5R47DGBZOOVKCAFIXC56AEN",
      "updated_at": "2017-02-21T14:50:26.495Z",
      "version": 1487688626495,
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "name": "Sales Tax",
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "inclusion_type": "ADDITIVE",
        "percentage": "5.0",
        "enabled": true
      }
    }
  ]
}