Applies to: Catalog API
Learn how to archive, unarchive, and manage catalog items.
You can archive a catalog item when you don't want the item to show up in search results. This removes clutter from search requests.
Unlike deleted items, archived items remain fully or mostly operational. The Square API has full support and all CRUD operations are allowed as with any active catalog items. In the Square Dashboard or on Square POS devices, operational support is somewhat restricted:
- An item can be archived and unarchived in the Square Dashboard. It can be unarchived on Retail POS devices.
- Archived items can be viewed in the Square Dashboard using the
Archivedfilter in the Items library. - Archived items can be scanned on Square POS devices.
- Editable attributes of an archived item cannot be updated in the Square Dashboard or on POS devices.
- Archived items aren't displayed on Square POS devices, except in the following cases:
- Existing orders on Retail POS
- Existing purchase orders on Retail POS
- Stock counts on Retail POS
- Existing invoices
- Existing sales reports
- Saved shopping carts
Programmatically speaking, an archived item has the is_archived field set to true on the CatalogItem instances. It becomes unarchived when the is_archived field is set to false.
If the item ID is known, the archived catalog item can be retrieved by calling RetrieveCatalogObject or BatchRetrieveCatalogObjects.
If the item ID isn't known, the archived catalog item can be queried by calling SearchCatalogItems with the
archived_state=ARCHIVED_STATE_ARCHIVEDquery expression. Thearchived_statefilter can take other ArchivedState values to support returning non-archived catalog items or both archived and non-archived catalog items.
The SearchCatalogObjects endpoint can also return any archived items along with non-archived ones.
Note
Restaurant sellers cannot use the Square Dashboard to archive items, unarchive items, or retrieve archived items. However, they can do so using the Catalog API. API-initiated archived items aren't visible in the Square Dashboard.
To archive an item using the Catalog API, call the UpsertCatalogObject endpoint to archive an item while setting the is_archived attribute to true.
The following example shows how to archive an item by calling UpsertCatalogObject, while setting the is_archived input parameter to true.
Upsert catalog object
The successful response is similar to the following:
{
"catalog_object": {
"type": "ITEM",
"id": "7MV6J3MSDAVHHRZJCVU2I63G",
"updated_at": "2023-08-08T18:36:55.807Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691519815807,
"is_deleted": false,
"present_at_all_locations": true,
"present_at_location_ids": [
"SNTR5190QMFGM"
],
"item_data": {
"name": "Square Wine",
"is_taxable": true,
"visibility": "PRIVATE",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "V2R3K372J5RDIAIEWGHPODKX",
"updated_at": "2023-08-08T18:32:56.512Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691519576512,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "7MV6J3MSDAVHHRZJCVU2I63G",
"name": "Regular",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 7500,
"currency": "USD"
},
"sellable": true,
"stockable": true
}
}
],
"product_type": "REGULAR",
"is_archived": true
}
}
}Unlike a deleted object, an archived item remains fully operational using the Catalog API. For example, given the item ID, you can call RetrieveCatalogObject to retrieve an archived item.
The following example shows how to call the RetrieveCatalogObject endpoint to return an archived item that's identified by the specified item ID (7MV6J3MSDAVHHRZJCVU2I63G):
Retrieve catalog object
If the item hasn't changed since it was last archived, the response is identical to that returned when the item was archived. For an example response, see Response: Archive an item.
When archived item IDs aren't known, you can query archived items by calling the SearchCatalogItems endpoint while specifying the archived_state query filter to ARCHIVED_STATE_ARCHIVED.
The following example shows how to call SearchCatalogItems with the archived_state filter to query archived items:
Search catalog items
If you don't explicitly set archived_state, the default value is ARCHIVED_STATE_NOT_ARCHIVED and you get only non-archived items in return.
To receive both the archived and non-archived items, set archived_state to ARCHIVED_STATE_ALL.
The successful response is similar to the following:
{
"items": [
{
"type": "ITEM",
"id": "7MV6J3MSDAVHHRZJCVU2I63G",
"updated_at": "2023-08-08T18:36:55.807Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691519815807,
"is_deleted": false,
"present_at_all_locations": true,
"present_at_location_ids": [
"SNTR5190QMFGM"
],
"item_data": {
"name": "Square Wine",
"is_taxable": true,
"visibility": "PRIVATE",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "V2R3K372J5RDIAIEWGHPODKX",
"updated_at": "2023-08-08T18:32:56.512Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691519576512,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "7MV6J3MSDAVHHRZJCVU2I63G",
"name": "Regular",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 7500,
"currency": "USD"
},
"sellable": true,
"stockable": true,
"default_unit_cost": {
"amount": 7500,
"currency": "USD"
},
}
}
],
"product_type": "REGULAR",
"is_archived": true
}
}
],
"cursor": "",
"matched_variation_ids": [
"V2R3K372J5RDIAIEWGHPODKX"
]
}An archived item can be unarchived. To do so using the Catalog API, call the UpsertCatalogObject while specifying the archived item ID, setting the is_archived field to false, and keeping other writable properties intact.
The following example request shows how to unarchive an archived item:
Upsert catalog object
The successful response is similar to the following:
{
"catalog_object": {
"type": "ITEM",
"id": "7MV6J3MSDAVHHRZJCVU2I63G",
"updated_at": "2023-08-08T20:29:26.421Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691526566421,
"is_deleted": false,
"present_at_all_locations": true,
"present_at_location_ids": [
"SNTR5190QMFGM"
],
"item_data": {
"name": "Square Wine",
"is_taxable": true,
"visibility": "PRIVATE",
"variations": [
{
"type": "ITEM_VARIATION",
"id": "V2R3K372J5RDIAIEWGHPODKX",
"updated_at": "2023-08-08T18:32:56.512Z",
"created_at": "2021-04-28T03:21:47.542Z",
"version": 1691519576512,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "7MV6J3MSDAVHHRZJCVU2I63G",
"name": "Regular",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 7500,
"currency": "USD"
},
"sellable": true,
"stockable": true
}
}
],
"product_type": "REGULAR",
"is_archived": false
}
}
}