Manage tags
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 totrue
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 itemid
.
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 itemid
. - Set the
delete
value astrue
.
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