Sign in

v1

latestOpenAPI 3.0.12026-07-242871595.3 MB
ORDERS

Create an atomic order

Description: Creates a complete order including line items, modifiers, discounts, and service charges with a single API call. If you need to create an order using multiple API calls with ad-hoc line items and non-Clover inventory items, use create custom orders.<br> Note: Clover has revoked the limitations of non-Clover inventory items and ad-hoc line items from the create an atomic order endpoint. You can now use the endpoint to create orders, such as create custom orders.<br> Limits: To ensure platform stability, an order is limited to a maximum of 3,000 line items. If this call would cause the order to exceed this limit, the request will fail with a 400 Bad Request error.<br> Tutorial: Manage orders data.

post/v3/merchants/{mId}/atomic_order/orders

Path parameters

mIdstring required

Merchant identifier.

Headers

User-Agentstring required

Identifies the application, operating system, vendor, and/or version of the requesting user agent. Format: <AppName>/<Version> <Comment>

Request body

Response

Successful response. Order created.

idstring

Unique identifier

currencystring

Currency of this order. For example, "USD"

totalinteger

Total price of the order in cents

externalReferenceIdstring

External reference id if present in the order

unpaidBalanceinteger

The net of orders with payment minus the amount collected. Includes refunds, manual refunds, tax, tip, service charge, non-revenue items, paid gift card activations and loads and discounts

paymentState'OPEN' | 'PAID' | 'REFUNDED' | 'CREDITED' | 'PARTIALLY_PAID' | 'PARTIALLY_REFUNDED'

Is this order paid or not?

titlestring
notestring

An arbitrary string with information about this order, may be printed on the order receipt and displayed in apps

taxRemovedboolean

If true then this order should not have taxes applied to it

isVatboolean

This order was created by merchant with VAT enabled.

statestring

A String generally describing the state of the order. If no value is set, the state defaults to null, which indicates a hidden order. A hidden order is not displayed in user interfaces and can only be retrieved by its id. When creating an order via the REST API the value must be manually set to "open". When creating an order via the Android SDK the value must be left empty and the value will be updated to "open" and "locked" automatically when actions such as taking payments and adding line items occur. The state value is not checked or enforced by the Clover server, at this time it is used for visualization purposes only.

manualTransactionboolean

Whether this order represents a manual transaction. A manual transaction is a transaction that has an arbitrary amount defined and is not associated with any inventory items. For example, the Clover Sale App and Clover Manual Transaction App create manual transactions. A manual transactions will have a single associated line item to hold the sale amount, but the generated receipt will display this differently to indicate that it is not considered a typical order with inventory items.

groupLineItemsboolean

Whether similar line items should be grouped together on the receipt that this order generates. Item "similarity" is based on items having matching values for a set of properties including price, modifiers, and discounts.

testModeboolean

Whether this order was created in test mode. Payments made against test orders are not processed. Test mode orders can be deleted from the Orders App on the merchant's device or web dashboard (https://www.clover.com/orders/m/{mId}/orders). They will also be deleted when the device sends a POST to the /v2/merchant/{mId}/orders/delete_all_tests endpoint.

payType'SPLIT_GUEST' | 'SPLIT_ITEM' | 'SPLIT_CUSTOM' | 'FULL'

Possible values: SPLIT_GUEST, SPLIT_ITEM, SPLIT_CUSTOM, FULL. During the payment flow, if the user chooses to split the payment for this order, this field will be set to one of the SPLIT_* values to indicate how the full amount should be split. If the user chooses to pay for the order in full with one payment, then this field will be FULL.

createdTimeinteger

Creation timestamp

clientCreatedTimeinteger

Time at which the client created this order.

modifiedTimeinteger

Last modified time of the order.

deletedTimestampinteger