Release NotesAnnouncementsBlogFAQSupport
Guides

Manage age-restricted items in the Orders API

North America—United States and Canada

The purchase of age-restricted items 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 Orders API to create, view, and update orders with age-restricted item types and minimum age.

Create an order with age-restricted items

The atomic order endpoint creates a complete order, including line items, modifiers, discounts, and service charges, with a single API call. Before you create an atomic order and calculate the order totals, you need to create an inventory item and, if needed, add modifiers and discounts and set up tax rates and rules. To create an order with age-restricted items and make sure the order is accurately built with all necessary checks and calculations, complete the following:

Step 1: Build the order checkout—Use the /atomic_order/checkouts endpoint to build the order. This step calculates totals, taxes, discounts, and service charges and displays summary information. It helps ensure that all necessary details are captured and the order is correctly configured before it is finalized.

Step 2: Create the order—After building the order checkout, use the /atomic_order/orders endpoint to create the actual order record. This step finalizes the order and makes it ready for further actions like payment.

Prerequisites

  1. Generate a merchant-specific API token.
  2. Use the Create an inventory item endpoint to get the lineItem Id with the item price.
  3. Use the Create an order type for a merchant to get theorderType Id.

Step 1: Build an order checkout

Use the Checkout an atomic order endpoint to build an order, along with the order total, tax, discount, and service charge, and then display the summary information. This endpoint does not create an order but displays the current state of the order to the customer.

  1. Send a POST request to /v3/merchants/{mId}/atomic_order/checkouts.
  2. Enter required information—mId, lineItem Id and item price .
  3. Enter optional information—orderType Id.
  4. Set the Authorization header as Bearer token type, and enter the merchant's API token.

The response includes order cart information, the order total, and taxes.

Request and Response example—Build an order checkout

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --data '{
         "customer": {
               "customerDisplayName": "Chris Doe",
               "customerPhoneNumber": "+1 123 555 1234",
               "customerEmailAddress": "[email protected]",
               "customerFirstName": "Chris",
               "customerLastName": "Doe"
           },
           "serviceType": "Delivery",
           "orderCart": {
               "lineItems": {
                   "elements": [
                       {
                           "item": {
                               "id": "6B3KZD4DACPYM"
                           },
                           "unitQty": 1
                       }
                   ]
               }
           },
           "onlineOrder": {
               "note": "sample note",
               "receiptId": "sample_receipt_ID",
               "onlineOrderId": "123",
               "orderState": "CREATED"
           }
        }'

{
   "orderCart": {
       "discounts": {
           "elements": []
       },
       "lineItems": {
           "elements": [
               {
                   "item": {
                       "id": "6B3KZD4DACPYM"
                   },
                   "name": "Alcoholic Item",
                   "price": 100,
                   "discounts": {
                       "elements": []
                   },
                   "exchanged": false,
                   "modifications": {
                       "elements": []
                   },
                   "refunded": false,
                   "isRevenue": true,
                   "taxRates": {
                       "elements": [
                           {
                               "id": "SPW2STAQA4RVM",
                               "name": "Sales Tax",
                               "rate": 900000,
                               "isDefault": true
                           }
                       ]
                   },
                   "isOrderFee": false,
                   "type": "REGULAR",
                   "isAgeRestricted": true,
                   "ageRestrictedType": "Alcohol",
                   "minimumAge": 21
               }
           ]
       },
       "merchant": {}
   },
   "total": 109,
   "subtotal": 100,
   "totalTaxAmount": 9,
   "taxSummaries": {
       "elements": [
           {
               "id": "SPW2STAQA4RVM",
               "name": "Sales Tax",
               "amount": 9,
               "rate": 900000
           }
       ]
   },
   "isVat": false
}

Step 2: Create an atomic order

Use the Create an atomic order endpoint to create an order and calculate the order totals. Merchants can view the order on the Merchant Dashboard and devices.

  1. Send a POST request to /v3/merchants/{mId}/atomic_order/orders.
    Note: Use the request body from Step 1: Build an order checkout.
  2. Enter required information—mId, lineItem id, item unitQty and orderType id.
    Note: unitQty is required only if the item is priced by the quantity of a unit.
  3. Set the Authorization header as Bearer token type, and enter the merchant's API token.

The response includes information about the order cart, the order total, and taxes. For more information, see Calculate Order Totals.

Request and Response example—Create an order

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/orders' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --data '{
         "customer": {
             "customerDisplayName": "Chris Doe",
             "customerPhoneNumber": "+1 123 555 1235",
             "customerEmailAddress": "[email protected]",
             "customerFirstName": "Chris",
             "customerLastName": "Doe"
         },
         "orderCart": {
             "lineItems": {
                 "elements": [
                     {
                         "item": {
                             "id": "6B3KZD4DACPYM"
                         },
                         "modifications": {
                             "elements": []
                         },
                         "discounts": {
                             "elements": []
                         },
                         "unitQty": 1
                     }              
                 ]
             },
             "discounts": {
                 "elements": []
             },
             "groupLineItems": true,
             "onlineOrder": {
                 "note": "sample note",
                 "receiptId": "sample_receipt_ID",
                 "onlineOrderId": "123",
                 "orderState": "CREATED"
             }
         },
         "trackOnlineInfo": true,
         "serviceType": "PICKUP"
      } '

{
   "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{OrderId}",
   "id": "5CQ79VK9DZWVR",
   "currency": "USD",
   "employee": {
       "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/employees/{employeeID}",
       "id": "HXJ8JMMVEV5Z2",
       "name": "John Smith",
       "role": "ADMIN",
       "orders": {
           "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/employees/{employeeID}/orders"
       }
   },
   "total": 109,
   "taxRemoved": false,
   "isVat": false,
   "state": "OPEN",
   "manualTransaction": false,
   "groupLineItems": true,
   "testMode": false,
   "createdTime": 1736239864000,
   "clientCreatedTime": 1736239864000,
   "modifiedTime": 1736239863000,
   "lineItems": {
       "elements": [
           {
               "id": "JGXQPPGFFXYPG",
               "orderRef": {
                   "id": "5CQ79VK9DZWVR"
               },
               "item": {
                   "id": "6B3KZD4DACPYM"
               },
               "name": "Alcoholic Item",
               "price": 100,
               "printed": false,
               "createdTime": 1736239864000,
               "orderClientCreatedTime": 1736239864000,
               "exchanged": false,
               "refunded": false,
               "isRevenue": true,
               "taxRates": {
                   "elements": [
                       {
                           "id": "SPW2STAQA4RVM",
                           "lineItemRef": {
                               "id": "JGXQPPGFFXYPG"
                           },
                           "name": "Sales Tax",
                           "rate": 900000,
                           "isDefault": true
                       }
                   ]
               },
               "isOrderFee": false,
               "type": "REGULAR",
               "isAgeRestricted": true,
               "ageRestrictedType": "Alcohol",
               "minimumAge": 21
           }
       ]
   }
}

Work with age-restricted line item for an order

Each line item indicates a single inventory item that is purchased as part of the order. You can use an inventory itemID to create a line item for a custom order.

Prerequisites

  1. Generate a merchant-specific API token.
  2. Create an inventory item.
  3. Create an order.

Create age-restricted line item for an order

  1. Send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items\.
  2. Enter required information—mId, orderID, and itemID.
  3. Set the Authorization header as Bearer token type, and enter the merchant's API token.

The response generates a unique item line item id. Details of the age-restricted item are displayed based on the inventory itemID.

Request and Response example—Create an age-restricted line 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 '{
     "orderRef": {
         "id": "TJP5PWA21NHHP"
     },
     "item": {
         "id": "6B3KZD4DACPYM"
     },
     "unitQty": 1
  }
  '

{
   "id": "GSN0T3EA3QFTM",
   "orderRef": {
       "id": "TJP5PWA21NHHP"
   },
   "item": {
       "id": "6B3KZD4DACPYM"
   },
   "name": "Alcoholic Item",
   "price": 100,
   "printed": false,
   "createdTime": 1736244876000,
   "orderClientCreatedTime": 1736235433000,
   "exchanged": false,
   "refunded": false,
   "isRevenue": true,
   "isOrderFee": false,
   "type": "REGULAR",
   "isAgeRestricted": true,
   "ageRestrictedType": "Alcohol",
   "minimumAge": 21
}

Bulk create multiple line items for an order

  1. Send a POST request to v3/merchants/{mId}/orders/{orderId}/bulk_line_items.
  2. Enter required information—mId and orderID.
  3. Enter information in the field to update, such as price or quantity or set ageRestricted value to either true of false for each item.
  4. Set the Authorization header as Bearer token type, and enter the merchant's API token.

In response, the updated values for the items are displayed.

Request and Response example—Bulk create age-restricted item

In the following example, two existing items with age-restricted values are updated.

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/bulk_line_items' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "items": [
      {
        "orderRef": {
          "id": "TJP5PWA21NHHP"
        },
        "unitQty": 1,
        "price": 100,
        "isAgeRestricted": true,
        "ageRestrictedType": "Alcohol",
        "minimumAge": 18
      },
      {
        "orderRef": {
          "id": "RKP874E8KP9Q8"
        },
        "unitQty": 1,
        "price": 200,
        "isAgeRestricted": true,
        "ageRestrictedType": "Tobacco",
        "minimumAge": 21
      },
      {
        "orderRef": {
          "id": "RKP874E8KP9Q8"
        },
        "unitQty": 1,
        "price": 300,
        "isAgeRestricted": true,
        "ageRestrictedType": "OTC drugs",
        "minimumAge": 25
      }
    ]
  }'


[
   {
       "id": "J1D2AEJJQC41Y",
       "price": 200,
       "unitQty": 1,
       "printed": false,
       "createdTime": 1736245314000,
       "orderClientCreatedTime": 1736235433000,
       "exchanged": false,
       "refunded": false,
       "isRevenue": true,
       "isOrderFee": false,
       "type": "REGULAR",
       "isAgeRestricted": true,
       "ageRestrictedType": "Tobacco",
       "minimumAge": 18
   },
   {
       "id": "MT182Q1Z422YM",
       "price": 100,
       "unitQty": 1,
       "printed": false,
       "createdTime": 1736245314000,
       "orderClientCreatedTime": 1736235433000,
       "exchanged": false,
       "refunded": false,
       "isRevenue": true,
       "isOrderFee": false,
       "type": "REGULAR",
       "isAgeRestricted": true,
       "ageRestrictedType": "Alcohol",
       "minimumAge": 21
   },
   {
       "id": "93B829CRBV7FT",
       "price": 300,
       "unitQty": 1,
       "printed": false,
       "createdTime": 1736245314000,
       "orderClientCreatedTime": 1736235433000,
       "exchanged": false,
       "refunded": false,
       "isRevenue": true,
       "isOrderFee": false,
       "type": "REGULAR",
       "isAgeRestricted": true,
       "ageRestrictedType": "OTC drugs",
       "minimumAge": 25
   }
]

View age-restricted line items in an order

Prerequisites

  1. Generate a merchant-specific API token.
  2. Create an order.
  3. Create a line item or multiple line items.

View an age-restricted line item

  1. Send a GET request to /v3/merchants/{mId}orders/{orderId}/line_items/{lineItemId}.
  2. Enter required information—mId, orderID and lineItemId.
  3. Set the Authorization header as Bearer token type, and enter the merchant's API token.

Request and Response example—View an age-restricted line item

curl --request GET \
--url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}orders/{orderId}/line_items/{lineItemId}' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
   "id": "GSN0T3EA3QFTM",
   "orderRef": {
       "id": "TJP5PWA21NHHP"
   },
   "item": {
       "id": "6B3KZD4DACPYM"
   },
   "name": "Alcoholic Item",
   "price": 100,
   "printed": false,
   "createdTime": 1736244876000,
   "orderClientCreatedTime": 1736235433000,
   "exchanged": false,
   "refunded": false,
   "isRevenue": true,
   "isOrderFee": false,
   "type": "REGULAR",
   "isAgeRestricted": true,
   "ageRestrictedType": "Alcohol",
   "minimumAge": 21
}

View all age-restricted line items

  1. Send a GET request to /v3/merchants/{mId}/orders/{orderId}/line_items.
  2. Enter required information—mId and orderID.
  3. Use filters and expansions to indicate the search parameters.
  4. Set the Authorization header as Bearer token type, and enter the merchant's API token.

Request and Response example—View all age-restricted line items

curl --request GET \
--url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
   "elements": [
       {
           "id": "M94S2Y39A7A9P",
           "orderRef": {
               "id": "TJP5PWA21NHHP"
           },
           "item": {
               "id": "6B3KZD4DACPYM"
           },
           "name": "Alcoholic Item",
           "price": 100,
           "printed": false,
           "createdTime": 1736248688000,
           "orderClientCreatedTime": 1736235433000,
           "exchanged": false,
           "refunded": false,
           "isRevenue": true,
           "isOrderFee": false,
           "type": "REGULAR",
           "isAgeRestricted": true,
           "ageRestrictedType": "Alcohol",
           "minimumAge": 21
       },
       {
           "id": "93B829CRBV7FT",
           "orderRef": {
               "id": "TJP5PWA21NHHP"
           },
           "name": "Chelated Magnesium",
           "price": 300,
           "unitQty": 1,
           "printed": false,
           "createdTime": 1736245314000,
           "orderClientCreatedTime": 1736235433000,
           "exchanged": false,
           "refunded": false,
           "isRevenue": true,
           "isOrderFee": false,
           "type": "REGULAR",
           "isAgeRestricted": true,
           "ageRestrictedType": "OTC drugs",
           "minimumAge": 23
       },

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

Related topics

Updated about 10 hours ago