Platform Docs

Working with Orders

With the Order object, you can expand merchant business using REST API.

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.

  • 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)

NOTE

Money amounts in Clover are represented in cent values. For example, an amount value of 2099 is equivalent to $20.99 for a merchant using the US dollar.

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.

This initial Order object is treated as unfinished while 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. To change the order state, send a POST request to /v3/merchants/{mId}/orders/{orderId} with the following payload:

{
  "state": "open"
}

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:

  • A lineItem object with a price. This creates a custom lineItem.
{
  "price": 200
}
  • A lineItem object with a reference to an inventory Item.
{
  "item": {
    "id": "[itemId]"
  }
}

NOTE

To add more than one item in a single request, you must use the /v3/merchants/{mId}/orders/{orderId}/bulk_line_items endpoint (see the API Reference for more information). If your payload for a request to the line_items endpoint includes more than one item, only the last item in the payload will be added to the order.

Add Item Modifiers

Modifiers customize individual lineItems. These modifiers are 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 by making a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/modifications.

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

The POST creates a new Modification object, which adds the modifier to the specified lineItem.

Add Discounts

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

To add a discount to an entire Order, send a POST request to /v3/merchants/{mId}/orders/{orderId}/discounts.

To add a discount to a single LineItem, send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/discounts.

At a minimum, the request payload must include a new custom Discount object with a name, as well as a negative amount or percentage value. The following examples show how to create the two types of discount:

{
  "name": "amount discount of $1.50",
  "amount": -150
}
{
  "name": "percentage discount of 25%",
  "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
    • Start with item's price
    • Apply any modifier costs to find the lineItem's pre-discount total
    • Subtract all percentage lineItem discounts (all percentages based on lineItem's pre-discount total)
    • 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.