---
updatedAt: 2026-06-17T21:34:47.000Z
agentTools:
  projectIndex: https://docs.clover.com/dev/llms.txt
---

# Create an atomic order

Use a single Clover API call to build an order cart, check an order, and the create the order record for payment.

[block:html]
{
  "html": "<!-- ***Content shared with OLO Partner docs***\n> This page has content shared with the partner docs. If you update this page, \ncheck if the same change applies to the partner docs.\n> 2025-Jan-20 Created a new topic to properly explain atomic order and use the\nManage orders data page as an Index page.\n> This page needs to be reviewed by an SME for the content relavancy.\n--> "
}
[/block]

[block:html]
{
  "html": "<div class=\"container-top\"> \n  <!--North America-US and Canada-->\n  <div class=\"container-reg\">\n    <div class=\"pill-reg\">\n      <div class=\"label-reg\">North America—United States and Canada</div>\n    </div>\n  </div>\n</div>\n<!--syles in global css-->"
}
[/block]

<br />

[block:html]
{
  "html": "<!--Add a top nav throughout the pilot doc content (v2.2: grayscale, no overlap)-->\n<div><!--div set-->\n <div class=\"top-container\">\n    <div class=\"topnav\">\n      <a href=\"https://docs.clover.com/dev/docs/working-with-orders\">Manage orders data</a>\n      <a href=\"https://docs.clover.com/dev/docs/generate-a-test-api-token#generate-a-merchant-specific-test-api-token-in-sandbox\">Generate test API token</a>\n       <a href=\"https://docs.clover.com/dev/reference/ordercheckoutatomicorder\">Checkout an atomic order endpoint</a>\n      <a href=\"https://docs.clover.com/dev/reference/ordercreateatomicorder\">Create an atomic order endpoint</a>\n      \n    </div><!--end topnav-->\n  </div><!--end top-container-->\n</div>\n\n<!--css-->\n<style>\n/* Add tight spacing to the the top navigation menu div */\n.top-container {\n  top: -33px;\n  position: relative;\n  margin-bottom: -18px;\n  width: 100%;\n}\n/* Add a background color to the top navigation */\n.topnav {\n  font-family: Altform, sans-serif;\n  background-color: #5D5D5D;\n  overflow: hidden;\n  margin-top: -10px;\n  }\n\n/* Style the links inside the navigation bar */\n.topnav a {\n  font-family: Altform, sans-serif;\n  float: left;\n  color: #f2f2f2;\n  text-align: center;\n  padding: 8px 10px;\n  text-decoration: none;\n  font-size: .9em;\n}\n\n/* Change the color of links on hover */\n.topnav a:hover {\n  background-color: #D8D8D8;\n  color: black;\n}\n\n/* Add a color to the active/current link */\n.topnav a.active {\n  background-color: #5D5D5D;\n  color: white;\n}\n</style>"
}
[/block]

To create an atomic order, make a single API call to build an order cart and then complete the order. An atomic order includes components such as line items, modifiers, discounts, and service charges. It can also include non-Clover inventory items and ad hoc items.

Use the [Checkout an atomic order](https://docs.clover.com/dev/reference/ordercheckoutatomicorder) endpoint to compute order totals and taxes while building the order without finalizing it. Once you are ready, use the [Create an atomic order](https://docs.clover.com/dev/reference/ordercreateatomicorder) endpoint to create the order. The atomic order endpoints support both in-store and online orders, providing a comprehensive solution that ensures accurate totals and tax calculations in one seamless process.

> 📘 NOTE:
>
> If you need to create an order using multiple API calls, use the [ Create custom orders](https://docs.clover.com/reference/ordercreateorder) endpoint. See the [Create custom orders](https://docs.clover.com/docs/creating-custom-orders) tutorial to learn more.

# Benefits

The key benefits of creating atomic orders are:

* **Efficiency**—Reduces the complexity of managing multiple API calls.
* **Accuracy**—Ensures that all order details are captured and calculated correctly in one step.
* **Convenience**—Ideal for creating standard orders quickly and efficiently.

# Workflow

The three-step workflow to create an atomic order:

**Step 1: Build an order checkout**—Use the [Checkout an atomic order](https://docs.clover.com/dev/reference/ordercheckoutatomicorder) endpoint to open a cart, build the order, and calculate totals, taxes, discounts, service charges, and display summary information. This endpoint does not create an order but displays the current state of the order to the customer. The order does not display on the Merchant Dashboard and devices.

**Step 2: Create the order record**—Use the [Create an atomic order](https://docs.clover.com/dev/reference/ordercreateatomicorder) endpoint to create the order record.

**Step 3: Pay for an order**—Use the [Pay for an order](https://docs.clover.com/dev/reference/postordersidpay) endpoint of the Ecommerce API to automatically charge the total order amount and to include a tip.

# Prerequisites

* [Create merchant-specific API token in sandbox](https://docs.clover.com/dev/docs/gdp-create-merchant-specific-api-token).
* Use the [Create an inventory item](https://docs.clover.com/dev/reference/inventorycreateitem) endpoint to get the `lineItem` Id.
* Use the [Create an order type for a merchant](https://docs.clover.com/dev/reference/merchantcreateordertype) endpoint to get the`orderType` Id. An order type is a classification of the order, such as online, delivery, pick-up, or dine-in. Each order type is specific to the merchant. The following identifiers are needed if modifiers, discounts, and taxes are applicable—`modId`,`discountId`,  and `taxId`.
* Requirements for modifiers—Modifiers are optional, but if you use them, note the following requirements:
  * If you do not pass a `modId`, other modifier fields are ignored.
  * If you pass both `name` and `amount` values, these override default modifiers set in the merchant's inventory.

***

# Create an atomic order

> 👍 TIP
>
> Use the Recipes in the Learn how section. **[Recipes](https://docs.clover.com/recipes)** provide response details and are a great option if you do not have an OAuth token.

## Step 1: Build an order checkout—Platform API

1. Send a POST request to the `/atomic_order/checkouts` endpoint.
2. Enter information for the `orderCart` object, including line items, modifiers, discounts, and any other relevant details.
3. Enter required information—`mId`, `lineItem` id, and `orderType` id.
4. Set the Authorization header as Bearer token type, and enter the test API token.

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

### Request and Response example—Build an order checkout

```curl Request
curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
     "orderCart": {
          "lineItems": [
               {
                    "item": {
                         "id": "MXHW24RNRHW16"
                    },
                    "discounts": [
                         {
                              "name": "$2 Tuesday",
                              "amount": -200
                         }
                    ],
                    "modifications": [
                         {
                              "modifier": {
                                   "available": "true",
                                   "id": "4KAZY3PXJQ4P0",
                                   "name": "Whip cream"
                              },
                              "amount": 25
                         }
                    ]
               }
          ],
          
     }
}
'
```
```python Response
{
  "id": "CHK1234567890",
  "orderCart": {
    "lineItems": [
      {
        "id": "LI1234567890",
        "item": {
          "id": "MXHW24RNRHW16",
          "name": "Item Name"
        },
        "price": 1000,
        "discounts": [
          {
            "id": "DIS1234567890",
            "name": "$2 Tuesday",
            "amount": -200
          }
        ],
        "modifications": [
          {
            "id": "MOD1234567890",
            "modifier": {
              "id": "4KAZY3PXJQ4P0",
              "name": "Whip cream",
              "available": true
            },
            "amount": 25
          }
        ],
        "printed": false,
        "refund": {
          "transactionInfo": {
            "isTokenBasedTx": false,
            "emergencyFlag": false
          }
        }
      }
    ]
  },
  "createdTime": 1737450582000,
  "orderClientCreatedTime": 1737449521000
}
```

### Learn how

Tour a full working example with this recipe.

[block:tutorial-tile]
{
  "backgroundColor": "#0864ba",
  "emoji": "🛒",
  "id": "6340731dbc65d00016b10163",
  "link": "https://docs.clover.com/v3/recipes/order-cart",
  "slug": "order-cart",
  "title": "Order Cart"
}
[/block]

## Step 2: Create an atomic order—Platform API

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, and `orderType` id.
3. Set the Authorization header as Bearer token type, and enter the test API token.

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

### Request and response example—Create an atomic order

The following example uses the Clover-provided inventory item **Espresso** with a modifier for whipped cream.

```curl Request
curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/orders' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
     "orderCart": {
          "discounts": [
               {
                    "name": "$2 Tuesday",
                    "amount": -200
               }
          ],
          "lineItems": [
               {
                    "item": {
                         "id": "MXHW24RNRHW16"
                    },
                    "printed": "false",
                    "exchanged": "false",
                    "modifications": [
                         {
                              "modifier": {
                                   "available": "true",
                                   "price": "0"
                              },
                              "id": "4KAZY3PXJQ4P0",
                              "name": "Whip Cream",
                              "amount": 25
                         }
                    ],
                    "refund": {
                         "transactionInfo": {
                              "isTokenBasedTx": "false",
                              "emergencyFlag": "false"
                         }
                    }
               }
          ],
          "orderType": {
               "id": "GAM80DMM3DEDG"
          },
     }
}
'
```
```json Response
{
  "id": "ORD1234567890",
  "orderCart": {
    "discounts": [
      {
        "id": "DIS1234567890",
        "name": "$2 Tuesday",
        "amount": -200
      }
    ],
    "lineItems": [
      {
        "id": "LI1234567890",
        "item": {
          "id": "MXHW24RNRHW16",
          "name": "Item Name"
        },
        "printed": false,
        "exchanged": false,
        "modifications": [
          {
            "id": "MOD1234567890",
            "modifier": {
              "id": "4KAZY3PXJQ4P0",
              "name": "Whip Cream",
              "available": true,
              "price": 0
            },
            "amount": 25
          }
        ],
        "refund": {
          "transactionInfo": {
            "isTokenBasedTx": false,
            "emergencyFlag": false
          }
        }
      }
    ],
    "orderType": {
      "id": "GAM80DMM3DEDG",
      "name": "Order Type Name"
    }
  },
  "createdTime": 1737450582000,
  "orderClientCreatedTime": 1737449521000
}
```

> 👍 TIP
>
> If adjust the amount of an order after you have created it, you must manually recalculate and update the total by sending a POST request to the `/v3/merchants/{mId}/orders/{orderId}` endpoint.

### Learn how

Tour a full working example with this recipe.

[block:tutorial-tile]
{
  "backgroundColor": "#0864ba",
  "emoji": "📑",
  "id": "633b54045562a600596e9c80",
  "link": "https://docs.clover.com/v3/recipes/create-an-order-with-multiples-items",
  "slug": "create-an-order-with-multiples-items",
  "title": "Create an order with multiples items"
}
[/block]

## Step 3: Pay for order—Ecommerce API

To take payment and include a tip:

1. Send a POST request to the `v1/orders/{orderId}/pay` endpoint using the sandbox base URL: `https://scl-sandbox.dev.clover.com`.
2. Set the `delete_order_on_failure` parameter to **true** as part of the `metadata`. This deletes an order if the payment fails, such as due to fraud.
3. Use the endpoint based on the payment method, such as:

* For a credit card, use the [Create a card token](https://docs.clover.com/reference/create-card-token) endpoint.
* For an ACH payment, use the [Create an ACH token](https://docs.clover.com/reference/create-ach-token) endpoint.
* For a gift card, use the [Create a gift card token](https://docs.clover.com/dev/reference/create-gift-card-token) endpoint.

### Learn how

Tour full working examples with these recipes.

[block:tutorial-tile]
{
  "backgroundColor": "#5b9f2d",
  "emoji": "💳",
  "id": "633ca330f2f35e0092755a28",
  "link": "https://docs.clover.com/v3/recipes/pay-for-an-order-w-a-cc",
  "slug": "pay-for-an-order-w-a-cc",
  "title": "Pay for an Order w/ a 'CC'"
}
[/block]

[block:tutorial-tile]
{
  "backgroundColor": "#5b9f2d",
  "emoji": "🔑",
  "id": "633ca07f1ee24f00235a09d5",
  "link": "https://docs.clover.com/v3/recipes/create-a-card-token",
  "slug": "create-a-card-token",
  "title": "Create a Card Token"
}
[/block]

***

# Handle 400 Bad Request errors

When a 400 Bad Request error occurs, the JSON response contains two properties—message and details. If the server identifies a specific error, it returns a unique identifier (UUID) of the failed element. Here are a few examples:

[block:parameters]
{
  "data": {
    "h-0": "Messages with unrecognized UUID",
    "h-1": "Human-readable error messages",
    "0-0": "- `item_does_not_exist` </br> - `service_charge_does_not_exist` </br> - `invalid_modifier`",
    "0-1": "- `cart_is_empty_or_missing` - `bad_request` </br> - `order_uuid_is_null` </br> - `insufficient_customer_info` </br> - `invalid_discount_attribute`"
  },
  "cols": 2,
  "rows": 1,
  "align": [
    "left",
    "left"
  ]
}
[/block]

**Example:** If the server detects that an order-related element does not exist, the JSON response will include a message—`item_does_not_exist`. To resolve this error, remove or replace the missing or invalid element in your request.

```json JSON
{  
  "message": "item_does_not_exist",  
  "details": "8NR072YTBZ52W"  
}
```

***

# Related topics

* [Manage orders data](https://docs.clover.com/dev/docs/working-with-orders)
* [Create an atomic order](https://docs.clover.com/dev/reference/ordercreateatomicorder) endpoint
* [Create custom orders](https://docs.clover.com/docs/creating-custom-orders) tutorial
* [Work with inventory](https://docs.clover.com/dev/docs/working-with-inventory)