v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB

Catalog

BatchRetrieveCatalogObjects

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.

post/v2/catalog/batch-retrieve

Request body

object_idsstring[] required

The IDs of the CatalogObjects to be retrieved.

include_related_objectsboolean nullable

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

catalog_versioninteger nullable

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.

include_deleted_objectsboolean nullable

Indicates whether to include (true) or not (false) in the response deleted objects, namely, those with the is_deleted attribute set to true.

include_category_path_to_rootboolean nullable

Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload.

Example request

{
  "include_related_objects": true,
  "object_ids": [
    "W62UWFY35CWMYGVWK6TWJDNI",
    "AA27W3M2GGTF3H6AVPNB77CK"
  ]
}

Response

Success

Example response

{
  "objects": [
    {
      "id": "W62UWFY35CWMYGVWK6TWJDNI",
      "is_deleted": false,
      "item_data": {
        "categories": [
          {
            "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
            "ordinal": 0
          }
        ],
        "description": "Hot Leaf Juice",
        "name": "Tea",
        "tax_ids": [
          "HURXQOOAIC4IZSI2BEXQRYFY"
        ],
        "variations": [
          {
            "id": "2TZFAOHWGG7PAK2QEXWYPZSP",
            "is_deleted": false,
            "item_variation_data": {
              "item_id": "W62UWFY35CWMYGVWK6TWJDNI",
              "name": "Mug",
              "ordinal": 0,
              "price_money": {
                "amount": 150,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            },
            "present_at_all_locations": true,
            "type": "ITEM_VARIATION",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878
          }
        ]
      },
      "present_at_all_locations": true,
      "type": "ITEM",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878
    },
    {
      "id": "AA27W3M2GGTF3H6AVPNB77CK",
      "is_deleted": false,
      "item_data": {
        "categories": [
          {
            "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
            "ordinal": 0
          }
        ],
        "description": "Hot Bean Juice",
        "name": "Coffee",
        "tax_ids": [
          "HURXQOOAIC4IZSI2BEXQRYFY"
        ],
        "variations": [
          {
            "id": "LBTYIHNHU52WOIHWT7SNRIYH",
            "is_deleted": false,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Regular",
              "ordinal": 0,
              "price_money": {
                "amount": 250,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            },
            "present_at_all_locations": true,
            "type": "ITEM_VARIATION",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878
          },
          {
            "id": "PKYIC7HGGKW5CYVSCVDEIMHY",
            "is_deleted": false,
            "item_variation_data": {
              "item_id": "AA27W3M2GGTF3H6AVPNB77CK",
              "name": "Large",
              "ordinal": 1,
              "price_money": {
                "amount": 350,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            },
            "present_at_all_locations": true,
            "type": "ITEM_VARIATION",
            "updated_at": "2016-11-16T22:25:24.878Z",
            "version": 1479335124878
          }
        ]
      },
      "present_at_all_locations": true,
      "type": "ITEM",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878
    }
  ],
  "related_objects": [
    {
      "category_data": {
        "name": "Beverages"
      },
      "id": "BJNQCF2FJ6S6UIDT65ABHLRX",
      "is_deleted": false,
      "present_at_all_locations": true,
      "type": "CATEGORY",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878
    },
    {
      "id": "HURXQOOAIC4IZSI2BEXQRYFY",
      "is_deleted": false,
      "present_at_all_locations": true,
      "tax_data": {
        "calculation_phase": "TAX_SUBTOTAL_PHASE",
        "enabled": true,
        "inclusion_type": "ADDITIVE",
        "name": "Sales Tax",
        "percentage": "5.0"
      },
      "type": "TAX",
      "updated_at": "2016-11-16T22:25:24.878Z",
      "version": 1479335124878
    }
  ]
}