Printing orders with the REST API

Watch the printing orders demo

Watch Clover's demo on how to print orders. Here's what you'll learn:

  • Print orders on a merchant's default printer using the print_event endpoint
  • Customize order and payment receipts

Print API endpoints

The Print API consists of two endpoints providing access to the printer on a merchant's device. Online ordering or other restaurant-related apps can build features that depend on the ability to print order receipts. The following endpoints can used to interact with the printer functions:

  • POST /v3/merchants/{mId}/print_event (requires the Write orders permission)
  • GET /v3/merchants/{mId}/print_event/{eventId} (requires the Read orders permission)

Your app may also need to use the GET /v3/merchants/{mId}/orders endpoint to get information about existing orders.

Printing an order to the default firing device

To print an order, your app sends a POST request to the /v3/merchants/{mId}/print_event endpoint with a request body including the order ID.

curl --request POST \
  --url{mId}/print_event \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"orderRef": {"id": "Y8TNWGTYHVP7G"}}'

This request is routed to the firing device's order printer or, if they don't have an order printer, to the firing device's onboard printer.


Data flow for order printing

The response includes the event id, the order being printed, the printer handling the request, as well as event state and time data.

  "id": "P5WWTQ44VRY74",
  "orderRef": {
    "id": "4CZ8EH4BEKRXW"
  "deviceRef": {
    "id": "926766ca-5636-8598-e959-6e3c6fe047e1"
  "state": "CREATED",
  "createdTime": 1626454194000,
  "modifiedTime": 1626454194000,
  "printTime": 1626454194000

If you want to confirm that a print job is finished, your app should be subscribed to the order event webhooks. When an order is printed, Clover sets the printed property to true for each order line item. These line item updates are then sent to your app's callback URL as webhook messages.

Getting the status of a recent print job

The GET/v3/merchants/{mId}/print_event/{eventId} endpoint returns information about a specific print job. Print jobs are short lived, so this endpoint only returns a response for jobs that are in the CREATED, PRINTING, or FAILED state.

curl --request GET \
  --url{mId}/print_event/WNSZ2D0WX884W \
  --header 'Accept: application/json'
  "id": "WNSZ2D0WX884W",
  "orderRef": {
    "id": "HQ6Q9WMX944SP"
  "deviceRef": {
    "id": "926766ca-5636-8598-e959-6e3c6fe047e1"
  "state": "PRINTING",
  "createdTime": 1626896196000,
  "modifiedTime": 1626896196000,
  "printTime": 1626896197000

Once a job is printed, the job is discarded and cannot be replayed. If you call this endpoint with the eventId of a job that has been successfully printed, the response is a message indicating The print event is missing.

FAQs and troubleshooting

What happens if the merchant's printer is offline?

If the job does not print within two minutes of the request, a failed printing email is sent to the merchant. This email lets the merchant know the printer is unavailable and gives them a link to an HTML version of the order receipt. When the printer is back online, the order receipt prints as requested.

If a print event is not printed within one hour of the request, Clover deletes the print event of the order. The order itself is not deleted, and the merchant can view it in the Orders app.

Can the merchant change the default firing device/printer at any time?

To select a device, go to Setup > Devices on any Clover device. For default printers, merchants can only change the printer visible on the device.

Can more than one device be configured as a default firing device?

No, the merchant can only select a single default firing device.

What happens if a merchant has a Clover Mini and then they add a Clover Station Duo in the future? Does the default firing device automatically change to the Station Duo?

A new device is not auto-selected until the merchant fully deactivates the Clover Mini. Orders will print on the Mini unless the merchant changes the default firing device to Station Duo.

What Clover devices can be configured as a default firing device?

  • Clover Mini
  • Clover Flex
  • Clover Station 2
  • Clover Station Duo

Can I refire an online order from the Orders app?

Yes, but only if the merchant has an order printer configured for the device on which the user is trying to fire the order.

How does a merchant add order notes to receipts?

Order notes can be enabled in the Setup app. See the merchant help site for more information.

Can a merchant customize their order receipts?

Yes, there are several settings available in the Setup app under Order Receipts:

  • When the order receipt is printed or fired
  • Font size
  • Order numbering (automatic or employee entered)
  • Order notes
  • How to display line items and modifiers
  • Whether to print customer information

Can customers place orders when the merchant's devices or printers are offline?

Yes, the orders will be queued and printed when the printer is available again.

What happens if the default Clover device is replaced?

When the device is deactivated, another device is selected as the default firing device on behalf of the merchant. Merchants can always change the default device in the Setup app.

If the default firing device has more than one order printer connected, can the merchant choose which order printer to fire online orders to?

No, the merchant cannot select an order printer in this case.

Will online orders fire to my kitchen display system if the KDS is configured as the order printer for the default firing device?

Yes, a KDS can be set as a default firing device's order printer.

If a device has multiple order printers connected and an order is reprinted, where is the order reprinted?

A message appears asking merchant which order printer should be used to print the receipt.