Platform Docs

Working with orders

The orders object is at the core of all Clover transaction data. Most transactions 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.

Key features

Creating an orders object: When a Clover merchant creates a new transaction using the Register or Pay app, a new orders object is created. Orders can be created using third-party developer apps as well.

Updating an orders object: An order is updated after merchant actions, such as adding line_items for inventory items or adding custom amount values.

📘

NOTE

Money amount values are represented in cent values. For example, $20.99 is represented as an amount value of 2099.

Associating orders with payments: When a customer pays for an order, a new payments object is associated with the order.

Associating orders with refunds: To handle refunds, a refund object is associated with the order. For manual refunds, a credits object is associated with the order.

🚧

IMPORTANT

Order totals are calculated dynamically and updated by the app that the merchant is using to handle orders. This means that if your app modifies an order, it must update the total as well.

See the Calculating order totals section for more information.

See Using Clover REST API for more information on how to make REST API calls.

Creating an order

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

In response, a unique id (order ID) is generated. While other values can be set in this POST request, none of the values are required.

🚧

IMPORTANT

The 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 UUID.

For orders to appear in the merchant's order list or appear in the Orders app, set the order's state to open.

To change the order state from null to open, send a POST request to /v3/merchants/{mId}/orders/{orderId} with the following payload:

{"state": "open"}

Viewing orders

To view all orders created by a merchant, send a GET request to /v3/merchants/{mId}/orders. In response, all the associated orders are retrieved.

📘

NOTE

If an order is deleted, it is not in the list retrieved by sending a GET request to /v3/merchants/{mId}/orders. To view a deleted order, filter your request with deletedTime.

For example, /v3/merchants/mId/orders?filter=deletedTime>=1596501066. See Applying filters for more information about using filters in the REST API.

To view a single order created by a merchant, send a GET request to /v3/merchants/{mId}/orders/{orderId}. In response, the associated order is retrieved.

Setting order types

You can classify merchant orders into different order types, such as online, delivery, pick-up, or dine-in. Each order type created is specific to a merchant.

To create an order type, send a POST request to /v3/merchants/{mId}/order_types and assign specific rules, such as minOrderAmount or hoursAvailable.

📘

NOTE

By default, every order type for a merchant is visible in the Register app. You can hide specific order types for a merchant by setting the isHidden value to true.

Adding 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 line item 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 line item object with a price. This creates a custom line item.
{
  "price": 200
}
  • A line item with a reference to an inventory item UUID.
{
  "item": {
    "id": "{itemId}"
  }
}

📘

NOTE

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.

To add more than one inventory item in a single request, use the /v3/merchants/{mId}/orders/{orderId}/bulk_line_items endpoint. See the API Reference for more information.

Adding item modifiers

Modifiers customize individual line_items. A modifier might represent an extra topping on ice cream or gift wrapping for a toy.

These modifiers are associated with certain item categories and should typically only be applied to items within those categories. See the merchant-facing help for more information about how merchants use modifiers.

You can add a modifier to a line item by sending a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/modifications.

{
  "modifier": {
    "id": "{modifierId}"
  }
}

Using the POST request, you create a new modifications object, which adds the modifier to the specified lineItem.

Adding discounts

Custom discounts can be added to an entire order or to a single line item.

Adding discounts to an entire order

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

Adding discounts to a single line item

To add a discount to a single line item, 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 and a negative amount or percentage value.

{
  "name": "amount discount of $1.50",
  "amount": -150
}
{
  "name": "percentage discount of 25%",
  "percentage": 25
}

Calculating order totals

After updating an order, the order total must be updated.

To calculate the total for an Order, follow these steps:

  1. Calculate the total for each line item.
  • Start with the price of the item
  • Apply any modifier costs to find the pre-discount total of the line item
  • Subtract all percentage discounts associated with the pre-discount total of the line item
  • Subtract all line item discounts to find the discounted total of the line item
  1. Subtract all order-level percentage discounts. The percentage is based on the sum of all line items after all line item discount totals.
  2. Subtract all order-level amount discounts.
  3. Add service charge to the subtotal, if applicable.
  4. Calculate tax per taxable line item.
  5. Add the tax total to the pre-tax line item totals.

🚧

IMPORTANT

Merchants will receive accurate tax reporting only when you calculate tax for each line item and add the tax total to the pre-tax line item totals.

If vat is set to true in the merchant properties, the merchant uses a VAT (Value Added Tax). This means the tax amount is already included in the line item total and no additional amount should be added for tax.

📘

NOTE

When rounding decimal amounts smaller than a cent, such as tax per line item, calculate rounding with the round half up rule. For example, the rounding value of $33.654 is $33.65 and the rounding value of $33.455 is $33.46.

See Tax Reports: Examples for more information about calculating taxes for line items.

Updated about 16 hours ago


Working with orders


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.