Release NotesAnnouncementsVideosBlog
Guides

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.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Create an item for the inventory

  1. Send a POST request to /v3/merchants/{mId}/items.
  2. 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.
  3. Assign a colorCode to an item using the hex values.
  4. Set the Authorization header as Bearer token type, and enter the test 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"
}

Search items in the inventory

  1. Send a GET request to /v3/merchants/{mId}/items.
  2. Enter the merchantId in the mId field.
  3. Use filters and expansions to indicate the search parameters.
  4. Set the Authorization header as Bearer token type, and enter the test 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—Search 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
        }
    ],
    "href": "http://sandbox.dev.clover.com/v3/merchants/{mId}/items?filter=modifiedTime%3E%3D1611609459000&limit=100"
}

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 appitem stock, merchants can select a Long sleeve crew neck item in color Blue and size Large.

Step 1: Create an item group

  1. Send a POST request to /v3/merchants/{mId}/item_groups.
  2. Enter required information—mid and group name.
  3. Set the Authorization header as Bearer token type, and enter the test 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

  1. Send a POST request to /v3/merchants/{mId}/attributes.
  2. 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

  1. Send a POST request to /v3/merchants/{mId}/attributes/{attributeId}/options.
  2. 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 an options

  1. Send a POST request to /v3/merchants/{mId}/option_items.
  2. 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}"}}]}'

Related topics

Updated 4 days ago