Booking-related custom attributes are used to store seller-specific or application-specific properties or metadata for a booking.
A custom attribute is represented by a CustomAttribute object that takes a custom attribute value of the type specified in the corresponding custom attribute definition. The CustomAttribute
and the corresponding CustomAttributeDefinition objects share the same key
value and the visibility
setting.
After the definition is created, the custom attribute can be set for bookings. For an overview of how booking-related custom attributes work, see Custom Attributes for Bookings.
Custom attributes related to a specific booking in a seller account are accessible using the following URL path:
.../v2/bookings/{booking_id}/custom-attributes
An individual custom attribute is accessible with the key
parameter appended to the URL path. If the requesting application isn't the definition owner, key
is a qualified key.
.../v2/bookings/{booking_id}/custom-attributes/{key}
The following example shows a CustomAttribute
object:
{
"custom_attribute": {
"key": "favorite-drink",
"version": 1,
"updated_at": "2022-11-16T00:07:20Z",
"value": "Mango Juice",
"created_at": "2022-11-16T00:07:20Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
A custom attribute has the following core properties:
Field | Description |
---|---|
key | The identifier for the custom attribute, which is obtained from the custom attribute definition. If the requesting application isn't the definition owner, the key is a qualified key. For more information, see Qualified keys. |
version | The version number of the custom attribute. The version number is initially set to 1 and incremented each time the custom attribute value is updated. Include this field in upsert operations to enable optimistic concurrency control and in read operations for strong consistency. |
visibility | The level of access that other applications have to the custom attribute. Custom attributes obtain this setting from the visibility field of the current version of the definition. |
definition | The CustomAttributeDefinition object that defines properties for the custom attribute. This field is included if the custom attribute is retrieved using the with_definition or with_definitions query parameter set to true . |
value | The value of the custom attribute, which must conform to the schema specified by the definition. For more information, see Value data types. The size of this field can't exceed 5 KB. |
When working with custom attributes owned by other applications, you must provide a qualified key for the following endpoints:
UpsertBookingCustomAttribute
BulkUpsertBookingCustomAttributes
RetrieveBookingCustomAttribute
DeleteBookingCustomAttribute
BulkDeleteBookingCustomAttributes
Square generates a qualified key in the {application ID}:{key}
format, using the application ID of the definition owner and the key
that was provided when the definition was created.
The following example is a qualified key generated for a third-party application:
sq0idp-BuahoY39o1X-GPxRRUWc0A:businessEmail
You can call the following endpoints to get a qualified key for an object created by another application:
ListBookingCustomAttributeDefinitions - Custom attributes use the same
key
as the corresponding custom attribute definition.ListBookingCustomAttributes - Only custom attributes that have a value are returned. If the
?with_definitions=true
query expression is included in the request, custom attribute definitions are also returned. For more information, see List booking custom attributes.
Square returns qualified keys for custom attributes and custom attribute definitions when the requesting application isn't the definition owner.
Note
In addition, the visibility
setting of the custom attribute must be VISIBILITY_READ_ONLY
or VISIBILITY_READ_WRITE_VALUES
. For more information, see Access control.
The following data types are supported for booking-related custom attributes:
Data type | Example value |
---|---|
String | "Nellie" "The quick brown fox." |
"[email protected]" | |
PhoneNumber | "+12085551234" |
Address | { "address_line_1": "Chez Mireille COPEAU Apartment 3", "address_line_2": "Entrée A Bâtiment Jonquille", "postal_code": "33380 MIOS", "locality": "CAUDOS", "country": "FR" } |
Date | "2022-05-12" |
Boolean | true false |
Number | "48" "12.3" |
Selection | [ "6b96fba7-d8a5-ae72-48f4-8c3ee875633f", "46c2716e-f559-4b75-c015-764897e3c4a0" ] |
Note
For more information about these data types, including constraints and example requests for setting custom attribute values, see Upsert request examples for each data type.
The data type of a custom attribute is specified by the schema
field of the custom attribute definition. You can call the following endpoints to retrieve a definition:
RetrieveBookingCustomAttribute using the
?with_definition=true
query expression. For more information, see Retrieve a booking custom attribute.
All data types except Selection
are specified using a simple URL reference to an object hosted on the Square CDN. A Selection
data type provides additional information.
The following is an example String
-type custom attribute definition:
{
"custom_attribute_definition": {
"key": "favorite-drink",
"name": "Favorite Drink",
"description": "The favorite drink of the customer",
"version": 1,
"updated_at": "2022-11-16T02:41:37Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-11-16T02:41:37Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
The following is an excerpt of an example Selection
-type custom attribute definition:
{ "custom_attribute_definition": { ... "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "maxItems": 3, "type": "array", "uniqueItems": true, "items": { "names": [ "Option 1", "Option 2", "Option 3" ], "enum": [ "9492bdda-ab4d-4eeb-8496-0986c8f78499", // UUID for "Option 1" "6b96fba7-d8a5-ae72-48f4-8c3ee875633f", // UUID for "Option 2" "4032c1a2-d749-4c75-9c30-be6472cd2e08" // UUID for "Option 3" ] } }, ... } }
Note the following:
- The
maxItems
field represents the maximum number of allowed selections for the custom attribute value. - The
items
field contains two arrays:names
andenum
. The options in thenames
field map by index to the UUIDs in theenum
field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.
This mapping is used to set the custom attribute value. For example, the value of the following custom attribute maps to option 2:
{
"custom_attribute": {
"key": "favoritebook",
"version": 1,
"updated_at": "2022-11-16T00:07:20Z",
"value": [
"6b96fba7-d8a5-ae72-48f4-8c3ee875633f"
],
"created_at": "2022-11-16T00:07:20Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
For more example UpsertBoookingCustomAttribute
requests, see Upsert request examples for each data type.
To set the value of a custom attribute for a booking, call UpsertBookingCustomAttribute and provide the following information:
booking_id
- Theid
of the Booking object to add the custom attribute to.key
- Thekey
of the custom attribute to create or update.If the requesting application is the definition owner, use the
key
that was provided when the definition was created.If the requesting application isn't the definition owner, use the qualified key. The
visibility
of the custom attribute must beVISIBILITY_READ_WRITE_VALUES
. For more information, see Qualified keys.
custom_attribute
- The custom attribute with the following fields:value
- Thevalue
of the custom attribute, which must conform to theschema
specified by the definition. For more information, see Value data types.version
- The current version of the custom attribute, optionally included to enable optimistic concurrency control when updating a value that was previously set for the booking. If the specified version is earlier than the current version of the custom attribute, the request fails with aCONFLICT
error. If the specified version is later than the current version, Square returns aBAD_REQUEST
error.
idempotency_key
- A unique ID for the request that can be optionally included to ensure idempotency.
The following example request sets the value for a String
-type custom attribute. The key
in this example is favoritebook
.
Upsert booking custom attribute
The following is an example response:
{
"custom_attribute": {
"key": "favoritebook",
"version": 1,
"updated_at": "2022-11-16T00:07:20Z",
"value": "Dune",
"created_at": "2022-11-16T00:07:20Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
During upsert operations, Square validates the provided value against the schema
specified by the definition.
After a custom attribute is upserted, Square invokes the booking.custom_attribute.owned.updated
and booking.custom_attribute.visible.updated
webhooks.
You can set a corresponding custom attribute for a booking by providing a value
that conforms to the schema
specified by the custom attribute definition. The size of this field can't exceed 5 KB. For information about getting the schema
, see Value data types.
The following sections contain UpsertBookingCustomAttribute
requests for each supported data type.
A string with up to 1000 UTF-8 characters. Empty strings are allowed.
Upsert booking custom attribute
An email address consisting of ASCII characters that matches the regular expression for the HTML5 email
type.
Upsert booking custom attribute
Note
The Email
data type for booking custom attributes takes a string value.
A string representation of a phone number in E.164 format. For example, +17895551234
.
Upsert booking custom attribute
Note
The PhoneNumber
data type for booking custom attributes takes a string value.
An Address object. For information about Address
fields, see Working with Addresses. You must provide a complete Address
object in every upsert request.
Upsert booking custom attribute
A date in ISO 8601 format: YYYY-MM-DD
.
Upsert booking custom attribute
Note
The Date
data type for booking custom attributes takes a string value.
A string representation of the date and time in the ISO 8601 format, starting with the year, followed by the month, day, hour, minutes, seconds, and milliseconds. For example, 2022-07-10 15:00:00.000
.
Upsert booking custom attribute
Note
The DateType
data type for booking custom attributes takes a string value.
A true
or false
value. A Toggle custom field created by sellers in Square Appointments is a Boolean.
Upsert booking custom attribute
A string representation of an integer or decimal with up to 5 digits of precision. Negative numbers are denoted using a -
prefix. The absolute value cannot exceed (2^63-1)/10^5 or 92233720368547.
Upsert booking custom attribute
Note
The Number
data type for booking custom attributes takes a string value.
A string representation of duration as defined by the ISO 8601 ABNF.
Upsert booking custom attribute
Note
The Duration
data type for booking custom attributes takes a string value.
A selection from a set of named options.
When working with a Selection
-type custom attribute, you need to get the schema
from the custom attribute definition. The schema
shows the mapping between the named options and Square-assigned UUIDs and the maximum number of allowed selections.
Reading the schema
The following is an excerpt of an example Selection
-type custom attribute definition:
{ "custom_attribute_definition": { ... "schema": { "$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json", "maxItems": 3, "type": "array", "uniqueItems": true, "items": { "names": [ "Option 1", "Option 2", "Option 3" ], "enum": [ "9492bdda-ab4d-4eeb-8496-0986c8f78499", // UUID for "Option 1" "6b96fba7-d8a5-ae72-48f4-8c3ee875633f", // UUID for "Option 2" "4032c1a2-d749-4c75-9c30-be6472cd2e08" // UUID for "Option 3" ] } }, ... } }
Note the following:
The
maxItems
field represents the maximum number of allowed selections for the custom attribute value.The
items
field contains two arrays:names
andenum
. The options in thenames
field map by index to the UUIDs in theenum
field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.
Setting a selection value
To set a selection value for a booking, you provide the target UUID (that maps to the target named option) in the value
field. For this data type, value
is an array that can contain zero or more UUIDs, up to the number specified in maxItems
.
The following example request sets two selections for a custom attribute by providing two UUIDs:
Upsert booking custom attribute
The following example request sets an empty selection by providing an empty array:
Upsert booking custom attribute
To create or update one or more custom attributes for one or more bookings, call BulkUpsertBookingCustomAttributes. This endpoint accepts a values
map with 1 to 25 objects that each contain:
- An arbitrary ID for the individual upsert request, which corresponds to an entry in the response that has the same ID. The ID must be unique within the
BulkUpsertBookingCustomAttributes
request. - An individual upsert request with the information needed to create or update a custom attribute for a booking.
The following example includes two upsert requests that set two custom attributes for two bookings:
{
"values": {
"id1": {
"custom_attribute": {
"key": "favoritebook",
"value": "Alice in Wonderland"
},
"booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
"idempotency_key": "{UNIQUE_KEY}"
},
"id2": {
"custom_attribute": {
"key": "favoritemovie",
"value": "Brazil",
"version": 3 // Only supported when updating an existing value
},
"booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
"idempotency_key": "{UNIQUE_KEY}"
}
}
}
During upsert operations, Square validates each provided value against the schema
specified by the definition. The optional version
field is only supported for update operations.
Did you know?
If you're providing idempotency keys, you can use them as the arbitrary ID for individual upsert requests.
An individual upsert request contains the information needed to set the value of a custom attribute for a booking. Each request includes the following fields:
booking_id
- Theid
of the targeted Booking object to set or update the custom attribute.custom_attribute
- The custom attribute with following fields:key
- The key of the custom attribute to set or update.If the requesting application is the definition owner, use the
key
that was provided when the definition was created.If the requesting application isn't the definition owner, use the qualified key. The
visibility
of the custom attribute must beVISIBILITY_READ_WRITE_VALUES
. For more information, see Qualified keys.
value
- The value of the custom attribute, which must conform to theschema
specified by the definition. For more information, see Value data types. The size of this field can't exceed 5 KB.version
- The current version of the custom attribute, which is optionally included to enable optimistic concurrency control when updating a value that was previously set for the booking. If the specified version is earlier than the current version of the custom attribute, the request fails with aCONFLICT
error. If the specified version is later than the current version, Square returns aBAD_REQUEST
error.
idempotency_key
- A unique ID for the individual request that can be optionally included to ensure idempotency.
The following example BulkUpsertBookingCustomAttributes
request includes five individual upsert requests:
Bulk upsert booking custom attributes
The following is an example response. Note that the errors
field is returned for any individual requests that fail:
{
"values": {
"id2": {
"booking_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
"custom_attribute": {
"key": "favoritebook",
"version": 3,
"updated_at": "2022-11-16T20:16:23Z",
"value": "Through the Looking Glass",
"created_at": "2022-11-16T10:20:35Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
},
"id1": {
"booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
"custom_attribute": {
"key": "favoritebook",
"version": 1,
"updated_at": "2022-11-16T00:16:23Z",
"value": "Dune",
"created_at": "2022-11-16T00:16:23Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
},
"id3": {
"errors": [
{
"code": "CONFLICT",
"detail": "Attempting to write to version 3, but current version is 4",
"field": "version",
"category": "INVALID_REQUEST_ERROR"
}
]
},
"id4": {
"booking_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
"custom_attribute": {
"key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
"version": 1,
"updated_at": "2022-11-16T16:16:23Z",
"value": "10.5",
"created_at": "2022-11-16T13:14:47Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
},
"id5": {
"booking_id": "70548QG1HN43B05G0KCZ4MMC1G",
"custom_attribute": {
"key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail",
"version": 2,
"updated_at": "2022-11-16T04:16:23Z",
"value": "[email protected]",
"created_at": "2022-11-16T03:51:18Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
}
}
Individual upsert requests aren't guaranteed to be returned in the same order. Each upsert response has the same ID as the corresponding upsert request, so you can use the ID to map individual requests and responses.
After each custom attribute is set or updated, Square invokes the booking.custom_attribute.owned.updated
and booking.custom_attribute.visible.updated
webhooks.
To list the custom attributes that are set on a booking, call ListBookingCustomAttributes and provide the following information:
booking_id
- Theid
of the Booking object that represents the target booking.with_definitions
- Indicates whether to return the custom attribute definition in thedefinition
field of each custom attribute. Set this parameter totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.limit
- The maximum page size of 1 to 100 results to return in the response. The default value is 20.If the results are paged, the
cursor
field in the response contains a value that you can send with thecursor
query parameter to get the next page of results.
The following example request includes the limit
query parameter:
List booking custom attributes
When all pages are retrieved, the results include:
All custom attributes owned by the requesting application that have a value. The
key
for these custom attributes is thekey
that was provided for the definition.All custom attributes owned by other applications that have a value and a
visibility
setting ofVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. Thekey
for these custom attributes is a qualified key. For more information, see Qualified keys.A custom attribute is owned by the application that created the corresponding definition.
The following is an example response:
{
"custom_attributes": [
{
"key": "entity-id",
"version": 1,
"updated_at": "2022-11-16T09:44:42Z",
"value": "mbj_004508",
"created_at": "2022-11-16T09:44:42Z",
"visibility": "VISIBILITY_HIDDEN"
},
{
"key": "favoritebook",
"version": 3,
"updated_at": "2022-11-16T10:16:23Z",
"value": "Through the Looking Glass",
"created_at": "2022-11-16T08:20:35Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "sq0idp-BuahoY39o1X-GPxRRUWc0A:businessAddress",
"version": 2,
"updated_at": "2022-11-16T17:40:28Z",
"value": {
"address_line_1": "1455 Market Street",
"postal_code": "94103",
"country": "US",
"administrative_district_level_1": "California",
"locality": "San Francisco"
},
"created_at": "2022-11-16T17:08:57Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
{
"key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
"version": 4,
"updated_at": "2022-11-16T00:16:23Z",
"value": "10.5",
"created_at": "2022-11-16T00:14:47Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
],
"cursor": "O5tF0DmcskdGTrPOAPjlIL...BxACXlOQYbdKq0RC4LZ"
}
The following example request includes the with_definitions
query parameter set to true
:
List booking custom attributes
The following is an excerpt of an example response that shows the custom attribute definition in the definition
field:
{
"custom_attributes": [
{
"key": "entity-id",
"version": 1,
"definition": {
"key": "entity-id",
"name": "Entity ID",
"version": 1,
"updated_at": "2022-11-16T23:23:30Z",
"schema": {
"$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
},
"created_at": "2022-11-16T23:23:30Z",
"visibility": "VISIBILITY_HIDDEN"
},
"updated_at": "2022-10-19T09:44:42Z",
"value": "mbj_004508",
"created_at": "2022-10-19T09:44:42Z",
"visibility": "VISIBILITY_HIDDEN"
},
...
]
}
If no custom attributes are found, Square returns a response containing an empty errors
object.
{
"errors": {}
}
To retrieve a custom attribute associated with a booking, call RetrieveBookingCustomAttribute and provide the following information:
booking_id
- Theid
of the Booking object that represents the target booking.key
- Thekey
of the custom attribute to retrieve.If the requesting application is the definition owner, use the
key
that was provided when the definition was created.If the requesting application isn't the definition owner, use the qualified key. The
visibility
of the custom attribute must beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. For more information, see Qualified keys.
with_definition
- Indicates whether to return the custom attribute definition in thedefinition
field of the custom attribute. Set this parameter totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.version
- The current version of the custom attribute, which is optionally included for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a400 BAD_REQUEST
error.
The following is an example request:
Retrieve booking custom attribute
The following is an example response for an Address
-type custom attribute. The value
field contains the value of the custom attribute.
{
"custom_attribute": {
"key": "sq0idp-BuahoY39o1X-GPxRRUWc0A:bca-address",
"version": 1,
"updated_at": "2022-11-16T17:08:57Z",
"value": {
"address_line_1": "43 Main Street",
"address_line_2": "The Liberties",
"locality": "Dublin 20",
"administrative_district_level_1": "Co. Dublin",
"postal_code": "D08XK58",
"country": "IE"
},
"created_at": "2022-11-16T17:08:57Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
The following example request includes the with_definition
query parameter:
Retrieve booking custom attribute
The following example response shows the custom attribute definition in the definition
field. This example defines a Selection
-type custom attribute. The mapping information in the schema.items
field is used to determine the custom attribute value.
The names
field contains the named options and the enum
field contains the corresponding Square-assigned UUIDs. The named options map by index to the UUIDs. The first option maps to the first UUID, the second option maps to the second UUID, and so on. Therefore, the UUID in the value
field of this custom attribute maps to the Small option.
{
"custom_attribute": {
"key": "bca-select-size",
"version": 1,
"definition": {
"key": "bca-select-size",
"name": "Default size",
"description": "The default size ordered by the customer.",
"version": 1,
"updated_at": "2022-11-16T00:27:17Z",
"schema": {
"$schema": "https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json",
"maxItems": 1,
"type": "array",
"uniqueItems": true,
"items": {
"names": [
"Small",
"Medium",
"Large"
],
"enum": [
"1a052285-7224-4d25-9232-69f941bb0612",
"4034d1bb-ff6c-4f7f-9108-a01625e8aadd",
"fb27f80b-24e1-463b-9aa1-d32fcec6b22a"
]
}
},
"created_at": "2022-11-16T00:27:17Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
},
"updated_at": "2022-11-16T16:19:07Z",
"value": [
"1a052285-7224-4d25-9232-69f941bb0612"
],
"created_at": "2022-11-16T16:19:07Z",
"visibility": "VISIBILITY_READ_WRITE_VALUES"
}
}
If the custom attribute isn't set for the specified booking, Square returns the following response:
{
"errors": [
{
"code": "NOT_FOUND",
"detail": "The requested Value `{key}` is not found",
"category": "INVALID_REQUEST_ERROR"
}
]
}
If the custom attribute isn't available for bookings in the seller account, Square returns the following response:
{
"errors": [
{
"code": "BAD_REQUEST",
"detail": "No matching definition found for value",
"field": "key",
"category": "INVALID_REQUEST_ERROR"
}
]
}
To delete a custom attribute from a booking, call DeleteBookingCustomAttribute and provide the following information:
booking_id
- Theid
of the Booking object that represents the target booking.key
- Thekey
of the custom attribute to delete.If the requesting application is the definition owner, use the
key
that was provided when the definition was created.If the requesting application isn't the definition owner, use the qualified key. The
visibility
of the custom attribute must beVISIBILITY_READ_WRITE_VALUES
. For more information, see Qualified keys.
The following is an example request:
Delete booking custom attribute
If the operation is successful, Square returns a response containing an empty errors
object:
{
"errors": {}
}
To delete all custom attributes of one or more bookings in a single request, call the BulkDeleteBookingCustomAttributes.
After a custom attribute is deleted, Square invokes the booking.custom_attribute.owned.deleted
and booking.custom_attribute.visible.deleted
webhooks.