Working With Orders

Overview

The Order object is at the core of Clover’s transaction data. Almost every transaction either creates or updates an Order. When an order is created or updated, the order data is automatically synchronized between the Clover Server and the merchant’s Clover devices.

Note

Money amounts in Clover are always passed as ‘cent’ values. So an amount or total of 2099 would be equivalent to $20.99 for a merchant using the US dollar.

  • Beginning a new transaction in the Register or Pay apps creates a new Order object
  • The Order is updated with lineItems for inventory Items or custom amounts
  • Customer payment updates the Order, associating it with a new Payment object
  • A Refund associates the Order with a new Refund object or Credit object for Manual Refunds

Important

Order totals are calculated dynamically and updated by the apps working with them. This means that if your app modifies an order it must update the total as well. See Calculating Order Totals

Creating an Order

Note

If you are not familiar with using the Clover REST API yet, you can learn more here

To create a new Order object, send a POST request to /v3/merchants/{mId}/orders/

This POST request will return a new Order object, and some values can be set in this initial POST, but no data is required.

Please note, this basic Order object will be treated as unfinished if the Order’s state is null. Before the order has first been set to “open”, it will only be possible to GET the individual order by its id, but it will not otherwise be included in the merchant’s order list, it will also not appear in the Orders app.

{
  "state": "open"
}

 

Important

Once the Order’s “state” is set to “open”, the Order will be returned in the merchant’s order list, and will appear in the Orders app.

Add line Items

Once you have an Order object, you can add line Items by POSTing data to /v3/merchants/{mId}/orders/{orderId}/line_items . Each lineItem represents a single Inventory item being purchased, a single portion of a variable price item, or an individual custom-item/manual-transaction amount.

At a minimum this request must include one of two options:

1. A lineItem object with an amount – which will create a custom lineItem:

{
  "price": 200
}

2. A lineItem object with a reference to an inventory Item:

{
  "item": {
    "id": "[itemId]"
  }
}

Add Item Modifiers

Modifiers are used to customize individual lineItems.These modifiers will be associated with certain item categories and should typically only be applied to items within those categories. A modifier might represent an extra topping on ice-cream, or gift wrapping a toy. You can learn more about modifiers on the merchant facing Help site.

A modifier can be added to a lineItem programmatically by making a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/modifications

At a minimum this request must include a new Modification object with a reference to a modifier:

{
  "modifier": {
    "id": "[modifierId]"
  }
}

The POST will create a new Modification object, which associates the lineItem with the included Modifier.

Add Discounts

Custom discounts can be added to either an entire order or to a single lineItem.

Add a discount to an entire Order by making a POST request to /v3/merchants/{mId}/orders/{orderId}/discounts

Add a discount to a single LineItem by making a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/discounts

At a minimum, this request must include a new custom Discount object with a name and either a negative amount:

{
  "name": "Amount Discount",
  "amount": -150
}

…or a percentage:

{
  "name": "Percentage Discount",
  "percentage": 25
}

Calculating Order Totals

Once you have finished updating an order the total should be updated to reflect the new order state.

The order of operations for calculating an Order’s total is as follows:

  1. For each lineItem, calculate lineItem total
    1. Start with item price
    2. Apply any modifier costs to find lineItem’s pre-discount total
    3. Subtract all percentage lineItem discounts (all percentages based on lineItem’s pre-discount total)
    4. Subtract all amount lineItem discounts to find lineItem’s discounted total
  2. Subtract all order level percentage discounts
  3. Subtract all order level amount discounts
  4. Add service charge to subtotal, if applicable
  5. Calculate tax per taxable line item
  6. Add tax total to pre-tax line item totals to find order’s final total

Note

When rounding decimal amounts smaller than the cent — such as tax per line Item — rounding should be calculated with the Round Half Up tie-breaking rule, meaning fives will be rounded up.

Important

if vat=true in a merchant’s properties, that merchant uses a VAT (Value Added Tax). This means the tax amount is already included in the lineItem total – no additional amount should be added for tax.