Learn how to delete a catalog object and how to retrieve it for auditing.
Catalog API

Delete Catalog Objects and Query Deleted Objects

When no longer needed, an object in the catalog can be deleted. A deleted catalog object remains in the catalog, can be queried for auditing purposes, but is otherwise inoperable.

Using the Catalog API, you can delete a catalog object by calling the DeleteCatalogObject endpoint to handle a single object or calling the BatchDeleteCatalogObjects endpoint to handle one or more objects.

The following example shows how to delete a single catalog object as identified by its ID (ZFJKJAQSFYULGXU6JBC6LDVL). The object is of the ITEM type and has one variation (XXHPAGFTJOZLMSMYWOSFGCTD) associated with it.

Delete Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/catalog/object/ZFJKJAQSFYULGXU6JBC6LDVL \
  -X DELETE \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

If successful, the above request return a response similar to the following:

The operation deletes the item (G5I2JPKMXSTHRIXIFORI53YX) and the contained item variation (XXHPAGFTJOZLMSMYWOSFGCTD), making them inoperable except for being searchable for auditing purposes.

To query deleted catalog objects, call the SearchCatalogObjects while setting the "include_deleted_objects":true and and other applicable query expressions.

The result contains both active and deleted objects. You need to parse the returned response to filter out deleted objects that have the is_deleted property set to true.

The following example request shows how to call SearchCatalogObjects to query deleted items.

Search Catalog Objects
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_related_objects": true,
    "object_types": [
      "ITEM"
    ],
    "include_deleted_objects": true
  }'

The successful response is similar to the following:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
{
  "objects": [
    {
      "type": "ITEM",
      "id": "AJH676Z3IMY3XP3LNG3PHSYS",
      "updated_at": "2023-06-22T21:58:12.827Z",
      "created_at": "2022-01-26T20:33:22.432Z",
      "version": 1687471092827,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "item testing sold out",
        "description": "Item for testing sold out",
        "is_taxable": true,
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "KIPW2ZRGP6NXY45C36ADJW5A",
            "updated_at": "2022-01-29T05:37:28.468Z",
            "created_at": "2022-01-26T20:33:22.432Z",
            "version": 1643434648468,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "AJH676Z3IMY3XP3LNG3PHSYS",
              "name": "item variation for inventory tracking",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 500,
                "currency": "USD"
              },
              "location_overrides": [
                {
                  "location_id": "SNTR5190QMFGM",
                  "track_inventory": true
                }
              ],
              "track_inventory": true,
              "sellable": true,
              "stockable": true
            }
          }
        ],
        "product_type": "REGULAR",
        "ecom_available": false,
        "ecom_visibility": "UNINDEXED",
        "description_html": "<p>Item for testing sold out</p>",
        "description_plaintext": "Item for testing sold out"
      }
    },
    {
      "type": "ITEM",
      "id": "G5I2JPKMXSTHRIXIFORI53YX",
      "updated_at": "2023-07-19T21:11:04.203Z",
      "created_at": "2023-07-19T21:09:47.306Z",
      "version": 1689801064203,
      "is_deleted": true,
      "present_at_all_locations": true,
      "item_data": {
        "name": "ITEM",
        "is_taxable": true,
        "product_type": "REGULAR",
        "ecom_available": false,
        "ecom_visibility": "UNINDEXED",
        "channels": [
          "CH_ddgQh11R4eH59sgQaGEo49Eb6ewL0mdrBrTg9QlQuYC"
        ]
      }
    }
  ],
  "latest_time": "2023-07-19T21:11:04.203Z"
}

The returned result contains both the deleted (with "is_deleted":true) and active (with "is_deleted":false) catalog objects of the specified types.

SearchCatalogObjects is the only operation that can be applied on deleted catalog objects. Any other operation attempted on a deleted object results in an error.

Calling RetrieveCatalogObject against a deleted object ID returns a 404 Not found response.

Other than querying by SearchCatalogObjects, you cannot perform any other operations on deleted catalog objects. In particular, you cannot undelete or otherwise modify a deleted CatalogObject instance. Any attempt to do so returns a 400 response indicating an invalid operation to update a non-existent object.