Release NotesAnnouncementsVideosBlog
Guides

DS-7452-Manage age-restricted items in the Inventory API

United States

The purchase of age-restricted items requires requires age verification and enforcing restrictions at the point-of-sale (POS) and during order fulfillment. This ensures compliance with regulations, prevents underage sales, and mitigates legal risks.

At Clover, the categories for age-restricted items are—Alcohol, Tobacco, Over-the-counter (OTC) products, and Pharmacy products, such as vitamins and supplements. Use the Clover Inventory API to create, view, and update age-restricted item types and minimum age.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Search default age-restricted item types

  1. Send a GET request to /v3/merchants/{mId}/age_restricted/types.
  2. Enter the merchantId in the mId field.
  3. Set the Authorization header as Bearer token type, and enter the test API token.

In response, the age-restricted item types are displayed.

Request and Response example—Search age-restricted item types

curl --location 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/age_restricted/types' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}' \

{
  "ageRestrictedTypes": {
    "elements": [
      {
        "id": "K2PM5DPQGBQEJ",
        "name": "Alcohol"
      },
      {
        "id": "K2PM5DPQGBQEJ",
        "name": "Tobacco"
      },
      {
        "id": "4GJEQRKG7X370",
        "name": "Vitamin & Supplements"
      }
    ]
  }
}

Create age-restricted 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. Set isAgeRestricted to true.
  4. In the ageRestrictedObj object, enter item name and minimumAge.
  5. Assign a colorCode to the item using the hex values.
  6. 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, and the ageRestricted value displays as true.

Request and Response example—Create an age-restricted 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 '{
    "hidden": false,
    "name": "Iron Supplement",
    "price": 1000,
    "priceType": "FIXED",
    "defaultTaxRates": false,
    "cost": 0,
    "isRevenue": true,
    "type": "REGULAR",
    "isAgeRestricted": true,
    "ageRestrictedObj": {
        "id": "4GJEQRKG7X370",
        "name": "Vitamin & Supplements",
        "minimumAge": 18
    }
}'


{
    "id": "016MJS84H6W68",
    "hidden": false,
    "available": true,
    "autoManage": false,
    "name": "Iron Supplement",
    "price": 1000,
    "priceType": "FIXED",
    "defaultTaxRates": false,
    "cost": 0,
    "isRevenue": true,
    "modifiedTime": 1736244719000,
    "deleted": false,
    "isAgeRestricted": true,
    "colorCode": "#FF0080"
}

Search age-restricted items in the inventory

Search for a single age-restricted item

  1. Send a GET request to /v3/merchants/{mId}/items/{itemId}?expand=ageRestricted.
  2. Enter required information—mId and itemId.
  3. Set the Authorization header as Bearer token type, and enter the test API token.

Request and Response example—Search for an age-restricted item

curl --request GET \
--url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/items/{itemId}?expand=ageRestricted' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "id": "F60YZY9NQRDG8",
    "hidden": false,
    "available": true,
    "autoManage": false,
    "name": "Iron Supplement",
    "price": 2200,
    "priceType": "FIXED",
    "defaultTaxRates": false,
    "cost": 0,
    "isRevenue": true,
    "modifiedTime": 1735878400000,
    "deleted": false,
    "isAgeRestricted": true,
    "ageRestrictedObj": {
        "id": "4GJEQRKG7X370",
        "name": "Vitamin & Supplements",
        "minimumAge": 18,
        "items": {
            "elements": [
                {
                    "id": "F60YZY9NQRDG8"
                }
            ]
        }
    }
}

Search for all age-restricted items

  1. Send a GET request to /v3/merchants/{mId}/items?expand=ageRestricted&limit=2&offset=0.
  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.

Request and Response example—Search for all age-restricted items

curl --request GET \
--url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/items?expand=ageRestricted&limit=2&offset=0' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
    "elements": [
        {
            "id": "F60YZY9NQRDG8",
            "hidden": false,
            "available": true,
            "autoManage": false,
            "name": "Iron Supplement",
            "price": 999,
            "priceType": "FIXED",
            "defaultTaxRates": false,
            "cost": 0,
            "isRevenue": true,
            "modifiedTime": 1735878400000,
            "deleted": false,
            "isAgeRestricted": true,
            "ageRestrictedObj": {
                "id": "4GJEQRKG7X370",
                "name": "Vitamin & Supplements",
                "minimumAge": 21,
                "items": {
                    "elements": [
                        {
                            "id": "F60YZY9NQRDG8"
                        }
                    ]
                }
            }
        },
        {
            "id": "WY5SC2THH60KY",
            "hidden": false,
            "available": true,
            "autoManage": false,
            "name": "Cigar",
            "price": 1000,
            "priceType": "FIXED",
            "defaultTaxRates": false,
            "cost": 0,
            "isRevenue": true,
            "modifiedTime": 1735797496000,
            "deleted": false,
            "isAgeRestricted": true,
            "ageRestrictedObj": {
                "id": "DHXH8XT6CHZKA",
                "name": "Tobacco",
                "minimumAge": 25,
                "items": {
                    "elements": [
                        {
                            "id": "WY5SC2THH60KY"
                        }
                    ]
                }
            }
        }
    ],
}

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

Update age-restricted item in the inventory

  1. Send a POST request to /v3/merchants/{mId}/items/{itemId}.
  2. Enter required information—mId and itemId.
  3. Enter information in the field to update, such as price or quantity.
  4. Set the Authorization header as Bearer token type, and enter the test API token.

In response, the updated information is displayed. In the following sample,autoManage is set as true and price and quantity are updated.

Request and Response example—Update age-restricted item

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/items/{itemId}' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --data '{
         "hidden": false,
         "available": true,
         "autoManage": true,
         "name": "Iron Supplements",
         "price": 1500,
         "priceType": "FIXED",
         "defaultTaxRates": false,
         "cost": 0,
         "isRevenue": true,
         "itemStock": {
             "quantity": 60
         },
         "isAgeRestricted": true,
         "ageRestrictedObj": {
             "id": "4GJEQRKG7X370",
             "minimumAge": 18
         }
     }'

{
    "id": "F60YZY9NQRDG8",
    "hidden": false,
    "available": true,
    "autoManage": true,
    "name": "Iron Supplements",
    "price": 1500,
    "priceType": "FIXED",
    "defaultTaxRates": false,
    "cost": 0,
    "isRevenue": true,
    "stockCount": 0,
    "modifiedTime": 1736234226000,
    "deleted": false,
    "isAgeRestricted": true
}

Related topics

Updated 5 days ago