Create custom orders

Use multiple Clover API endpoints to create an order with customized line items.

United States

Canada

Europe

Manage orders data Generate test API token Calculate order totals Print orders Create custom order endpoint

Custom orders allow you to create orders using multiple API endpoints. This approach is suitable for orders requiring non-standard items or specific customizations. You can override default properties such as tax rates or item prices, providing greater flexibility.

Clover merchants create an order before completing transactions with the Register or Sale app. An order is updated after merchant actions, such as adding line items for inventory items or custom amount values. The Clover server synchronizes the order data with the merchant's Clover devices.

📘
NOTE
Use the Create an atomic order endpoint to create orders using Clover inventory and leverage the real-time totals and tax calculation features using a single API call. See the Create an atomic order tutorial to learn more.

Benefits

The key benefits of creating custom orders are:

Flexibility—Customize orders to include non-Clover inventory items or override default properties like tax rates and item prices.
Control—Manage each component of the order individually, allowing for precise adjustments and customizations.
Adaptability—Suitable for complex orders that require specific configurations or non-standard items.

Workflow

The workflow to create a custom order includes:

Step 1: Create an order object—Use the Create custom orders endpoint to create a new order object with an open status. After the order is created, add payment details, such as amount, currency, and paymentType.

Step 2: Add line items—Use the Create a new line item endpoint to add line items to the order. You can add custom or ad-hoc line items from a non-Clover inventory.

Step 3: Optional. Apply modifiers—Use the Apply a modifier to a line item endpoint to include customizations or options for a line item.

Step 4: Optional. Add a discount—Use the Create a discount on a line item endpoint to apply a fixed amount or percentage discount to a line item.

Step 5: Optional. Add a service charge—Use the Apply a service charge to an order endpoint to apply service charge or gratuity tax to an order.

Step 6: Calculate order totals—Order totals are calculated dynamically and updated by the app the merchant uses to handle orders. If your app modifies an order, it must update the total as well. See Calculate order totals for more information.

Step 7: Process payments—When a customer pays for an order, a new payments object is associated with the order. If the payment is successful, the order status is updated accordingly.
Note: Amount values are represented in cents. For example, $20.99 is represented as an amount value of 2099.

Step 8: Optional. Process refunds—To handle refunds, a refund object is also associated with the order. For manual refund a credits object is associated with the order.

Prerequisite

Generate a merchant-specific test API token in sandbox.

Step 1: Create an order

Set order type

Merchant orders can be of different order types, such as online, delivery, pick-up, or dine-in. Each order type is specific to the merchant.

To create an order type:

Send a POST request to /v3/merchants/{mId}/order_types.
Enter required information—mId (merchant identifier).
Set specific rules, such as minOrderAmount or hoursAvailable.
Set the Authorization header as Bearer token type, and enter the test API token.

The response returns a unique order type id.

Request and response example—Set order type

url --request POST \
     --url https://apisandbox.dev.clover.com/v3/merchants/{mId}/order_types \
     --header 'authorization: {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "taxable": true,
  "isDefault": "false",
  "filterCategories": "false",
  "isHidden": "false",
  "isDeleted": "false",
  "maxOrderAmount": 10000,
  "hoursAvailable": "ALL"
}
'

{
  "id": "KFRPRVCZ73JHM", // orderType Id
  "taxable": true,
  "isDefault": false,
  "filterCategories": false,
  "isHidden": false,
  "maxOrderAmount": 10000,
  "hoursAvailable": "ALL",
  "isDeleted": false
}

Set order state

Send a POST request to /v3/merchants/{mId}/orders.
Enter required information—mId (merchant identifier).
Set the order state as Open to display the order in the merchant's order list or Orders app.
Set the Authorization header as Bearer token type, and enter the test API token.

In response, an order object is created and unique order id is generated.

Request example—Create an order and set the order `state`

curl --request POST \
     --url https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders \
     --header 'authorization: {access_token}' \
     --header 'content-type: application/json' \
     --data '
{
  "orderType": {
    "taxable": "false",
    "isDefault": "false",
    "filterCategories": "false",
    "isHidden": "false",
    "isDeleted": "false",
    "id": "KFRPRVCZ73JHM"
  },
  "taxRemoved": "false",
  "currency": "USD",
  "total": 1500,
  "state": "Open"
}
'

{
  "href": "https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/4N8Q0Q1P95900",
  "id": "4N8Q0Q1P95900", // order Id
  "currency": "USD",
  "total": 1500,
  "orderType": {
    "id": "KFRPRVCZ73JHM" // orderType Id
  },
  "taxRemoved": false,
  "isVat": false,
  "state": "Open",
  "manualTransaction": false,
  "groupLineItems": true,
  "testMode": false,
  "createdTime": 1737449521000,
  "clientCreatedTime": 1737449521000,
  "modifiedTime": 1737449521000
}

View orders

To view all orders for a merchant, send a GET request to /v3/merchants/{mId}/orders.
To view a single order for a merchant, send a GET request to /v3/merchants/{mId}/orders/{orderId}.
To view a deleted order, filter your request with deletedTime. Example: /v3/merchants/mId/orders?filter=deletedTime>=1596501066. For more information, see Apply filters.
Enter required information—mId (merchant identifier).
Set the Authorization header as Bearer token type, and enter the test API token.

In response, the specified order information is displayed.

You can also view orders on the test Merchant Dashboard.

View order based on `state`

If the order state is null, you cannot retrieve the order details by sending a GET request to the v3/merchants/{mId}/orders endpoint. The order object is considered unfinished. Orders with a null state do not display on the Orders app on the device but will display on the Merchant Dashboard if an order total is set.

If an order state is set to any state other than open or null, you can use the order ID to retrieve the order details by sending a GET request to the v3/merchants/{mId}/orders/{orderId} endpoint.

Step 2: Add order line items

After you create an order object, you can add line items. Each line item represents a single inventory item, a single portion of a variable-price item, or an individual custom item or manual transaction amount. You can build the line item using the current state of the referenced inventory item. Any additional line item properties you provide on the request, such as tax rates or item prices, are ignored.

You can add order line items in two ways—Add an inventory item and Add a custom line item.

Add an inventory item

Send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items.
Enter the required information—mId and order Id.
Set the Authorization header as Bearer token type, and enter the test API token.

Request and response sample—Create a line item and generate item ID

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '
{
  "colorCode": "#442255",
  "name": "Purple grapes",
  "alternateName": "Grapes",
  "price": 2100,
  "unitQty": 1,
  "unitName": "Bunch",
  "note": "Seasonal fruit"
}
'

{
  "id": "EJ84S3JY34FZC", //item Id
  "orderRef": {
    "id": "4N8Q0Q1P95900"
  },
  "name": "Purple grapes",
  "price": 2500,
  "unitQty": 1,
  "unitName": "Bunch",
  "note": "Seasonal fruit",
  "createdTime": 1737450582000,
  "orderClientCreatedTime": 1737449521000,
}

In response, a line item id is generated.

👍
TIP
If your request includes more than one line_item, only the last item in the request is added to the order. Use the bulk_line_items endpoint to add multiple line items.

Add a custom line item with price and tax

To create a custom line item, you can first add or retrieve a tax rate and then apply it to the line item. Merchants can add tax rates on the Merchant Dashboard under Account & Setup > Business Operations > Taxes & Fees.

Do one of the following:

Send a POST request to /v3/merchants/mId/tax_rates to create a tax rate for a merchant and not the ID.
Send a GET request to /v3/merchants/{mId}/tax_rates to retrieve an existing tax rate.

Send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items.
Enter the required information—mId and orderId.
Enter the tax rate in the taxRates object.
Set the Authorization header as Bearer token type, and enter the test API token.

Request and response sample—Create line item with price and tax

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "price": 1200,
    "name": "Caesar Salad",
    "taxRates": [
      {
        "rate": 1000000,
        "id": "{taxRateId}",
        "name": "State tax",
        "isDefault": true
      }
    ]
  }'

{
  "id": "KJH8S9D7F6G5H4",
  "name": "Caesar Salad",
  "price": 1200,
  "unitQty": 1,
  "taxRates": [
    {
      "rate": 1000000,
      "id": "TAX123456",
      "name": "State tax",
      "isDefault": true
    }
  ],
  "createdTime": 1737450582000,
  "orderClientCreatedTime": 1737449521000
}

Create multiple line items

Use the v3/merchants/mId/orders/orderId/bulk_line_items endpoint to create multiple line items in a single request. This endpoint allows you to add ad hoc line items or reference Clover inventory while overriding properties such as taxRates, price, name, and so on.

Request samples—Override tax rate; Use flat rate rate

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/bulk_line_items' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "items": [
        {
            "item": {
                "id": "{CloverInventoryItemUUID}"
            },
            "price": 100,
            "name": "Hamburger",
            "taxRates": [
                {
                    "id": "{taxRate UUID}",
                    "rate": 200000,
                    "name": "Sales Tax"
                }
            ]
        },
        {
            "item": {
                "id": "{CloverInventoryItemUUID}"
            },
            "price": 1000,
            "name": "Coke"
        }
    ]
}'

curl --request POST \
  --url 'https: //apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/bulk_line_items' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json'
  --data-raw '{
    "items": [
        {
            "item": {
                "id": "{CloverInventoryItemUUID}"
            },
            "price": 500,
            "name": "Coffee",
            "taxRates": [
                {
                    "id": "{taxRate UUID}",
                    "taxAmount": 100,
                    "rate": 0,
                    "name": "Sales Tax"
                }
            ]
        },
        {
            "item": {
                "id": "{CloverInventoryItemUUID}"
            },
            "price": 300,
            "name": "Muffin"
        }
    ]
}'

👍
TIP
If your app caches inventory items, you should also register for webhook notifications so that you know when item prices are updated or when items are added or removed from the inventory. See Use webhooks.

Step 3: Add item modifiers

You can add modifiers to customize individual line_items. Use modifiers to add any extras to an order, such as salad add-ins or extra toppings on ice cream.

To create a modifier, complete the following steps:

Create a modifier group (Salad add-ins) with /v3/merchants/{mId}/modifier_groups endpoint.
Add a modifier (Avocado) to the group with the /v3/merchants/{mId}/modifier_groups/{modifierId}/modifiers endpoint.

Merchants can add modifier groups and modifiers on the Merchant Dashboard, under Inventory > Modifier Groups.

For more information, see Manage modifier groups and modifiers.

To add a modifier to a line item:

Send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/modifications.
Enter the required information—mId, orderId, lineItemId, and modifierId.
Set the Authorization header as Bearer token type, and enter the test API token.

Request sample—Add a modifier to a line item

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/modifications' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "modifier": {
      "id": "{modifierId}"
    }
  }'

Step 4: Add discounts

You can add custom discounts to a single line item or an entire order.

Add discounts to a single line item

Send a POST request to /v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/discounts
Enter the required information—mId, orderId, and lineItemId.
Enter the discount name and percentage or negative or zero (0)amount value.
Set the Authorization header as Bearer token type, and enter the test API token.

Request sample—Percentage and amount discount values

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/discounts' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "name": "25% off select salads",
    "percentage": 25
  }'

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/line_items/{lineItemId}/discounts' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "name": "lunch deal",
    "amount": -100
  }'

Add discounts to an entire order

To add a discount to an entire order:

Send a POST request to /v3/merchants/{mId}/orders/{orderId}/discounts.
Enter the required information—mId and orderId.
Enter the discount name and percentage or negative or zero (0)amount value.
Set the Authorization header as Bearer token type, and enter the test API token.

Request sample—Order discount

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/discounts' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "name": "15th visit 15% off",
    "percentage": 15
  }'

Step 5: Apply a service charge

Clover merchants can add service charges based on local, state, and country laws or card brand rules. A merchant's default service charge is set through the Setup App or on the Merchant Dashboard under Account & Setup > Business operations > Additional Charges.

To apply a service charge to a line item, you need to get service charges associated with a merchant.

Get default service charge for a merchant

Send a GET request to /v3/merchants/{mId}/default_service_charge endpoint.
Enter the mId (merchant identifer).
Set the Authorization header as Bearer token type, and enter the test API token.

The service charge name and percentage amount are displayed in the response.

Request and response sample—Get service charges for a merchant

curl --request GET  \
--url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/default_service_charge \
--header 'content-type: application/json' \
--header 'Authorization: Bearer {access_token}'

{
  "id": "YQKKXC2QNXM24",
  "name": "Service Charge",
  "enabled": true,
  "percentage": 10,
  "percentageDecimal": 100000
}

Apply service charge to an order

Send a POST request to the /v3/merchants/{mId}/orders/{orderId}/service_charge/ endpoint.
Enter the required information—mId and orderId.
Enter the service charge id, name and percentageDecimal, and set the enabled status to true.
Set the Authorization header as Bearer token type, and enter the test API token.

Request example 5% service charge

curl --request POST  \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders/{orderId}/service_charge' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "id": "{serviceChargeId}",
    "name": "Service charge",
    "enabled": true,
    "percentageDecimal": 50000
  }'

Create custom orders

📘
NOTE

Benefits

Workflow

Prerequisite

Step 1: Create an order

Set order type

Request and response example—Set order type

Set order state

Request example—Create an order and set the order `state`

View orders

View order based on `state`

Step 2: Add order line items

Add an inventory item

Request and response sample—Create a line item and generate item ID

👍
TIP

Add a custom line item with price and tax

Request and response sample—Create line item with price and tax

Create multiple line items

Request samples—Override tax rate; Use flat rate rate

👍
TIP

Step 3: Add item modifiers

Request sample—Add a modifier to a line item

Step 4: Add discounts

Add discounts to a single line item

Request sample—Percentage and amount discount values

Add discounts to an entire order

Request sample—Order discount

Step 5: Apply a service charge

Get default service charge for a merchant

Request and response sample—Get service charges for a merchant

Apply service charge to an order

Request example 5% service charge

Related topics

📘NOTE

Benefits

Workflow

Prerequisite

Step 1: Create an order

Set order type

Request and response example—Set order type

Set order state

Request example—Create an order and set the order state

View orders

View order based on state

Step 2: Add order line items

Add an inventory item

Request and response sample—Create a line item and generate item ID

👍TIP

Add a custom line item with price and tax

Request and response sample—Create line item with price and tax

Create multiple line items

Request samples—Override tax rate; Use flat rate rate

👍TIP

Step 3: Add item modifiers

Request sample—Add a modifier to a line item

Step 4: Add discounts

Add discounts to a single line item

Request sample—Percentage and amount discount values

Add discounts to an entire order

Request sample—Order discount

Step 5: Apply a service charge

Get default service charge for a merchant

Request and response sample—Get service charges for a merchant

Apply service charge to an order

Request example 5% service charge

Related topics

📘
NOTE

Request example—Create an order and set the order `state`

View order based on `state`

👍
TIP

👍
TIP