Request a tip

United States

To allow a merchant to request a tip from the customer, use the /v1/device/read-tip endpoint.



This endpoint is generally used as part of a transaction flow. See Authorize and capture a tipped payment on screen for instructions to use this endpoint during an auth transaction.


  • POS is connected to the device using a network or cloud connection.
  • Clover device is idle; that is, no payment is being taken.

Request a tip with default settings

The simplest request for a tip includes only the baseAmount of the transaction. This type of request uses the merchant's default tip settings and displays options to the customer.

  1. Construct a request with the amount of the charge that is not captured (uncaptured charge).
  "baseAmount": 3400
  1. Send the baseAmount as a POST request to /v1/device/read-tip.
  2. Required. Include the required headers for your request.
    The tip screen displays the specified amount. After the customer selects a tip amount, a success message displays the tip, and the welcome screen appears.
    "response": 680

Request a tip with custom settings

If you want to override the default tip amounts or percentages and the on-screen messages, you can include additional information in the request body with the baseAmount.

  1. Construct a request with the amount of the uncaptured charge and the custom tipSuggestions you want to display.
  "baseAmount": 1400,
  "tipSuggestions": [
      "name": "One dollar",
      "amount": 100
      "name": "Five dollars",
      "amount": 500
      "name": "Ten percent",
      "percentage": 10
      "name": "Twenty percent",
      "percentage": 20
  1. Send a POST request to /v1/device/read-tip.
    The tip screen displays for the specified amount with the custom tip information. After the customer selects a tip, a success message displays the tip amount.