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

Archive Catalog Items and Manage Archived Items

When not used temporarily, a catalog item can be archived. An archived catalog item is not displayable in Square Seller Dashboard or on Square POS devices. Otherwise, it is fully functional. In particular, it can be updated to become unarchived and thus becomes displayable again in the Seller Dashboard or POS.

Operationally speaking, an archived item has the is_archived field set to true on the CatalogItem instances. They become 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 is not 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 value to support returning not archived catalog items or both of archived and not archived items.

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
  • 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
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "XOHN3EEAZAM37VLUSQD52BN6",
      "type": "ITEM",
      "item_data": {
        "product_type": "APPOINTMENTS_SERVICE",
        "is_archived": true,
        "name": "A Service Item",
        "variations": [
          {
            "id": "YP6CYNNZO3BXUM36BN3CDAA2",
            "type": "ITEM_VARIATION",
            "version": 1687545969365,
            "item_variation_data": {
              "name": "First service variation",
              "item_id": "XOHN3EEAZAM37VLUSQD52BN6",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 100,
                "currency": "USD"
              }
            }
          }
        ]
      },
      "version": 1687545969365
    }
  }'

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
{
  "catalog_object": {
    "type": "ITEM",
    "id": "XOHN3EEAZAM37VLUSQD52BN6",
    "updated_at": "2023-06-23T19:03:51.395Z",
    "created_at": "2023-06-23T18:46:09.365Z",
    "version": 1687547031395,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "A Service Item",
      "is_taxable": true,
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "YP6CYNNZO3BXUM36BN3CDAA2",
          "updated_at": "2023-06-23T18:46:09.365Z",
          "created_at": "2023-06-23T18:46:09.365Z",
          "version": 1687545969365,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "XOHN3EEAZAM37VLUSQD52BN6",
            "name": "First service variation",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 100,
              "currency": "USD"
            },
            "available_for_booking": true,
            "sellable": true,
            "stockable": true
          }
        }
      ],
      "product_type": "APPOINTMENTS_SERVICE",
      "is_archived": true
    }
  }
}

Unlike a deleted object, an archived item remains operable, except for not being displayable in the Square Seller Dashboard or on Square POS devices.

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 is identified by the specified item ID (XOHN3EEAZAM37VLUSQD52BN6):

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

If the item has not been changed since it is last archived, the response is identical to that returned when the the item was archived. For an example response, see Response: archive an item

When archived item IDs are not 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 to query archived items:

Search Catalog Items
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/catalog/search-catalog-items \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_types": [
      "APPOINTMENTS_SERVICE"
    ],
    "archived_state": "ARCHIVED_STATE_ARCHIVED"
  }'

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
{
  "items": [
    {
      "type": "ITEM",
      "id": "XOHN3EEAZAM37VLUSQD52BN6",
      "updated_at": "2023-06-23T19:03:51.395Z",
      "created_at": "2023-06-23T18:46:09.365Z",
      "version": 1687547031395,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "A Service Item",
        "is_taxable": true,
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "YP6CYNNZO3BXUM36BN3CDAA2",
            "updated_at": "2023-06-23T18:46:09.365Z",
            "created_at": "2023-06-23T18:46:09.365Z",
            "version": 1687545969365,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "XOHN3EEAZAM37VLUSQD52BN6",
              "name": "First service variation",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 100,
                "currency": "USD"
              },
              "available_for_booking": true,
              "sellable": true,
              "stockable": true
            }
          }
        ],
        "product_type": "APPOINTMENTS_SERVICE",
        "is_archived": true
      }
    }
  ],
  "cursor": "",
  "matched_variation_ids": [
    "YP6CYNNZO3BXUM36BN3CDAA2"
  ]
}

An archived item can be unarchived and become displayable again in the Square Seller Dashboard or on Square POS devices. To do so, call the UpsertCatalogObject while specifying the archived item ID, setting the is_archived field to true, and keeping other write-able properties intact.

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

Upsert Catalog Object
  • 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
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "XOHN3EEAZAM37VLUSQD52BN6",
      "type": "ITEM",
      "item_data": {
        "product_type": "APPOINTMENTS_SERVICE",
        "is_archived": false,
        "name": "A Service Item",
        "variations": [
          {
            "id": "YP6CYNNZO3BXUM36BN3CDAA2",
            "type": "ITEM_VARIATION",
            "version": 1687545969365,
            "item_variation_data": {
              "name": "First service variation",
              "item_id": "XOHN3EEAZAM37VLUSQD52BN6",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 100,
                "currency": "USD"
              }
            }
          }
        ]
      },
      "version": 1687547031395
    }
  }'

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
{
  "catalog_object": {
    "type": "ITEM",
    "id": "XOHN3EEAZAM37VLUSQD52BN6",
    "updated_at": "2023-07-19T22:48:17.61Z",
    "created_at": "2023-06-23T18:46:09.365Z",
    "version": 1689806897610,
    "is_deleted": false,
    "present_at_all_locations": true,
    "item_data": {
      "name": "A Service Item",
      "is_taxable": true,
      "variations": [
        {
          "type": "ITEM_VARIATION",
          "id": "YP6CYNNZO3BXUM36BN3CDAA2",
          "updated_at": "2023-06-23T18:46:09.365Z",
          "created_at": "2023-06-23T18:46:09.365Z",
          "version": 1687545969365,
          "is_deleted": false,
          "present_at_all_locations": true,
          "item_variation_data": {
            "item_id": "XOHN3EEAZAM37VLUSQD52BN6",
            "name": "First service variation",
            "ordinal": 0,
            "pricing_type": "FIXED_PRICING",
            "price_money": {
              "amount": 100,
              "currency": "USD"
            },
            "available_for_booking": true,
            "sellable": true,
            "stockable": true
          }
        }
      ],
      "product_type": "APPOINTMENTS_SERVICE",
      "is_archived": false
    }
  }
}