You are viewing an old version of the API

All Versions

Batch retrieve catalog objects

POST /v2/catalog/batch-retrieve

Returns a set of objects based on the provided ID.

Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Permissions

ITEMS_READ

Try in API Explorer

Request Body

Example code

Name Description

Name	Description
`object_ids string [ ]` Required	The IDs of the CatalogObjects to be retrieved.
`include_related_objects boolean`	If `true`, the response will include additional objects that are related to the requested objects, as follows: 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.


          
  
  
            object_ids
          


        

        
      string [ ]

Required

The IDs of the CatalogObjects to be retrieved.


          
  
  
            include_related_objects
          


        

        
    boolean

If true, the response will include additional objects that are related to the requested objects, as follows:

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.

Response Fields

Name	Description
`errors Error [ ]`	The set of Errors encountered.
`objects CatalogObject [ ]`	A list of CatalogObjects returned.
`related_objects CatalogObject [ ]`	A list of CatalogObjects referenced by the object in the `objects` field.

Examples

curl https://connect.squareup.com/v2/catalog/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "object_ids": [
      "W62UWFY35CWMYGVWK6TWJDNI",
      "AA27W3M2GGTF3H6AVPNB77CK"
    ],
    "include_related_objects": true
  }'

{
  "objects": [
    {
      "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"
              }
            }
          }
        ]
      }
    },
    {
      "type": "ITEM",
      "id": "AA27W3M2GGTF3H6AVPNB77CK",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Coffee",
        "description": "Hot Bean Juice",
        "category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
        "tax_ids": [
          "HURXQOOAIC4IZSI2BEXQRYFY"
        ],
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "LBTYIHNHU52WOIHWT7SNRIYH",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Regular",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "PKYIC7HGGKW5CYVSCVDEIMHY",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Large",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  ],
  "related_objects": [
    {
      "type": "CATEGORY",
      "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Beverages"
      }
    },
    {
      "type": "TAX",
      "id": "HURXQOOAIC4IZSI2BEXQRYFY",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878,
      "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
      }
    }
  ]
}

Catalog API You are viewing an old version of the API 2020-09-23 Version 2020-09-23 All Versions Catalog API Batch retrieve catalog objects

Request Body

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

Batch retrieve catalog objects