Print orders with the REST API

United States

Canada

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 https://sandbox.dev.clover.com/v3/merchants/{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.

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 https://sandbox.dev.clover.com/v3/merchants/{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.

Watch the printing orders demo

Print API endpoints

Printing an order to the default firing device

Getting the status of a recent print job

More questions?