Orders data

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

  • Supports only Clover inventory items and their associated tax rates.
  • 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.

Field

Description

orderCart

Container for order data including line items, line item modifiers, discounts, and taxes.

lineItems

Line items associated with an order, such as coffee and muffin.
You can use a modifier to indicate the size of the coffee (small or large).

discount

An amount or a percentage of discount applied to the order.

orderType

The classification of the order as different order types, 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.

serviceCharge

Optional service charge or gratuity tip applied to the order.

Order creation flow

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

curl --location --request POST 'https://sandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/checkouts' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "orderCart": {
         “orderType”: {
                        “id”: “{existingCloverOrderTypeUUID}”
             },
       "lineItems": [
             {
               "item": {
                   "id": "{existingCloverInventoryItemUUID}"
               },
               "modifications": [
                   {
                       "amount": 10,
                       "modifier": {
                           "id": "{existingCloverModifierUUID}"
                       },
                       "name": "Coffee Sizes"
                   }
               ]
           }
        ],
        "discounts": [
            {
                "name": "$2 off",
                "amount": -2
            }
        ]
      }
}'

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.

curl --request POST --url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/atomic_order/orders' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' 
--data-raw '{
        "orderCart":{
            "lineItems":[
                    {
                    "item":{
                        "id":"{existingCloverInventoryItemUUID}"
                    }
                 }
         ]
    }
 }'

👍

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.

Requirements for using modifiers

  • 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

Pay for order

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

📘

NOTE

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

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.

Handling 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 a sample of the error response included 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:


Did this page help you?