Manage items and item groups

United States

Canada

Europe

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 Clover REST API, you can build custom solutions to create and manage items, stock quantities, and item group. See the API reference for more information on the complete list of values you can set.

Manage items and item groups on the Merchant Dashboard

Merchants can manage items and item groups on the Merchant Dashboard. See Clover Help to Build your item list.

Manage item availability with Clover REST APIs

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create an item for the inventory

Send a POST request to /v3/merchants/{mId}/items.
Enter required information—mId, name and price (in cents).
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.
Assign a colorCode to an item using the hex values.
Set the Authorization header as Bearer token type, and enter the merchant's API token.

In response, a unique item id is generated. The hidden, priceType, and isRevenue values are set by default.

Request and Response example—Create an item

curl --request POST \
--url 'https://apisandbox.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"}'

{
    "id": "9J1F7WW503CZW", // item ID
    "hidden": false,
    "name": "Caesar Salad",
    "price": 1200,
    "priceType": "FIXED",
    "defaultTaxRates": true,
    "isRevenue": true,
    "modifiedTime": 1611609459000,
    "colorCode": "#FF0080"
}

View items in the inventory

Send a GET request to /v3/merchants/{mId}/items.
Enter the merchantId in the mId field.
Use filters and expansions to indicate the search parameters.
Set the Authorization header as Bearer token type, and enter the merchant's API token.

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.

In response, items that match the search filter are displayed. The itemStock expansion displays the quantity of each listed item.

Request and Response example—View items in the inventory

curl --request GET \
--url 'https://apisandbox.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
        }
    ]
}

See Apply filters and Use expandable fields for more information on working with filter and expand parameters in your requests.

Create 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) and size (Small, Medium, Large). In the Clover Register app item stock, merchants can select a Long sleeve crew neck item in color Blue and size Large.

Step 1: Create an item group

Send a POST request to /v3/merchants/{mId}/item_groups.
Enter required information—mid and item group name.
Set the Authorization header as Bearer token type, and enter the merchant's API token.

Request and Response example—Create an item group

curl --request POST \
--url 'https://apisandbox.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"
}

Step 2: Add attributes to the item group

Send a POST request to /v3/merchants/{mId}/attributes.
Enter required information—mId, group id and attribute name.

Request and Response example—Add attributes to the item group

curl --request POST \
--url 'https://apisandbox.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
    }
}

Step 3: Add attribute options

Send a POST request to /v3/merchants/{mId}/attributes/{attributeId}/options.
Enter required information—mId, attribute id and option name. For example, you can create options like Small, Medium, and Large for the Size attribute.

Request and Response example—Add attribute options

curl --request POST \
--url 'https://apisandbox.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
    }
}

Step 4: Create an item and associate it with an item group ID

Use the mId and item group id from step 1:

To create an item with variants—Send a POST request to /v3/merchants/{mId}/items.
To update an item with variants—Send a POST request to /v3/merchants/{mId}/items/{itemId}

curl --request POST \
--url 'https://apisandbox.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"}}'

Step 5: Create an association between items and options

Send a POST request to /v3/merchants/{mId}/option_items.
Enter required information—mId, option id and item id.

curl --request POST \
--url 'https://apisandbox.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}"}}]}'