Release NotesAnnouncementsVideosBlog
Guides

Manage tags

United States
Canada
Europe

Merchants use tags or labels for keeping track of these items in reports. With the REST API, you can build custom solutions to create, manage, and query tags.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create a tag

  1. Send a POST request to /v3/merchants/{mId}/tags.
  2. Enter required information—mId and name.
  3. Set the showInReporting value to true for using the tag as a summary label in the Clover Reporting app.
  4. Set the Authorization header as Bearer token type, and enter the test API token.

In response, a unique tag id is generated.

Request and Response example—Create a tag

curl --request POST \
--url 'https://apisandbox.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
}

Manage tags

Associate items with a tag

  1. Send a POST request to /v3/merchants/{mId}/tag_items.
  2. Enter required information—mId, tag id and item id.
  3. Set the Authorization header as Bearer token type, and enter the test API token.

Request example—Associate items with a tag

curl --request POST \
--url 'https://apisandbox.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

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

In response, the tags expansion displays tags associated with the item.

Request and Response example—Search tags associated with an item

curl --request GET \
--url 'https://apisandbox.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
}

See Use expandable fields for more information on working with expand parameters in your requests.

Delete association between an item and tag

  1. Send a POST request to /v3/merchants/{mId}/tag_items?delete=true.
  2. Enter required information—mId, tag id and item id.
  3. Set the delete value as true.

Request example—Delete item associations

curl --request POST \
--url 'https://apisandbox.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

  1. Send a GET request to /v3/merchants/{mId}/tags/{tagId}/items.
  2. Use filters and expansions to indicate your search parameters.
  3. Set the Authorization header as Bearer token type, and enter the test API token.

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. In response, items that match the search filter are displayed.

Request and Response example—Search items with a tag

curl --request GET \
--url 'https://apisandbox.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://apisandbox.dev.clover.com/v3/merchants/{mId}/tags/{tagId}/items?filter=price%3E%3D1000"
}

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.

Related topics

Updated 4 days ago