Manage items and item groups
Each item in the merchant inventory is represented by an items
object. Clover merchants create and manage inventory items with the Clover Inventory app.
With the REST API, you can build custom solutions for creating and managing items, stock quantities, and item groups.
Creating an item
To create an inventory item, send a POST
request to /v3/merchants/{mId}/items
. The name
and price
(in cents) values are required. To assign a colorCode to an item, use the hex values.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"name":"Caesar Salad","price":1200,”colorCode”:#FF0080”}'
NOTE
All money amount values are represented in cents. For example, $20.99 is represented as an amount value of
2099
.For merchants that use value-added tax (VAT), the
price
value includes tax. In this case, setpriceWithoutVat
as the base price without VAT.
{
"id": "9J1F7WW503CZW", // item ID
"hidden": false,
"name": "Caesar Salad",
"price": 1200,
"priceType": "FIXED",
"defaultTaxRates": true,
"isRevenue": true,
"modifiedTime": 1611609459000
"colorCode": "#FF0080"
}
In response, a unique item id
is generated. The hidden
, priceType
, and isRevenue
values are set by default. See the API reference for more information on the complete list of values you can set.
Updating item stock
To update the stock of an item, send a POST
request to /v3/merchants/{mId}/item_stocks/{itemId}
. The quantity
value is required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/item_stocks/{itemId}' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"item":"9J1F7WW503CZW","quantity":4,”colorCode”:#FF0080”}'
In response, the quantity
value is updated.
Under Inventory > Setup on the merchant dashboard, merchants can update settings for the Clover Inventory app to track and update the stock of items. To see the related merchant properties, send a GET
request to /v3/merchants/{mId}/properties
.
In response, the trackStock
value specifies whether the Clover Inventory app is used to track item stock count. The updateStock
value specifies whether the Clover Inventory app is used to automatically update item stock count.
Querying items in the inventory
To query items in the merchant inventory, send a GET
request to /v3/merchants/{mId}/items
. You can use filters and expansions to fine-tune responses.
In the following example, the filter
parameter is used to filter by modified time and the expand
parameter is used to provide more information about item stock.
curl --request GET \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items?filter=modifiedTime>={unix_time}&expand=itemStock' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'
{
"elements": [
{
"id": "N2WWSQBTAADZC", // item matches filter
"hidden": false,
"name": "Greek Salad",
...
"itemStock": { // expansion
"item": {
"id": "N2WWSQBTAADZC"
},
...
"quantity": 5.0,
"modifiedTime": 1611643868000
},
"modifiedTime": 1611643817000
}
],
"href": "http://sandbox.dev.clover.com/v3/merchants/{mId}/items?filter=modifiedTime%3E%3D1611609459000&limit=100"
}
In response, items that match the filter are displayed. The itemStock
expansion shows the quantity
of each listed item.
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.
Creating an item group for item variants
Merchants use item groups to manage variants of a single item.
For example, in a T-shirt item group, you can create variants for color (Red, Blue, Green, etc) and size (Small, Medium, Large, etc). In the Clover Register app, merchants can select a Long sleeve crew neck
item in color Blue
and size Large
.
- Create an item group by sending a
POST
request to/v3/merchants/{mId}/item_groups
. The groupname
value is required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/item_groups' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"name":"T-shirt"}'
{
"id": "FBAAX81VXHDP0", // item group ID
"name": "T-shirt"
}
- Add attributes to the item group by sending a
POST
request to/v3/merchants/{mId}/attributes
. The groupid
and attributename
values are required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/attributes' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"itemGroup":{"id":"{itemGroupId}"},"name":"Size"}'
{
"id": "12XGR3RNHG8FW", // attribute ID
"name": "Size",
"itemGroup": {
"id": "FBAAX81VXHDP0" // group ID
}
}
- Add attributes options by sending a
POST
request to/v3/merchants/{mId}/attributes/{attributeId}/options
. The attributeid
and optionname
values are required. For example, you can create options likeSmall
,Medium
, andLarge
for theSize
attribute.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/attributes/{attributeId}/options' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"name":"Large"}'
{
"id": "V5EKKX8XDA05M", // option ID
"name": "Large",
"attribute": {
"id": "12XGR3RNHG8FW" // attribute ID
}
}
- Use the item group
id
(from step 1) and send aPOST
request to create (/v3/merchants/{mId}/items
) or update (/v3/merchants/{mId}/items/{itemId}
) an item with variants.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"name":"Long sleeve crew neck","price":3000,"itemGroup":{"id":"FBAAX81VXHDP0"}}'
- Create an association between items and options by sending a
POST
request to/v3/merchants/{mId}/option_items
. The optionid
and itemid
values are required.
curl --request POST \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/option_items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{"elements":[{"option":{"id":"{optionId}"},"item":{"id":"{item1Id}"}},{"option":{"id":"{optionId}"},"item":{"id":"{item2Id}"}}]}'
Updated 2 months ago