Use the Create an atomic order endpoint to create a complete order with a single API call, including line items, modifiers, discounts, and service charges. This endpoint can also compute order totals and taxes while building the order without creating an actual order. This endpoint builds an ordering solution for both in-store and online orders.

If you need to create an order using multiple API calls with ad-hoc line items and non-Clover inventory items, use the create custom orders endpoint. See the Create custom orders tutorial to learn more.

📘

Tip

Clover has revoked the limitations of non-Clover inventory items and ad-hoc line items from the create an atomic order endpoint. You can now use the endpoint to create orders, such as create custom orders.

Prerequisite

Before using the API to create or summarize the orders, the inventory must be available in the Clover environment. You can use our Create an inventory item to create items, modifiers, and discounts and set up tax rates and rules.

Atomic order requests

An atomic_order request includes the following fields:

Before you begin

Prerequisites

Before creating an order, you must have the following identifiers:

• orderTypeId
• itemId
• modId, if any
• discountId, if any
• taxId, if any

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.

Steps

Multiple endpoints are required to create an order:

1. Build an order summary—v3/merchants/{mId}/atomic_order/checkouts endpoint opens a cart to build the order (prerequisite information is captured here).
2. Create the order record—/v3/merchants/{mId}/atomic_order/orders endpoint creates the order record.
3. Pay for an order—v1/orders/{orderId}/pay of the Ecommerce API automatically charge the total order amount and to include a tip.

Step 1: Build an order summary—Platform API

Use the /atomic_order/checkouts endpoint to build an 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. This endpoint does not display orders on their dashboards and devices.

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.

Learn how

Tour a full working example with this recipe.

👍

TIP

Recipes provide response details and are a great option if you do not have an OAuth token.

Example

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://sandbox.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)

Step 2: Create an order—Platform API

• Use the /atomic_order/orders endpoint to create an order and calculate the order totals.
• 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.
• Merchants can view the orders on their dashboards and devices.

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.

Learn how

Tour a full working example with this recipe.

👍

TIP

Recipes provide response details and are a great option if you do not have an OAuth token.

Example

The following example uses the Clover-provided inventory item "Espresso" with modifierid 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.

Step 3: Pay for order—Ecommerce API

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

When paying for an order, 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.

If you want to use a credit card, use the Create a card token endpoint.

If you want to use an ACH payment, use the Create an ACH token endpoint.

📘

NOTE

Base URL https://scl-sandbox.dev.clover.com is only applicable for testing and not for production. See the Ecommerce API endpoint for more information.

Learn how

Tour full working examples with these recipes.

👍

TIP

Recipes provide response details and are a great option if you do not have an OAuth token.

Handle 400 Bad Request errors

JSON response consists of two properties - message and details. If the server detects a specific error, it returns an UUID of the failed element.

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

The following example displays 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 in your request.

For the following message values, the details value is unrecognized UUID:

• item_does_not_exist
• service_charge_does_not_exist
• invalid_modifier

The following are human-readable error messages:

• cart_is_empty_or_missing
• bad_request
• order_uuid_is_null
• insufficient_customer_info
• invalid_discount_attribute

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

• Create an atomic order
• Checkout an atomic order