Manage tags

United States

Canada

Europe

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.

Create a tag

Send a POST request to /v3/merchants/{mId}/tags.
Enter required information—name.
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.

Manage tags

Associate items with a tag

Send a POST request to /v3/merchants/{mId}/tag_items.
Enter required information—tag id and item id.

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

Search tags associated with an item

Send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=tags.
Enter required information—item id.

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 displays tags associated with the item. See Use expandable fields for more information on working with expand parameters in your requests.

Delete item associations

To delete an association between an item and tag:

Send a POST request to /v3/merchants/{mId}/tag_items?delete=true.
Enter required information—tag id and item id.
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}"}}]}'

Search items with a tag

Send a GET request to /v3/merchants/{mId}/tags/{tagId}/items.
Use filters and expansions to indicate your search parameters.

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 search filter are displayed.

See Apply filters and Use expandable fields for more information on working with filter and expand parameters in your requests. See the API reference for more information on available filters and expansions.

Updated 9 months ago