Manage orders data
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:
Field | Description |
---|---|
orderCart | Order cart that contains items, discounts, modifications, and order-related information. |
lineItems | Line items associated with the order. You can use a modifier to indicate the size of the coffee (small or large). |
discount | Amount 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. |
orderType | Classification 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 . |
serviceCharge | Optional. 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 anydiscountId
, if anytaxId
, 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
andamount
values, these override default modifiers set in the merchant's inventory.
Steps
Multiple endpoints are required to create an order:
v3/merchants/{mId}/atomic_order/checkouts
endpoint opens a cart to build the order (prerequisite information is captured here)./v3/merchants/{mId}/atomic_order/orders
endpoint creates the order record.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
- 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.
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:
Updated 8 months ago