Create, retrieve, delete, and query custom attributes for Square Bookings. Requires filtering by BookingId.

Table Specific Information

Select

The driver 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 driver.

• Key supports the following operator: =.
• BookingId supports the following operator: =.

Retrieve all custom attributes for a specific booking:

SELECT * FROM BookingCustomAttributes WHERE BookingId = 'booking_id_here'

Retrieve a specific custom attribute for a booking:

SELECT * FROM BookingCustomAttributes WHERE BookingId = 'booking_id_here' AND Key = 'preferred-provider'

Update

Upsert a custom attribute for a booking by providing the BookingId and Key:

UPDATE BookingCustomAttributes SET Value = 'provider_name', BookingId = 'booking_id_here' WHERE Key = 'preferred-provider'

Delete

Delete a custom attribute from a booking by providing the BookingId and Key:

DELETE FROM BookingCustomAttributes WHERE Key = 'preferred-provider' AND BookingId = 'booking_id_here'

Bulk Insert

The maximum BatchSize supported by BookingCustomAttributes is 25.

You can write custom attributes in bulk using TEMP tables. Each staged row identifies one attribute by its BookingId and Key, so a single batch can carry several attributes for the same booking as well as attributes for different bookings. Key is a reserved word, so enclose it in square brackets. Supply BookingId, Key, and Value on every staged row; Version is optional and lets Square reject the write if the attribute has changed since you read it.

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key], Value) VALUES ('N3NCVYY3WS27HF0HKANA3R9FP8', 'favoriteShampoo', 'Spring Fresh')

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key], Value) VALUES ('SY8EMWRNDN3TQDP2H4KS1QWMMM', 'ownsShampoo', 'false')

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key], Value) VALUES ('SY8EMWRNDN3TQDP2H4KS1QWMMM', 'favoriteShampoo', 'Hydro-Cool')

INSERT INTO BookingCustomAttributes SELECT * FROM BookingCustomAttributes#TEMP

Note: Stage the rows through the TEMP table as shown, or supply several rows in a single multi-row VALUES clause. A one-row INSERT is sent as an ordinary single-attribute write rather than as a batch.

Bulk Update

The maximum BatchSize supported by BookingCustomAttributes is 25.

Square serves both bulk INSERT and bulk UPDATE from its bulk upsert endpoint, so a batch creates the attributes that do not yet exist and overwrites the ones that do.

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key], Value) VALUES ('N3NCVYY3WS27HF0HKANA3R9FP8', 'favoriteShampoo', 'Winter Mint')

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key], Value) VALUES ('SY8EMWRNDN3TQDP2H4KS1QWMMM', 'ownsShampoo', 'true')

UPDATE BookingCustomAttributes (BookingId, [Key], Value) SELECT BookingId, [Key], Value FROM BookingCustomAttributes#TEMP

Square reports the outcome of each row in the batch separately. Query LastResultInfo#TEMP after the write to read the per-row result, including the error details for any row that failed.

SELECT * FROM LastResultInfo#TEMP

Bulk Delete

The maximum BatchSize supported by BookingCustomAttributes is 25.

Stage the attributes to remove in a TEMP table, then delete them in a single request. Each staged row needs only BookingId and Key, since those identify the attribute; any other column is ignored for a delete. As with a bulk write, one batch can mix attributes belonging to different bookings.

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key]) VALUES ('N3NCVYY3WS27HF0HKANA3R9FP8', 'favoriteShampoo')

INSERT INTO BookingCustomAttributes#TEMP (BookingId, [Key]) VALUES ('SY8EMWRNDN3TQDP2H4KS1QWMMM', 'ownsShampoo')

DELETE FROM BookingCustomAttributes WHERE EXISTS SELECT BookingId, [Key] FROM BookingCustomAttributes#TEMP

Note: The staged form shown above is required to reach the bulk delete endpoint. A DELETE FROM BookingCustomAttributes WHERE BookingId = '...' AND [Key] = '...' statement removes the same attribute but issues one request per attribute. The same applies to bulk UPDATE, which must also read its rows from the TEMP table.

Columns

Name	Type	ReadOnly	Description
Key [KEY]	String	True	The identifier of the custom attribute definition and its corresponding custom attributes.
BookingId [KEY]	String	True	The ID of the target booking. Required for all operations and used as a URL path parameter.
Value	String	False	The value assigned to the custom attribute. It is validated against the custom attribute definition schema on write operations.
Visibility	String	True	A copy of the visibility field value for the associated custom attribute definition.
Version	Integer	False	The current version of the custom attribute. Incremented when changed. Provide for optimistic concurrency control during updates.
CreatedAt	Datetime	True	The timestamp when the custom attribute was created, in RFC 3339 format.
UpdatedAt	Datetime	True	The timestamp when the custom attribute was created or most recently updated, in RFC 3339 format.
Definition	String	True	A copy of the associated custom attribute definition object. Only set when specified on the request.

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.

Name	Type	Description
IdempotencyKey	String	A unique string that identifies the request. Supported only for UPDATE operations. Maximum length is 45 characters.