📘

NEW—This topic now contains recipes.

Recipes provide response details and are a great option If you don't have an OAuth token.
Refer to the Learn how sections of this topic to tour working examples of common use cases.

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 new 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.

Prerequisite

Before using the API to create or summarize the orders, the 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.

Limitations

• Only supports inventory items found 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.

Before you begin

To complete an order, it is best to gather the prerequisite information before you begin.

Prerequisites

• order type id
• inventory item id
• modifiers, 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.

Endpoints

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.

Steps

1. Use /atomic_order/checkouts to build the order.
2. Call /atomic_order/orders to create the order.
3. 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 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.

Learn how

Tour a full working example with this recipe.

👍

TIP

Recipes provide response details and are a great option If you don't have an OAuth token.

Example

curl --request POST \
     --url https://sandbox.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)

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 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.

Learn how

Tour a full working example with this recipe.

👍

TIP

Recipes provide response details and are a great option If you don't have an OAuth token.

Example

The following example uses the Clover-provided Inventory item, "Espresso" with modifier id for whipped cream.

curl --request POST \
     --url https://sandbox.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.

Pay for order

📘

NOTE

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

To take 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.

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

See the Ecommerce API endpoint for more information.

📘

NOTE

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

Learn how

Tour full working examples with these recipes.

👍

TIP

Recipes provide response details and are a great option If you don't have an OAuth token.

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 an example 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:

• Create an atomic order
• Checkout an atomic order