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.

Archive a catalog item
Retrieve an archived item
Search for archived items
Unarchive an item

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

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
    }
  }'

Link to section
Response: archive an item

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
    }
  }
}

Link to section
Retrieve an archived item

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.

Link to section
Request: 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

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'

Link to section
Response: retrieve an archived item

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

Link to section
Search for archived items

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.

Link to section
Request: search for archived items

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"
  }'

Link to section
Response: search for archived items

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"
  ]
}

Link to section
Unarchive an item

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.

Link to section
Request: unarchive an item

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
    }
  }'

Link to section
Response: unarchive an item

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
    }
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Archive Catalog Items and Manage Archived Items

On this page

Link to section
Archive a catalog item

Link to section
Request: archive an item

Link to section
Response: archive an item

Link to section
Retrieve an archived item

Link to section
Request: retrieve an archived item

Link to section
Response: retrieve an archived item

Link to section
Search for archived items

Link to section
Request: search for archived items

Link to section
Response: search for archived items

Link to section
Unarchive an item

Link to section
Request: unarchive an item

Link to section
Response: unarchive an item

On this page

Docs

Archive Catalog Items and Manage Archived Items

On this page

Link to section Archive a catalog item

Link to section Request: archive an item

Link to section Response: archive an item

Link to section Retrieve an archived item

Link to section Request: retrieve an archived item

Link to section Response: retrieve an archived item

Link to section Search for archived items

Link to section Request: search for archived items

Link to section Response: search for archived items

Link to section Unarchive an item

Link to section Request: unarchive an item

Link to section Response: unarchive an item

On this page

Link to section
Archive a catalog item

Link to section
Request: archive an item

Link to section
Response: archive an item

Link to section
Retrieve an archived item

Link to section
Request: retrieve an archived item

Link to section
Response: retrieve an archived item

Link to section
Search for archived items

Link to section
Request: search for archived items

Link to section
Response: search for archived items

Link to section
Unarchive an item

Link to section
Request: unarchive an item

Link to section
Response: unarchive an item