Orders data

Use the Atomic Orders API to create a Clover Order—calculate totals and taxes and generate summary information that you can display when a customer is building an order. Use these features to build an ordering solution for both in-store and online orders.

The atomic_order endpoints provide the following improvements to the Orders API:

  • Compute order totals and taxes while building the order without creating an actual order.
  • Create the order with line-items, modifiers, discounts, and service charges with a single API call and lessen the probability of running into rate limits.


Before you use the API to create or summarize the orders, an inventory must exist in the Clover environment. You can use our Inventory API to create items, modifiers, discounts, and set up tax rates and rules.


  • Only supports inventory items in the Clover Inventory App.
  • If you need to create an order with custom or ad-hoc line items, use the v3/orders API to create the order and create a new line item/v3/merchants/{mId}/orders/{orderId}/line_items or add a line item or line items/v3/merchants/{mId}/orders/{orderId}/bulk_line_items to the order.

Atomic order requests

An atomic_order request includes the following fields.

orderCartOrder cart that contains order data including line items, line item modifiers, discounts, and taxes.
lineItemsLine items associated with an order, such as coffee and muffin. You can use a modifier to indicate the size of the coffee (small or large).
discountAmount or a percentage of discount applied to the order.
orderTypeClassification of the order as different order types, such as online, delivery, pick-up, or dine-in. Each order type is specific to the merchant.

Create an order type before you create the order. To create an order type, send a POST request to /v3/merchants/{mId}/order_type.
serviceChargeOptional service charge or gratuity tip applied to the order.

Order creation flow

To complete an order, you must have the prerequisite information.


  • order type id
  • inventory item id
  • modifier id, if any
  • discounts, if any
  • tax rate id

Requirements for using modifiers

Modifiers are optional, but if you are using them, note these requirements:

  • If you do not pass a modifier.id, other modifier fields are ignored.
  • You must pass both name and amount values.
  • The name and the amount passed override the defaults set on the modification that are set up in the merchant's inventory.


Multiple endpoints are needed to create the order:

  • The checkouts endpoint opens a cart to build the order. Prerequisite information is captured here.
  • The orders endpoint posts the order record.
  • The pay endpoint passes the payment information.


  • Use /atomic_order/checkouts to build the order.
  • Call /atomic_order/orders to create the order.
  • Call v1/orders/{orderId}/pay of the Ecommerce API to automatically charge the total order amount and to include a tip.

Build an order summary

  • Use the /atomic_order/checkouts endpoint to build an order and calculate totals, taxes, discounts, service charges, and display summary information. The checkouts endpoint does not create an order and merchants cannot view the orders on their Web Dashboard or devices.
  • Use /checkouts endpoint as the order is being built, to display the current state of the order to the customer. To use the /checkouts endpoint, build an orderCart object including a discount and send it as the body of a POST request to the /v3/merchants/{mId}/atomic_order/checkouts endpoint.
curl --location --request POST 'https://sandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orderCart": {
    "orderType": {
      "id": "{existingCloverOrderTypeUUID}"
    "lineItems": [
        "item": {
          "id": "{existingCloverInventoryItemUUID}"
        "modifications": [
            "amount": 10,
            "modifier": {
              "id": "{existingCloverModifierUUID}"
            "name": "Coffee Sizes"
    "discounts": [
        "name": "$2 off",
        "amount": -200

Create an order

Use the /atomic_order/orders endpoint to create an order and calculate the order totals. The merchants can view the orders on their Web Dashboards and devices. If you are using the /atomic_orders/checkouts endpoint to calculate the order total, taxes, and discounts, pass the same request body to the /orders endpoint to create the order.

To create a new order, build an orderCart object and send it as the body of a POST request to the /v3/merchants/{mId}/atomic_order/orders endpoint.

curl --request POST --url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/orders' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' 
--data-raw '{
  "orderCart": {
    "lineItems": [
        "item": {
          "id": "{existingCloverInventoryItemUUID}"



If you make amount adjustments to the order after it is created, you must manually recalculate and update the total by sending a POST request to the /v3/merchants/{mId}/orders/{orderId} endpoint.

Pay for order

To take a payment and include a tip, send a POST request to the v1/orders/{orderId}/pay endpoint using the baseUrl of https://scl-sandbox.dev.clover.com.



The baseUrl https://scl-sandbox.dev.clover.com is only for testing and not for production. See documentation for more information.

When paying for an order, set the delete_order_on_failure parameter to "true" as part of the metadata. This automatically delete a an order if the payment fails, such as due to fraud.

See the Ecommerce API endpoint for more information.

Handle 400 Bad Request errors

The JSON response consists of two properties—message and details. If the server detects a specific error, the details value returns the UUID of the failed element.

Consider a scenario where the server detects that an order-related element does not exist. The JSON includes the following message: item_does_not_exist.

The following is a sample of the error response including the UUID.

response: {"message": "item_does_not_exist", "details": "8NR072YTBZ52W"}

To fix this error, remove or replace the missing or invalid element from your request. For the following message values, the details value is the unrecognized UUID:

  • item_does_not_exist
  • service_charge_does_not_exist
  • invalid_modifier

For the following message values, the details value is a human-readable error message:

  • cart_is_empty_or_missing
  • bad_request
  • order_uuid_is_null
  • insufficient_customer_info
  • invalid_discount_attribute: The details value includes the incorrect attribute.

See the API Reference for more information on using Atomic APIs: