Retrieve catalog object

GET

/v2/catalog/object/{object_id}

Returns a single CatalogItem as a CatalogObject based on the provided ID.

The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Permissions:ITEMS_READ

Try in API Explorer

Link to section

Path parameters

Example code

Link to section

object_id

string

Required

The object ID of any type of catalog objects to be retrieved.

Link to section

Query parameters

Link to section

include_related_objects

boolean

If true, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the objects field of the response. These objects are put in the related_objects field. Setting this to true is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example,

if the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Default value: false

Link to section

catalog_version

integer(64-bit)

Beta

Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects. If not included, results will be from the current version of the catalog.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

object

The CatalogObjects returned.

Link to section

related_objects

A list of CatalogObjects referenced by the object in the object field.

Link to section

Examples

GET /v2/catalog/object/{object_id}

curl https://connect.squareup.com/v2/catalog/object/W62UWFY35CWMYGVWK6TWJDNI \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Response JSON

{
  "object": {
    "type": "ITEM",
    "id": "W62UWFY35CWMYGVWK6TWJDNI",
    "updated_at": "2016-11-16T22:25:24.878Z",
    "version": 1479335124878,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "Tea",
      "description": "Hot Leaf Juice",
      "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "tax_ids": [
        "HURXQOOAIC4IZSI2BEXQRYFY"
      ],
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "2TZFAOHWGG7PAK2QEXWYPZSP",
          "updated_at": "2016-11-16T22:25:24.878Z",
          "version": 1479335124878,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "W62UWFY35CWMYGVWK6TWJDNI",
            "name": "Mug",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 150,
              "currency": "USD"
            }
          }
        }
      ]
    }
  }
}