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 data associated with it is automatically synchronized between the Clover Server and the merchant’s Clover devices.

Note

Money amounts in Clover are always passed as cent values. 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 app creates a new Order object
  • The Order is updated with lineItems for inventory Items or custom amounts
  • A customer payment updates the Order, associating it with a new Payment object
  • A Refund associates the Order with a new Refund 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 for more information.

Creating an Order

Note

If you are not familiar with using the Clover REST API, you can learn more at the REST API page.

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

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

Please note that this basic Order object will be treated as unfinished if its state is null. If you have not set the Order‘s state to open, it will only be possible to GET the individual Order by its ID. It will not be included in the merchant’s order list or 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 appear in the Orders app.

Add line Items

Once you have an Order object, you can add line items by sending the data as a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items. Each lineItem represents a single inventory item, 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 a price. This 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 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 for a toy. You can learn more about modifiers on the merchant-facing Help site.

You can add a modifier 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 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, as well as a negative amount or percentage. The following example includes a negative amount:

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

The following example includes a percentage:

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

Calculating Order Totals

Once you’ve finished updating an Order, the total should be updated to reflect the Order‘s new state.

To calculate the total for an Order:

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

Note

When rounding decimal amounts smaller than the cent, such as tax per lineItem, 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, and no additional amount should be added for tax.