Advanced Square Terminal Features

The Terminal API provides additional ways for a Square Terminal and a Point of Sale (POS) application to interact. These interactions are called Terminal actions. This topic provides an overview of Terminal actions and how to use them for advanced use cases, including non-payment-related scenarios.


Terminal actions are in beta.

The following prerequisites apply to Terminal actions.

Link to section


  • A Square Terminal paired with a POS application.
  • Applications must have the following OAuth permissions:
    • PAYMENTS_READ for getting or searching for a Terminal action request.
    • PAYMENTS_WRITE for creating or canceling a Terminal action request.
  • Ensure that the Square Terminal software is up to date. On the Square Terminal, choose Settings, choose General, choose About Terminal, and then check the software version. For more information, see the Square Terminal FAQ.
  • Your developer account must be enabled to subscribe to Terminal API action webhooks.
Link to section

Create a Terminal action request

After pairing a Square Terminal using the Devices API, you can create a new CreateTerminalAction request, which is similar to requesting a checkout or refund. The POS application sends a request to Square using the Terminal API. The action request goes to Square, which forwards it to the paired Square Terminal. The request carries the action and prompts the buyer with a screen based on the action type.

When the buyer completes the action on the Square Terminal, the POS application can be notified by a Square webhook or get the action result using the Terminal API.

The following example shows a POST request to create a new Terminal action for saving a card on file:

Create terminal action

Link to section

Search for a Terminal action request

You can retrieve a filtered list of Terminal action requests created by an account by sending a POST request to the SearchTerminalActions endpoint. Terminal action requests are available for 30 days.

The following example shows a request to search for a Terminal action with the device status of PENDING:

Search terminal actions

Link to section

Cancel a Terminal action request

You can send a POST request to cancel a Terminal action if the status of the request permits it or if the request is pending or in progress.

The following example shows a POST request to cancel a Terminal action that takes an action_id in the path parameter:

Cancel terminal action

Link to section

Types of Terminal actions

The Terminal API allows you to create the following Terminal actions:

Link to section

Other advanced features

In addition to Terminal actions, the Terminal API allows sellers to customize the Square Terminal idle screen and showcase their business and brand. For more information, see Customize the Square Terminal Idle Screen.