Orders FAQs

Can I track which Clover device was used to place an order?

Yes, you can identify the device used to place an order by setting up an order title prefix for each device. This can be configured under Setup > Devices > Order Title Prefix in the Clover Merchant Dashboard. Assigning unique prefixes to each device allows you to trace orders back to the originating machine, even if multiple users share login credentials.

Why isn’t the $3.00 discount on my receipt showing in the `/line_items?expand=discounts` API response, and where can I find it?

The $3.00 discount you see on the receipt is an order-level discount, not a line-item-level discount. The endpoint you're currently using: /v3/merchants/{merchantId}/orders/{orderId}/line_items?expand=discounts only returns discounts that are applied directly to individual line items.

To retrieve order-level discounts, you should use the following endpoint instead /v3/merchants/{{merchantId}}/orders/{{orderId}}?expand=lineItems&expand=discounts

This endpoint will return:

All line items in the order
Any discounts applied to the entire order (not tied to specific items)

Tip: If a discount is shown on the receipt but not linked to a specific product, it's most likely an order-level discount and will be included in the response from the above endpoint.

Can I apply discounts at the product level instead of the entire order in the Clover Register app?

Yes, the Clover Register app allows you to apply discounts either at the order level or individually to each product. To apply a discount to a specific item, select the item in the order, then select the discount you want to apply. For detailed steps, see how to Create a custom order.

How can I create and send a custom-formatted order to a receipt printer using the Clover Print API?

Use the Create an atomic order or Create a custom order endpoints with the Print API to send orders to a receipt printer. However, the default formatting does not support full receipt customization, such as grouped items, subtotal/tax/total sections, or header branding. For more control over formatting:

Use the note field with line breaks (\n) to simulate custom layouts.
Group line items manually in your application logic before sending the order.
Include business name and contact info in the note or title fields of the order.

For advanced formatting, consider integrating with the Clover Order Connector SDK or using a custom app on the device.

Can I add a custom message or image at the end of a Clover receipt after an order is paid?

Yes, you can customize receipts using the Clover Android SDK. While you can't directly append an XML file to the receipt, you can use the SDK to add custom text or images to the bottom of the printed receipt. You can create a custom receipt handler or use the ReceiptRegistration and ReceiptHandler interfaces. For implementation details, see Create custom receipts with CloverConnector.

Can I align both line items and modifications on the same side of the order ticket?

No, there is currently no option to change the alignment of line items and modifications on printed order tickets. Line items are left justified, while modifications appear right-justified by default.

Which Clover API call can I use to retrieve order labels?

To get order labels use:
GET /v3/merchants/{merchantId}/orders/{orderId}/line_items?expand=item.tags
This retrieves line items for an order and includes item tags, such as kitchen or bar, using the expand=item parameter.tags parameter.

To learn more, see Use expandable fields for API responses.

Can I apply discounts to individual products instead of the entire order in the Clover Register app?

Yes, Clover supports product-level (line item) discounts. If you're a developer, you can apply these discounts either during order creation using the Atomic order endpoint or after the order is built using the Create a new line item endpoint. These options allow you to target specific items rather than applying a discount to the entire order.

How can I record a payment in Clover for an order that was created and paid through an external system?

If you've already received payment through an external system and created the order in Clover, you can mark it as paid by adding a payment record using the Create a payment record on an order endpoint. If the payment is processed through Clover, the order status updates automatically. Another option is to use a custom tender for the payment.

Can I refund a line item or an entire order using the Clover Platform API?

The Clover Platform API does not currently support processing refunds or returns directly. While you can create orders and record payments using endpoints like /atomic_order/orders and /orders/{order_id}/payments, refund operations must be handled through the Merchant Dashboard or the Ecommerce API, which support refund functionality. For advanced use cases, send an email to [email protected].

Can I print a payment receipt with itemized pricing using the Clover REST API or Pay Display API? Is receipt image generation supported?

The REST Pay Display API provides two options for printing receipts with the built-in printer:

Print a standard Clover receipt that complies with card brand requirements.
Print a text- or image-based receipt if your integration has specific design requirements that are not met on a standard receipt. For most merchants, the Set up payment receipts are sufficient.
For more information, see Print a receipt.

How do I add a line item to an order using the Clover REST API?

To add line items to an order using the Clover REST API, you can use the following:

Atomic Order endpoint (POST /v3/merchants/{mId}/atomic_order/orders): Create a new order and include all details in one request—line items, modifiers, discounts, and so on. This is ideal for building a complete order in a single atomic operation.
Line Items endpoint (POST /v3/merchants/{mId}/orders/{orderId}/line_items): Add a single line item to an existing order. This is the standard way to append items after the order has been created.
Bulk Line Items endpoint (POST /v3/merchants/{mId}/orders/{orderId}/bulk_line_items): Add multiple line items at once to an existing order for efficiency.

For more information, see Manage orders data tutorials.

Can I change the state of an order with `state` = null on the Clover.com portal, or is an API call required?

Yes, merchants can sometimes update an order’s state on the Clover Merchant Dashboard by editing the order, adding items, or applying a payment. These actions may trigger the system to assign a valid state, such as open or locked. However, if the order already has items and payments but still shows state = null, it may be due to a sync issue or an incomplete creation process. In such cases, using the Orders API to explicitly update the order state is recommended. If the issue persists, contact Clover Developer Relations with your developer and merchant details.

Why do I get Order not found on Clover Mini when calling the Payment API?

The error likely indicates that the device isn’t syncing properly. Confirm that your Mini is connected and successfully synced with Clover servers. Also, verify that the order ID is valid and accessible. If the issue persists, contact Clover supports and provide your merchant and device details.

What does the Credited value in the `paymentState` mean in Clover orders?

The Credited value in the paymentState field indicates that the order has been refunded. This status typically appears when a refund is processed using the Refunds app or the Manual Transactions app. It signifies that the payment associated with the order has been reversed or credited back to the customer. Clover recommends checking the refunds or credits object within the order expansion (GET /v3/merchants/{mId}/orders/{orderId}?expand=refunds) to verify the specific refund details.

How can I apply a tax rate to an entire order using the Clover Android SDK or REST API?

Clover does not support applying a tax rate directly to the entire order via SDK or API. Instead, taxes must be applied at the line item level, and the tax rate must already exist in the merchant’s inventory.

Key requirements:

Tax rate must exist in Clover inventory: You cannot create or apply a new tax rate dynamically unless it’s already defined in the merchant’s inventory.
Apply tax rate to line items: Use the setTaxRates() method on each LineItem to apply the tax. Ensure the tax rate ID is valid and active.
No direct support for order-level tax: Clover does not currently support applying a tax rate to the entire order in one step.

Common issues:
If the item already has a tax applied, your custom tax may not override it. If the tax rate is not properly linked to the item in inventory, it won’t reflect in the order. Tax amount of 0.00 usually means the tax rate wasn’t applied correctly or the rate value is too low, such as, 2L = 0.002%. For more information, see Create a custom order.

Why aren't my custom orders printing after calling the `print_events` API? Will custom modifiers be printed?

Clover doesn't print custom modifiers unless they're added to inventory and linked to items. If the print_event status stays 'created', check these:

Use a simple order (no modifiers) to test.
Ensure you're in a live environment with a connected Clover device.
Use a Clover-compatible app to handle print events.

Why am I getting a 502 Bad Gateway error when querying orders in Clover sandbox with filters and expansions?

A 502 Bad Gateway error in the sandbox is typically caused by a timeout due to overly complex queries that exceed the environment's processing limits. To resolve 502 errors:

Limit expansions: Avoid deeply nested expand parameters, such as expand=lineItems.modifications). Every expansion adds a join to the database query, which often times out in the lower-resourced sandbox environment.
Use pagination: Always use limit and offset parameters to fetch smaller batches of data rather than requesting large datasets at once.
Check filter syntax: Ensure your filter string is properly URL-encoded; malformed filters can occasionally cause the gateway to drop the connection.
Sandbox versus production: The sandbox environment has stricter rate limits and lower performance thresholds than production; if a simplified query works, the 502 was likely a timeout.

How do I add an existing modifier to an order line item using Clover `OrderConnector`?

To add an existing modifier to a line item using the OrderConnector, ensure the modifier is fully defined with required fields. A common cause of the status code 400 error is missing required properties, such as name and amount, in the modifier object.

Modifier modifier = new Modifier();
modifier.setId("MODIFIER_ID"); // Required  
modifier.setName("Modifier Name"); // Required  
modifier.setAmount(100L); // Required (in cents)  

Reference modifierGroup = new Reference();  
modifierGroup.setId("MODIFIER_GROUP_ID");  
modifier.setModifierGroup(modifierGroup);

orderConnector.addLineItemModification(orderID, lineItemID, modifier);  
orderConnector.updateOrder(order);

Note: You must include modifier.setName() and modifier.setAmount() even if the modifier already exists. Always call updateOrder() after adding the modification. Ensure the modifier is associated with the item through the inventory setup. See OrderConnector documentation for more details.

How do I create a customer and assign it to an order using the Clover REST API?

Clover does not support creating and assigning a customer to an order in a single atomic request. Follow these steps:

Create the customer using the Customers API. Send a POST request to: /v3/merchants/{mId}/customers.
Create the order using the Orders API. Send a POST request to: /v3/merchants/{mId}/orders/{orderId}.
Update the order to associate it with the customer using the customer.id field.
To avoid creating duplicate customers, you can use the Get Customers endpoint to search for existing customers by fields such as email or phoneNumber. If a match is found, use that customer’s ID when updating the order. Otherwise, proceed to create a new customer. See Customers API documentation for supported query parameters.

How does Clover calculate sales tax when applying discounts in atomic orders?

Clover calculates sales tax after discounts are applied, but the method depends on how the discount is structured:

Line item discounts: Tax is calculated on the discounted price of each item.
This method ensures accurate tax per item but may result in rounding discrepancies when summing up the total discount (e.g., a 5% discount applied individually may differ slightly from a 5% discount on the subtotal).
Clover uses round half up rules for decimal rounding:
$33.654 → $33.65
$33.455 → $33.46

Order-level discounts: Tax is calculated on the subtotal after the order-level discount is applied.
This method aligns better with external systems that calculate discounts on the subtotal, but may not group items correctly for tax if they have different tax rates.

Negative line item method: Adding a discount as a negative line item does not affect tax calculations.
Clover ignores this line when calculating tax, which can lead to incorrect tax totals.

Best practice: Use line item discounts if you want accurate tax calculations per item. Use order-level discounts if your external system calculates discounts on the subtotal and you want consistency in discount totals. Be aware of rounding differences and test both methods using the Checkout an atomic order endpoint before finalizing.

Can I create an order using the Clover REST API and have it show up in the Dining app

Orders created using the Orders or Atomic Orders REST API appear in the Orders and Register apps; however, they are not compatible with Clover Dining, which uses a private data schema for features such as table mapping and guest seating. The Dining app does not recognize table assignments or dining-specific metadata from external order creation.

Why can't I re-issue an order receipt from a past order using the Clover API?

Orders created using the Atomic order endpoint must include valid Clover inventory items and associated modifiers to be eligible for printing. Clover does not support printing customer items with custom modifiers unless they are linked to existing Clover inventory and modifier groups.

To print an order receipt manually:

Confirm that the merchant has a configured order printer and the necessary permissions (Write orders, Read orders).
Use the Print Orders REST API to send a print request to the merchant’s default device.
Ensure the order includes valid line items and modifiers from Clover inventory.

How can I retrieve a customer’s first and last name from the Get Orders API?

The default response from the Get Orders API only includes the customer’s reference and id. To access the customer's full details, including first and last name, use the expand parameter in your API request: {{baseUrl}}/v3/merchants/{mId}/orders/{orderId}?expand=customer.

Will an atomic order show up on all devices for the same merchant?

Yes, orders created using the Atomic order endpoint are synced across all connected Clover devices under the same merchant account. This ensures consistent visibility and reporting across multiple lines or devices.

Why don’t receipts print for atomic orders with modifiers?

Clover doesn’t support printing custom items with modifiers using the Atomic order endpoint. Treating modifiers as separate line items may help, but it can cause display issues, such as incorrect order in virtual receipts. For reliable printing and readable receipts, use Clover inventory items with linked modifier groups. Custom modifier names or prices in atomic orders can cause printing issues. See Manage orders data.

How can I create orders in Clover from a third-party app?

You can use the Clover REST API to create orders programmatically from your app. This requires merchant OAuth authorization and proper use of the Atomic order endpoint. Once authorized, your app can push orders directly into the merchant’s Clover account.

How can I add a test order to my sandbox app?

Send a POST request to the /orders endpoint to create test orders in the sandbox. Make sure your request includes required fields, such as the merchant_id, access_token, and valid order data. You can also explore custom orders or follow the Build an order cart recipe for structured examples.

Why aren’t custom orders displaying on the Clover Go app?

Orders created using the REST API may appear on the Merchant Dashboard but not on Clover Go or POS apps if they lack required fields. To ensure visibility, use the Atomic order endpoint with valid Clover inventory items. Include complete order details: line items, modifiers, and correct state (example: open). Custom orders with minimal data (example: total and state) may not sync properly across devices.

How can I retrieve orders for the last 3 years when the Clover API limits results to 1000 orders?

Clover Orders API enforces a limit of 1000 records per request. To pull historical data:

Use pagination with the offset parameter to retrieve data in batches.
Apply date filters using createdTime in milliseconds since epoch (not seconds). For example: https://api.clover.com/v3/merchants/{merchantId}/orders?filter=createdTime>=1698796800000&filter=createdTime<=1701388799000&limit=100&offset=0
Loop through offsets until all records are retrieved. For large datasets (such as 3 years), break queries into smaller time ranges (monthly or quarterly) to avoid timeouts and improve performance. See Clover API limits documentation for details.