Print 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 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
.
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.
Updated 9 months ago