Manage orders data

United States
Canada

Use the Atomic Orders API 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 with custom or ad-hoc line items, use the /v3/orders endpoint.

Prerequisite

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

Atomic order requests

An atomic_order request includes the following fields:

FieldDescription
orderCartOrder cart that contains items, discounts, modifications, and order-related information.
lineItemsLine items associated with the order.
You can use a modifier to indicate the size of the coffee (small or large).
discountAmount or percentage discount applied to the order subtotal. To retrieve discounts applied to individual items, use the get all line items for an order endpoint and enter discounts in the expand parameter.
orderTypeClassification of the order, 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. A service charge or gratuity tip is applied to the order.

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. v3/merchants/{mId}/atomic_order/checkouts endpoint opens a cart to build the order (prerequisite information is captured here).
  2. /v3/merchants/{mId}/atomic_order/orders endpoint creates the order record.
  3. v1/orders/{orderId}/pay of the Ecommerce API 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. 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://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.
  • 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://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

Base URL https://scl-sandbox.dev.clover.com is only applicable for testing and not for production. See Work with test merchants in sandbox for more information.

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.

See the Ecommerce API endpoint for more information.

📘

NOTE

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: