In the REST API, item labels are identified as tags. Merchants use tags or labels for keeping track of these items in reports. With the REST API, you can build custom solutions for creating, managing, and querying tags.

Creating a tag

To create a tag, send a POST request to /v3/merchants/{mId}/tags. The name value is required. You can set the showInReporting value to true for using the tag as a summary label in the Clover Reporting app.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/tags' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
--data '{"name":"Food & beverages","showInReporting":"true"}'

{
    "id": "3VC6H9Y72N1NG" // tag ID
    "name": "Food & beverages"
    "showInReporting": true
}

In response, a unique tag id is generated.

Managing tags

Associating items with a tag

To associate items with a tag, send a POST request to /v3/merchants/{mId}/tag_items. The tag id and item id values are required.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}tag_items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"tag":{"id":"{tagId}"},"item":{"id":"{item1Id}"}},{"tag":{"id":"{tagId}"},"item":{"id":"{item2Id}"}}]}'

Querying tags associated with an item

To query tags associated with an item, send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=tags. The item id value is required.

curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items/{itemId}?expand=tags' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "id": "N2WWSQBTAADZC", // item ID
    "hidden": false,
    "name": "Greek Salad",
    ...
    "tags": { // expansion
        "elements": [
            {
                "id": "3VC6H9Y72N1NG",
                "name": "Food & beverages",
                "showInReporting": true,
                "items": {
                    "elements": [
                        {
                            "id": "N2WWSQBTAADZC"
                        }
                    ]
                }
            }
        ]
    },
    "modifiedTime": 1611643817000
}

In response, the tags expansion shows tags associated with the item. See Expanding fields for more information on working with expand parameters in your requests.

Deleting item associations

To delete an association between an item and tag, send a POST request to /v3/merchants/{mId}/tag_items?delete=true. The tag id and item id values are required. Set the delete value as true.

curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}tag_items?delete=true' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"tag":{"id":"{tagId}"},"item":{"id":"{itemId}"}}]}'

Querying items with a tag

To query items with a tag, send a GET request to /v3/merchants/{mId}/tags/{tagId}/items. You can use filters and expansions to fine-tune responses.

In the following example, the filter parameter is used to filter by price and the expand parameter is used to provide more information about categories and modifier groups.

curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/tags/{tagId}/items?filter=price=1000&expand=categories&expand=modifierGroups' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "elements": [
        {
            "id": "N2WWSQBTAADZC", // item matches filter
            "hidden": false,
            "name": "Greek Salad",
            "price": 1000,
            ...
            "modifierGroups": { // expansion
                "elements": [
                    {
                        "id": "QZ587JT76N80Y",
                        "name": "Salad Add-in",
                        "showByDefault": true,
                        "modifierIds": "S47VGYX913K4T,JRMCKCQK1XCGT",
                        ...
                    }
                ]
            },
            "categories": { // expansion
                "elements": [
                    {
                        "id": "AN7WTGHSKE9XG",
                        "name": "Salads",
                        ...
                    }
                ]
            },
            "modifiedTime": 1611643817000
        }
    ],
    "href": "http://sandbox.dev.clover.com/v3/merchants/{mId}/tags/{tagId}/items?filter=price%3E%3D1000"
}

In response, items that match the filter are displayed.

See Applying filters and Expanding fields for more information on working with filter and expand parameters in your requests. See the API reference for more information about available filters and expansions.