Manage tags
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
- Send a POST request to
/v3/merchants/{mId}/tags
. - Enter required information—
mId
andname
. - Set the
showInReporting
value totrue
for using the tag as a summary label in the Clover Reporting app. - 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
- Send a POST request to
/v3/merchants/{mId}/tag_items
. - Enter required information—
mId
, tagid
and itemid
. - 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
- Send a GET request to
/v3/merchants/{mId}/items/{itemId}?expand=tags
. - Enter required information—
mId
and itemid
.
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
- Send a POST request to
/v3/merchants/{mId}/tag_items?delete=true
. - Enter required information—
mId
, tagid
and itemid
. - Set the
delete
value astrue
.
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
- Send a GET request to
/v3/merchants/{mId}/tags/{tagId}/items
. - Use filters and expansions to indicate your search parameters.
- 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
- Work with inventory
- Create a tag endpoint
- Get tags for a single item endpoint
- Get all items for a single tag endpoint
- Create or delete associations between tags and items endpoint
Updated 4 days ago