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, set priceWithoutVat 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.

1. Create an item group by sending a POST request to /v3/merchants/{mId}/item_groups. The group name 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"
}

2. Add attributes to the item group by sending a POST request to /v3/merchants/{mId}/attributes. The group id and attribute name 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
    }
}

3. Add attributes options by sending a POST request to /v3/merchants/{mId}/attributes/{attributeId}/options. The attribute id and option name values are required. For example, you can create options like Small, Medium, and Large for the Size 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
    }
}

4. Use the item group id (from step 1) and send a POST 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"}}'

5. Create an association between items and options by sending a POST request to /v3/merchants/{mId}/option_items. The option id and item id 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}"}}]}'