Print orders with the REST API

United States

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.

More questions?

See FAQs page for frequently asked questions related to Devices and Printers. Additionally, visit our Developer Community to see if your question has already been answered. Your initial requests should always begin at this forum which is highly visible to the Clover team and our developer community.