Working with orders

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 orders the inventory must exist in Clover. You can use our Inventory API to create items, modifiers, discounts, and set up tax rates and rules.

Limitations

  • Supports only Clover inventory and the tax rates associated with those inventory items.
  • If you need to create an order with custom or ad-hoc line items, then you must use the v3/orders API to create the order and /v3/merchants/{mId}/orders/{orderId}/line_items or /v3/merchants/{mId}/orders/{orderId}/bulk_line_items to add a line item or line items to the order.

Atomic order requests

An atomic_order request includes the fields described in the following table:

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 (such as small or large).

discount

An amount or a percentage 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 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 merchant can't view the order on their dashboard or devices. Use /checkouts 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 /v3/merchants/{mId}/atomic_order/checkouts.

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 order totals. The merchant can view this order on their dashboard and devices. If you are using the /atomic_orders/checkouts endpoint to calculate the order total, taxes, and discounts, you can 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 /v3/merchants/{mId}/atomic_order/orders.

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 creation, then 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 don't 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 a baseUrl of https://scl-sandbox.dev.clover.com.

📘

NOTE

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

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 doesn't 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?