--- title: "CreateTerminalAction" method: POST path: "/v2/terminals/actions" tags: ["Terminal"] --- # CreateTerminalAction `POST /v2/terminals/actions` Creates a Terminal action request and sends it to the specified device. ## Request body - CreateTerminalActionRequest - `idempotency_key` string, required — A unique string that identifies this `CreateAction` request. Keys can be any valid string but must be unique for every `CreateAction` request. See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information. - `action` TerminalAction, required — Represents an action processed by the Square Terminal. - `id` string — A unique ID for this `TerminalAction`. - `device_id` string, nullable — The unique Id of the device intended for this `TerminalAction`. The Id can be retrieved from /v2/devices api. - `deadline_duration` string, nullable — The duration as an RFC 3339 duration, after which the action will be automatically canceled. TerminalActions that are `PENDING` will be automatically `CANCELED` and have a cancellation reason of `TIMED_OUT` Default: 5 minutes from creation Maximum: 5 minutes - `status` string — The status of the `TerminalAction`. Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED` - `cancel_reason` 'BUYER_CANCELED' | 'SELLER_CANCELED' | 'TIMED_OUT' - `created_at` string — The time when the `TerminalAction` was created as an RFC 3339 timestamp. - `updated_at` string — The time when the `TerminalAction` was last updated as an RFC 3339 timestamp. - `app_id` string — The ID of the application that created the action. - `location_id` string — The location id the action is attached to, if a link can be made. - `type` 'QR_CODE' | 'PING' | 'SAVE_CARD' | 'SIGNATURE' | 'CONFIRMATION' | 'RECEIPT' | 'DATA_COLLECTION' | 'SELECT' — Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. - `qr_code_options` QrCodeOptions — Fields to describe the action that displays QR-Codes. - `title` string, required — The title text to display in the QR code flow on the Terminal. - `body` string, required — The body text to display in the QR code flow on the Terminal. - `barcode_contents` string, required — The text representation of the data to show in the QR code as UTF8-encoded data. - `save_card_options` SaveCardOptions — Describes save-card action fields. - `customer_id` string, required — The square-assigned ID of the customer linked to the saved card. - `card_id` string — The id of the created card-on-file. - `reference_id` string, nullable — An optional user-defined reference ID that can be used to associate this `Card` to another entity in an external system. For example, a customer ID generated by a third-party system. - `signature_options` SignatureOptions - `title` string, required — The title text to display in the signature capture flow on the Terminal. - `body` string, required — The body text to display in the signature capture flow on the Terminal. - `signature` SignatureImage[] — An image representation of the collected signature. - `image_type` string — The mime/type of the image data. Use `image/png;base64` for png. - `data` string — The base64 representation of the image. - `confirmation_options` ConfirmationOptions - `title` string, required — The title text to display in the confirmation screen flow on the Terminal. - `body` string, required — The agreement details to display in the confirmation flow on the Terminal. - `agree_button_text` string, required — The button text to display indicating the customer agrees to the displayed terms. - `disagree_button_text` string, nullable — The button text to display indicating the customer does not agree to the displayed terms. - `decision` ConfirmationDecision - `has_agreed` boolean — The buyer's decision to the displayed terms. - `receipt_options` ReceiptOptions — Describes receipt action fields. - `payment_id` string, required — The reference to the Square payment ID for the receipt. - `print_only` boolean, nullable — Instructs the device to print the receipt without displaying the receipt selection screen. Requires `printer_enabled` set to true. Defaults to false. - `is_duplicate` boolean, nullable — Identify the receipt as a reprint rather than an original receipt. Defaults to false. - `data_collection_options` DataCollectionOptions - `title` string, required — The title text to display in the data collection flow on the Terminal. - `body` string, required — The body text to display under the title in the data collection screen flow on the Terminal. - `input_type` 'EMAIL' | 'PHONE_NUMBER', required — Describes the input type of the data. - `collected_data` CollectedData - `input_text` string — The buyer's input text. - `select_options` SelectOptions - `title` string, required — The title text to display in the select flow on the Terminal. - `body` string, required — The body text to display in the select flow on the Terminal. - `options` SelectOption[], required — Represents the buttons/options that should be displayed in the select flow on the Terminal. - `reference_id` string, required — The reference id for the option. - `title` string, required — The title text that displays in the select option button. - `selected_option` SelectOption - `reference_id` string, required — The reference id for the option. - `title` string, required — The title text that displays in the select option button. - `device_metadata` DeviceMetadata - `battery_percentage` string, nullable — The Terminal’s remaining battery percentage, between 1-100. - `charging_state` string, nullable — The current charging state of the Terminal. Options: `CHARGING`, `NOT_CHARGING` - `location_id` string, nullable — The ID of the Square seller business location associated with the Terminal. - `merchant_id` string, nullable — The ID of the Square merchant account that is currently signed-in to the Terminal. - `network_connection_type` string, nullable — The Terminal’s current network connection type. Options: `WIFI`, `ETHERNET` - `payment_region` string, nullable — The country in which the Terminal is authorized to take payments. - `serial_number` string, nullable — The unique identifier assigned to the Terminal, which can be found on the lower back of the device. - `os_version` string, nullable — The current version of the Terminal’s operating system. - `app_version` string, nullable — The current version of the application running on the Terminal. - `wifi_network_name` string, nullable — The name of the Wi-Fi network to which the Terminal is connected. - `wifi_network_strength` string, nullable — The signal strength of the Wi-FI network connection. Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` - `ip_address` string, nullable — The IP address of the Terminal. - `await_next_action` boolean, nullable — Indicates the action will be linked to another action and requires a waiting dialog to be displayed instead of returning to the idle screen on completion of the action. Only supported on SIGNATURE, CONFIRMATION, DATA_COLLECTION, and SELECT types. - `await_next_action_duration` string, nullable — The timeout duration of the waiting dialog as an RFC 3339 duration, after which the waiting dialog will no longer be displayed and the Terminal will return to the idle screen. Default: 5 minutes from when the waiting dialog is displayed Maximum: 5 minutes ## Response `200` Success - CreateTerminalActionResponse - `errors` Error[] — Information on errors encountered during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `action` TerminalAction — Represents an action processed by the Square Terminal. - `id` string — A unique ID for this `TerminalAction`. - `device_id` string, nullable — The unique Id of the device intended for this `TerminalAction`. The Id can be retrieved from /v2/devices api. - `deadline_duration` string, nullable — The duration as an RFC 3339 duration, after which the action will be automatically canceled. TerminalActions that are `PENDING` will be automatically `CANCELED` and have a cancellation reason of `TIMED_OUT` Default: 5 minutes from creation Maximum: 5 minutes - `status` string — The status of the `TerminalAction`. Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED` - `cancel_reason` 'BUYER_CANCELED' | 'SELLER_CANCELED' | 'TIMED_OUT' - `created_at` string — The time when the `TerminalAction` was created as an RFC 3339 timestamp. - `updated_at` string — The time when the `TerminalAction` was last updated as an RFC 3339 timestamp. - `app_id` string — The ID of the application that created the action. - `location_id` string — The location id the action is attached to, if a link can be made. - `type` 'QR_CODE' | 'PING' | 'SAVE_CARD' | 'SIGNATURE' | 'CONFIRMATION' | 'RECEIPT' | 'DATA_COLLECTION' | 'SELECT' — Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum. - `qr_code_options` QrCodeOptions — Fields to describe the action that displays QR-Codes. - `title` string, required — The title text to display in the QR code flow on the Terminal. - `body` string, required — The body text to display in the QR code flow on the Terminal. - `barcode_contents` string, required — The text representation of the data to show in the QR code as UTF8-encoded data. - `save_card_options` SaveCardOptions — Describes save-card action fields. - `customer_id` string, required — The square-assigned ID of the customer linked to the saved card. - `card_id` string — The id of the created card-on-file. - `reference_id` string, nullable — An optional user-defined reference ID that can be used to associate this `Card` to another entity in an external system. For example, a customer ID generated by a third-party system. - `signature_options` SignatureOptions - `title` string, required — The title text to display in the signature capture flow on the Terminal. - `body` string, required — The body text to display in the signature capture flow on the Terminal. - `signature` SignatureImage[] — An image representation of the collected signature. - `image_type` string — The mime/type of the image data. Use `image/png;base64` for png. - `data` string — The base64 representation of the image. - `confirmation_options` ConfirmationOptions - `title` string, required — The title text to display in the confirmation screen flow on the Terminal. - `body` string, required — The agreement details to display in the confirmation flow on the Terminal. - `agree_button_text` string, required — The button text to display indicating the customer agrees to the displayed terms. - `disagree_button_text` string, nullable — The button text to display indicating the customer does not agree to the displayed terms. - `decision` ConfirmationDecision - `has_agreed` boolean — The buyer's decision to the displayed terms. - `receipt_options` ReceiptOptions — Describes receipt action fields. - `payment_id` string, required — The reference to the Square payment ID for the receipt. - `print_only` boolean, nullable — Instructs the device to print the receipt without displaying the receipt selection screen. Requires `printer_enabled` set to true. Defaults to false. - `is_duplicate` boolean, nullable — Identify the receipt as a reprint rather than an original receipt. Defaults to false. - `data_collection_options` DataCollectionOptions - `title` string, required — The title text to display in the data collection flow on the Terminal. - `body` string, required — The body text to display under the title in the data collection screen flow on the Terminal. - `input_type` 'EMAIL' | 'PHONE_NUMBER', required — Describes the input type of the data. - `collected_data` CollectedData - `input_text` string — The buyer's input text. - `select_options` SelectOptions - `title` string, required — The title text to display in the select flow on the Terminal. - `body` string, required — The body text to display in the select flow on the Terminal. - `options` SelectOption[], required — Represents the buttons/options that should be displayed in the select flow on the Terminal. - `reference_id` string, required — The reference id for the option. - `title` string, required — The title text that displays in the select option button. - `selected_option` SelectOption - `reference_id` string, required — The reference id for the option. - `title` string, required — The title text that displays in the select option button. - `device_metadata` DeviceMetadata - `battery_percentage` string, nullable — The Terminal’s remaining battery percentage, between 1-100. - `charging_state` string, nullable — The current charging state of the Terminal. Options: `CHARGING`, `NOT_CHARGING` - `location_id` string, nullable — The ID of the Square seller business location associated with the Terminal. - `merchant_id` string, nullable — The ID of the Square merchant account that is currently signed-in to the Terminal. - `network_connection_type` string, nullable — The Terminal’s current network connection type. Options: `WIFI`, `ETHERNET` - `payment_region` string, nullable — The country in which the Terminal is authorized to take payments. - `serial_number` string, nullable — The unique identifier assigned to the Terminal, which can be found on the lower back of the device. - `os_version` string, nullable — The current version of the Terminal’s operating system. - `app_version` string, nullable — The current version of the application running on the Terminal. - `wifi_network_name` string, nullable — The name of the Wi-Fi network to which the Terminal is connected. - `wifi_network_strength` string, nullable — The signal strength of the Wi-FI network connection. Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT` - `ip_address` string, nullable — The IP address of the Terminal. - `await_next_action` boolean, nullable — Indicates the action will be linked to another action and requires a waiting dialog to be displayed instead of returning to the idle screen on completion of the action. Only supported on SIGNATURE, CONFIRMATION, DATA_COLLECTION, and SELECT types. - `await_next_action_duration` string, nullable — The timeout duration of the waiting dialog as an RFC 3339 duration, after which the waiting dialog will no longer be displayed and the Terminal will return to the idle screen. Default: 5 minutes from when the waiting dialog is displayed Maximum: 5 minutes --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)