Applies to: Catalog API
Learn how to delete a catalog object and retrieve it for auditing.
When no longer needed, an object in the catalog can be deleted. A deleted catalog object remains in the catalog and 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 for a single object or the BatchDeleteCatalogObjects endpoint to handle multiple objects.
Important
If your application routinely deletes and recreates an entire catalog, the catalog size can double with each cycle. For example, deleting and recreating a catalog of 1,000 items results in 2,000 objects (1,000 deleted and 1,000 recreated). Each cycle adds the number of recreated objects to the total. This can degrade the performance of bulk operations, eventually causing timeouts.
If your application might need to restore a deleted object, it's better to archive it. When orders and inventory reference an archived item, unarchiving keeps those references valid. Deleting and recreating an item breaks these references, and you cannot update completed orders or inventory adjustments to point to the recreated item.
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
If successful, the request returns a response similar to the following:
{
"deleted_object_ids": [
"G5I2JPKMXSTHRIXIFORI53YX",
"XXHPAGFTJOZLMSMYWOSFGCTD"
],
"deleted_at": "2023-07-19T21:11:04.203Z"
}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 SearchCatalogObjects while setting "include_deleted_objects":true and other applicable query expressions. The result contains both active and deleted objects.
The following example request shows how to call SearchCatalogObjects to query items, including deleted ones:
Search catalog objects
The successful response is similar to the following:
{
"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 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.
If a deleted catalog object must be restored, your application needs to create a new object with the properties of the deleted object. However, the ID and version of the new object won't match those of the deleted object.