Display Menu Select Options

Applies to: Terminal API

Learn how to display a menu of options for a buyer to select from on the Square Terminal.

As part of creating custom workflows with the Terminal API, you can create a screen workflow that captures a buyer's selected option from a menu of options. You send a Terminal action request of the SELECT type and the Square Terminal displays a screen with a selection of options. The buyer taps the screen to select an option and the Terminal API collects the selection for the seller's records.

In the request body, you can edit the title and body text that displays on the menu selection screen. You also specify an array of options with reference IDs and title text that describes each option.

The request requires at least two options configured for the menu selection screen, with a maximum of five options.

You can build a screen workflow that prompts the buyer to choose how to receive reminders from the seller or how to choose not to receive reminders.

[An animation of the menu selection screen displayed on the Square Terminal.]

1. Send a Terminal action POST request using the CreateTerminalAction endpoint and specify the SELECT action type. In the select_options body, provide screen text for title and body. For options, provide the reference ID and the title text for each menu select option in the array. The array requires a minimum of two options.

   Create terminal action

   cURL

   The Terminal action response includes an action_id and a PENDING status.

   {
        "action": {
    		"id": "termapia: abcdefg1234567",
        "device_id": "R5WNWB5BKNG9R",
        "deadline_duration": "PT5M",
        "status": "PENDING",
        "created_at": "2022 - 03 - 09 T09: 01: 19.622 Z",
        "updated_at": "2022 - 03 - 09 T09: 03: 06.830 Z",
        "type": "SELECT",
        "app_id": "sq0ids - abcdefg123456789",
        "select_options": {
          "title": "Enroll in reminders",
          "body": "How would you like to be contacted?",
          "options": [
            {
              "reference_id": "Option 1",
              "title": "Text Message"
            },
            {
              "reference_id": "Option 2",
              "title": "Email"
            },
            {
              "reference_id": "Option 3",
              "title": "I don't want to be contacted"
            }
    	   	]
    	  }
     }
   }

   The Square Terminal displays the menu selection screen for the buyer.

   [A Square Terminal showing a screen asking the buyer how they want to receive reminders from the seller.]

   After the buyer selects an option, the Terminal action is put in a COMPLETED state and the Square Terminal displays the idle screen.

2. Send a GET request to see the Terminal action that includes the decision.

   Get terminal action

   cURL

   The response returns the buyer's selected option in the selected_options body. The following response example shows that the buyer selected "Option 1" to enroll in receiving text message reminders.

   {
     "action": {
       "id": "termapia:abcdefg1234567",
       "device_id": "R5WNWB5BKNG9R",
       "deadline_duration": "PT5M",
       "status": "COMPLETED",
       "created_at": "2022-03-09T09:01:19.622Z",
       "updated_at": "2022-03-09T09:03:06.830Z",
       "type": "SELECT",
       "app_id": "sq0ids-abcdefg123456789",
       "select_options": {
          "title": "Sign up",
          "body": "Join our email list to stay up to date",
          "options": [ 
            {
              "reference_id": "Option 1",
              "title": "Text Message"
            },
            {
              "reference_id": "Option 2",
              "title": "Email"
            },
            {
              "reference_id": "Option 3",
              "title": "I do not want to be contacted"
            }
          ],
          "selected_options": {
            "reference_id": "Option 1",
            "title": "Text Message"
         }
       }
     }
   }