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 endpoint to compute order totals and taxes while building the order without finalizing it. Once you are ready, use the Create an atomic order 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 endpoint. See the Create 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 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 endpoint to create the order record.

Step 3: Pay for an order—Use the Pay for an order endpoint of the Ecommerce API to automatically charge the total order amount and to include a tip.

Prerequisites

• Generate a merchant-specific test API token in sandbox.
• Use the Create an inventory item endpoint to get the itemID.
• Use the Create an order type for a merchant to get theorderTypeID. 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 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 the required information—mId, itemId, orderTypeId, and name fields related to the discount object.
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 POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {OAuth 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
                         }
                    ]
               }
          ],
          
     }
}
'

import requests

url = "https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts"

payload = {"orderCart": {
        "lineItems": [
            {
                "item": {"id": "MXHW24RNRHW16"},
                "printed": "false",
                "discounts": [
                    {
                        "name": "$2 Tuesday",
                        "amount": -200
                    }
                ],
                "modifications": [
                    {
                        "modifier": {
                            "available": "true",
                            "id": "4KAZY3PXJQ4P0",
                            "name": "Whip cream"
                        },
                        "amount": 25
                    }
                ],
                "refund": {"transactionInfo": {
                        "isTokenBasedTx": "false",
                        "emergencyFlag": "false"
                    }},
            }
        ],
    }}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer {OAuth Token}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Learn how

Tour a full working example with this recipe.

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, itemId and orderTypeID.
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 example—Create an atomic order

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

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/orders' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {OAuth 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"
          },
     }
}
'

👍

TIP

If you make amount adjustments to the order after its creation, 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.

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 endpoint.
• For an ACH payment, use the Create an ACH token endpoint.
• For a gift card, use the Create a gift card token endpoint.

Learn how

Tour full working examples with these recipes.

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:

Example: If the server detects that an order-related element does not exist, the JSON response will include a message—item_does_not_exist.

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

To resolve this error, remove or replace the missing or invalid element in your request.

Related topics

• Manage orders data
• Create an atomic order endpoint
• Create custom orders tutorial
• Work with inventory