Release NotesAnnouncementsBlogFAQSupport
Guides

Manage tags

United States
Canada
Europe

In the Clover REST API, item labels are identified as tags. Merchants use tags to categorize items for tracking and reporting purposes. With the REST API, you can build custom solutions to create, manage, and query items based on their 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 mecrhant's 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}"}}]}'

View 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.
  3. Set the Authorization header as Bearer token type, and enter the mecrhant's API token.

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

Request and Response example—View 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}"}}]}'

View 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—View 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.

Related topics

Updated 6 months ago