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.

Watch video: Print orders

Prerequisites

• Required permissions—To interact with printer functions, you need the:
  • Write orders permission to request for a print event.
  • Read orders permission to retrieve print events.
• Use the Get a list of orders endpoint to get the orderId.
• Generate a merchant-specific test API token in sandbox.

Print an order to the default firing device

1. Send a POST request to the /v3/merchants/{mId}/print_event endpoint
2. Enter the required information—mId and orderId.
3. Set the Authorization header as Bearer token type, and enter the test API token.

The 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, and the event state and time data.

Request example—Print an order

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/print_event' \
  --header 'authorization: {access_token}' \
  --header 'content-type: application/json' \
  --data '{
    "orderRef": {
      "id": "Y8TNWGTYHVP7G"
    }
  }'

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

Webhook notifications

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. For more information, see Use webhooks.

Get the status of a recent print job

Print jobs are short-lived, so the Get a print event by ID endpoint only returns a response for jobs that are in the CREATED, PRINTING, or FAILED state. 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.

1. Send a GET request to the /v3/merchants/{mId}/print_event/{eventId} endpoint.
2. Enter the required information—mId and eventId.
3. Set the Authorization header as Bearer token type, and enter the test API token.

The endpoint returns information about a specific print job.

Request example—Get status of a print event

curl --request GET \
  --url https://apisandbox.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
}

Get support

• For frequently asked questions, see Devices and Printers.
• For questions and feedback, send an email to the Clover Developer Relations (DevRel) team.
• To join our developer communications mailing list, Sign up for Developer Announcements.

Related topics

• Manage orders data
• Submit a print request to the merchant's default order printer endpoint
• Get a print event by its ID endpoint