TerminalActions

Create and query Square Terminal action requests.

Table Specific Information

Select

The add-in uses the Square API to filter the results by the following columns and operators while the rest of the filter is executed client-side within the add-in.

Id supports the following operator: =.
CreatedAt supports the following operators: =, >=, <=, >, <.
DeviceId supports the following operator: =.
Status supports the following operator: =.
Type supports the following operator: =.

Retrieve all terminal actions:

SELECT * FROM TerminalActions

Retrieve a specific terminal action:

SELECT * FROM TerminalActions WHERE Id = 'action_id_here'

Retrieve terminal actions for a specific device:

SELECT * FROM TerminalActions WHERE DeviceId = 'DEVICE_ID'

Insert

To create a terminal action, you must specify the DeviceId, Type, and IdempotencyKey columns.

INSERT INTO TerminalActions (DeviceId, Type, IdempotencyKey) VALUES ('DEVICE_ID', 'PING', 'unique-idempotency-key')

To create a CHECKOUT terminal action, specify CheckoutOptions with at least amount_money:

INSERT INTO TerminalActions (DeviceId, IdempotencyKey, Type, DeadlineDuration, CheckoutOptions) VALUES ('DEVICE_ID', 'unique-idempotency-key', 'CHECKOUT', 'PT5M', '{"amount_money":{"amount":100,"currency":"USD"}}')

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	The unique ID of this Terminal action.
DeviceId	String	False	The unique Id of the device intended for this TerminalAction. The Id can be retrieved from /v2/devices api.
Type	String	False	Represents the type of action to be applied to the `TerminalAction`. The allowed values are QR_CODE, PING, SAVE_CARD, SIGNATURE, CONFIRMATION, RECEIPT, DATA_COLLECTION, SELECT, CHECKOUT.
DeadlineDuration	String	False	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.
AwaitNextAction	Boolean	False	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.
SaveCardOptions	String	False	Describes configuration for the save-card action. Requires SAVE_CARD type. Contains customer_id and reference_id.
ConfirmationOptions	String	False	Describes configuration for the confirmation action. Requires CONFIRMATION type. Contains title, body, agree_button_text, disagree_button_text, and the buyer decision.
ReceiptOptions	String	False	Describes configuration for the receipt action. Requires RECEIPT type. Contains payment_id, print_only, and is_duplicate.
SignatureOptions	String	False	Describes configuration for the signature capture action. Requires SIGNATURE type. Contains title, body, and the collected signature image.
QrCodeOptions	String	False	Describes configuration for the QR code action. Requires QR_CODE type. Contains title, body, and barcode_contents.
Status	String	True	The status of the TerminalAction. Options: PENDING, IN_PROGRESS, CANCEL_REQUESTED, CANCELED, COMPLETED. The allowed values are PENDING, IN_PROGRESS, CANCEL_REQUESTED, CANCELED, COMPLETED.
LocationId	String	True	The location of the device where the `TerminalAction` was directed.
AppId	String	True	The ID of the application that created the action.
CancelReason	String	True	The reason why TerminalAction is canceled. Present if the status is CANCELED. The allowed values are BUYER_CANCELED, SELLER_CANCELED, TIMED_OUT.
CreatedAt	Datetime	True	The time when the TerminalAction was created as an RFC 3339 timestamp.
UpdatedAt	Datetime	True	The time when the TerminalAction was last updated as an RFC 3339 timestamp.
AwaitNextActionDuration	String	False	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. Maximum: 5 minutes.
DataCollectionOptions	String	False	Describes configuration for the data collection action. Requires DATA_COLLECTION type. Contains title, body, input_type (EMAIL or PHONE_NUMBER), and the collected buyer input.
SelectOptions	String	False	Describes configuration for the select action. Requires SELECT type. Contains title, body, a list of options (2-5), and the buyer selected option.
DeviceMetadata	String	True	Details about the Terminal that received the action request (such as battery level, operating system version, and network connection settings). Only available for PING action type.
CheckoutOptions	String	False	Describes configuration for the checkout action. Requires CHECKOUT type. Contains amount_money (amount and currency), reference_id, note, order_id, payment_type, payment_options, and tip_money.

Pseudocolumns

Pseudo column fields are used in the WHERE clause of SELECT statements (unless stated otherwise) and offer a more granular control over the tuples that are returned from the data source.