---
title: "Get a tip"
method: POST
path: "/v1/device/read-tip"
tags: ["DEVICE"]
---

# Get a tip

`POST /v1/device/read-tip`

Displays a message on a Clover device requesting customer selection of a tip amount or percentage.

## Headers

- `User-Agent` string, required
- `X-Clover-Device-Id` string, required
- `X-POS-Id` string, required
- `X-Clover-Timeout` integer
- `Idempotency-Key` string

## Request body

- TipDisplayRequest — A request to display the tip screen with optional message, base amount and tip configurations.
  - `baseAmount` integer — For percentage tip suggestions, this is the amount the calculated tips will be based upon. This is an integer with 2 decimal points implied, for example 100 = 1.00
  - `tipSuggestions` TipSuggestion[] — A set of tip configurations to use when displaying the tip screen. If omitted defaults will be used. The options 'custom tip' and 'no tip' are always offered.
    - `amount` integer — An absolute amount to use for the suggestion.
    - `name` string — A string to display on the suggestion. If omitted, either the amount of the tip, or the percentage will be displayed.
    - `percentage` integer — A percentage to use when calculating the suggestion.

## Response `200`

The tip screen was displayed to the customer.

- IntegerResponse — This is an integer with 2 decimal points implied, for example 100 = 1.00
  - `response` integer

## Other responses

- `209` — Operation was canceled.
- `400` — The request is invalid, and subsequent calls will continue to fail; do not repeat the call.
- `401` — An invalid bearer token has been provided. The call may be repeated if the provided bearer token is updated.
- `415` — The request is invalid, and contains request data in an unsupported format. This call may be repeated if the content is changed to a supported format.
- `500` — The request processing failed with an unknown error, and the processing state of the operation is indeterminate. Do not repeat the call without additional analysis.
- `501` — The device does not have the ability to respond to the requested operation; do not repeat the call.
- `503` — The device is not available because it is currently servicing another call. This can be repeated at a later time, or cancel may be called to end the current operation.
- `504` — The Device did not respond in a timely manner. This can be repeated at a later time.

---

[API](https://skmtc.net/clover/apis/platform-api.md) · [All operations](https://skmtc.net/clover/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clover/platform-api/versions/08da265101a3/schema)