Managing 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.
Creating a tag
To create a tag, send a POST
request to /v3/merchants/{mId}/tags
. The name
value is required. You can 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.
Managing tags
Associating items with a tag
To associate items with a tag, send a POST
request to /v3/merchants/{mId}/tag_items
. The tag id
and item id
values are required.
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}"}}]}'
Querying tags associated with an item
To query tags associated with an item, send a GET
request to /v3/merchants/{mId}/items/{itemId}?expand=tags
. The item id
value is required.
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 shows tags associated with the item. See Expanding fields for more information on working with expand
parameters in your requests.
Deleting item associations
To delete an association between an item and tag, send a POST
request to /v3/merchants/{mId}/tag_items?delete=true
. The tag id
and item id
values are required. 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}"}}]}'
Querying items with a tag
To query items with a tag, send a GET
request to /v3/merchants/{mId}/tags/{tagId}/items
. You can use filters and expansions to fine-tune responses.
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 filter are displayed.
See Applying filters and Expanding fields for more information on working with filter
and expand
parameters in your requests. See the API reference for more information about available filters and expansions.
Updated about 7 hours ago