Create custom orders
Use multiple Clover API endpoints to create an order with customized line items.
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
orhoursAvailable
. - 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
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
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
andorder 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
andorderId
. - 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
, andmodifierId
. - 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
, andlineItemId
. - Enter the discount
name
andpercentage
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
andorderId
. - Enter the discount
name
andpercentage
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
andorderId
. - Enter the service charge
id
,name
andpercentageDecimal
, and set theenabled
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
}'
Related topics
- Manage orders data
- Create custom orders endpoint
- Create a new line item endpoint
- Create multiple line items endpoint
- Apply modifiers to a line item endpoint
- Create a discount on a line item endpoint
- Apply a service charge to an order endpoint
Updated 2 days ago