Archive Catalog Items and Manage Archived Items

Applies to: Catalog API

Learn how to archive, unarchive, and manage catalog items.

Link to section

Overview

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 Seller Dashboard or on Square POS devices, operational support is somewhat restricted:

  • An item can be archived and unarchived in the Seller Dashboard. It can be unarchived on Retail POS devices.
  • Archived items can be viewed in the Seller Dashboard using the Archived filter in the Items library.
  • Archived items can be scanned on Square POS devices.
  • Editable attributes of an archived item cannot be updated in the Seller 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_ARCHIVED query expression. The archived_state filter 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 Seller 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 Seller Dashboard.

Link to section

Archive a catalog item

To archive an item using the Catalog API, call the UpsertCatalogObject endpoint to archive an item while setting the is_archived attribute to true.

Link to section

Request: Archive an item

The following example shows how to archive an item by calling UpsertCatalogObject, while setting the is_archived input parameter to true.

Upsert catalog object

Link to section

Response: Archive an item

The successful response is similar to the following:

Link to section

Retrieve an archived item

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.

Link to section

Request: 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

Link to section

Response: Retrieve an archived item

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.

Link to section

Search for archived items

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.

Link to section

Request: Search for archived items

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.

Link to section

Response: Search for archived items

The successful response is similar to the following:

Link to section

Unarchive an item

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.

Link to section

Request: Unarchive an item

The following example request shows how to unarchive an archived item:

Upsert catalog object

Link to section

Response: Unarchive an item

The successful response is similar to the following: