Custom attributes for Booking objects store properties or metadata (which can be added to the
Booking objects to support custom business logic) that aren't available in the Square-defined
For example, you might want to associate a specific genre of background music with a particular booking. The customer can choose the selected genre to be played during a booked event. Such a scenario involves the following tasks:
- Create a custom attribute definition with at least a name and a key. The name and key values can be
- Create a new booking for a wedding reception or select an existing one to assign a custom attribute to.
- Create a custom attribute of
Ambient Musicwith the following:
- The key (
ambient-music) as defined in the custom attribute definition.
- The booking ID of the Booking object for the reserved wedding reception.
- A value (
Jazz) of the type as specified in the custom attribute definition.
- The key (
At the booked event, the service provider can review the
Ambient Music custom attribute to choose the music genre or let an application retrieve the
Ambient Music custom attribute and play the selected background music. You can use the Booking Custom Attributes API to define, update, and set custom attributes for bookings.
In this topic, you learn how to use the API to define and manage a custom attribute definition and to create and update a custom attribute for a booking. For general discussions about custom attributes, see Custom Attributes Overview.
In general, using the API to enable custom attributes for a booking involves the following types of programming tasks:
keyvalue uniquely identifies the custom attribute definition and the corresponding custom attribute.
schemafield specifies the format of the custom attribute value.
visibilityfield defines how the custom attribute can be accessed by other applications.
Call UpsertBookingCustomAttribute to set a CustomAttribute object for a booking according to the custom attribute definition, specifying the
value, and possibly other field values in the input:
keyfield must be assigned the same value as the
keyfield of the corresponding
booking_idis the ID of the Booking object to associate the custom attribute with.
valuefield takes an assigned value of the custom attribute. Its format must conform to the schema of the corresponding
Retrieve one or more custom attributes from a booking and perform appropriate operations supporting the retrieved custom attributes.
The following example shows how to define an
Ambient Music custom attribute of the
Create booking custom attribute definition
key identifier and
visibility setting that you specify for the definition are also used by corresponding custom attributes. The
visibility setting determines the access level that other applications have to view or update the definition and corresponding custom attributes.
After a custom attribute definition is created, you can create the custom attribute based on the definition and set the custom attribute on a booking in the seller account. To create and set a custom attribute for a booking, call UpsertBookingCustomAttribute.
The following example shows how to create and set the
Ambient Music custom attribute on a specific booking. Note the following:
booking_idpath parameter specifies the associated booking.
keypath parameter (
ambient-music) must match the
keyfield value of the corresponding custom attribute definition of
valuebody parameter in the request assigns a value to the custom attribute. This value must conform to the
schemaspecification stated in the custom attribute definition. In this example, the value (
"Jazz") is of the
Upsert booking custom attribute
To retrieve the custom attribute set on a booking, call RetrieveBookingCustomAttribute, specifying the ID of the booking and the key of the custom attribute.
The following example shows how to retrieve the
Ambient Music custom attribute (identified by the
key parameter) for a specified booking (identified by
Retrieve booking custom attribute
The successful request returns in the response a payload similar to the following:
You can include the
?with_definition=true query parameter in the request URL to have the corresponding custom attribute definition returned in the same call. This is useful, for example, if you want to inspect in details the shape and meaning of the custom attribute.
The Booking Custom Attributes API supports the following operations.
- Create a custom attribute definition for bookings
- Update a booking custom attribute definition
- List booking custom attribute definitions
- Retrieve a booking custom attribute definition
- Delete a booking custom attribute definition
- Create or update a booking custom attribute (upsert)
- Bulk create or update booking custom attributes (bulk upsert)
- List booking custom attributes
- Retrieve a booking custom attribute
- Delete a booking custom attribute
The data type of a custom attribute is specified in the
schema field of the custom attribute definition. For all data types except
Selection, this field contains a simple URL reference to a schema object hosted on the Square CDN.
Booking-related custom attributes support the following data types:
For information about defining the data type for a booking-related custom attribute, see Specifying the schema.
CreateBookingCustomAttributeDefinition request is scoped to a specific seller. Creating a definition makes the corresponding custom attribute available to all bookings in the seller account.
To make the custom attribute available to other sellers, you must call
CreateBookingCustomAttributeDefinition on behalf of each target seller. Using OAuth, you can do so by calling this endpoint for each seller using their access token.
You can reuse the same
key for your custom attribute definition across sellers. The
key must be unique for your application but not for a given seller. However, if you provide a
name, it must be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller.
The application that creates a custom attribute definition is the definition owner. The definition owner always has
WRITE permissions to the definition and all instances of the corresponding custom attribute.
visibility specified by a custom attribute definition determines how other applications that make calls on behalf of a seller can access the definition and corresponding custom attributes.
The following table shows the access permitted to other applications by each supported
To access custom attributes or definitions owned by other applications, the following conditions must be met:
visibilityfield must be set to one of the following:
VISIBILITY_READ_ONLY- Allows other applications to view the definition and corresponding custom attributes.
VISIBILITY_READ_WRITE_VALUES- Additionally allows other applications to set the value of the custom attribute for bookings or delete the custom attribute from bookings.
The requesting application must use theof a custom attribute for the following requests:
To obtain a qualified key, call
ListBookingCustomAttributes. These endpoints return qualified keys for custom attribute definitions and custom attributes that are owned by other applications and visible to your application. For more information, see List booking custom attribute definitions and List booking custom attributes.
You can subscribe to receive notifications for booking-related custom attribute events. Each event provides two options that allow you to choose when Square sends notifications:
.ownedevent notifications are sent when changes are made to custom attribute definitions and custom attributes that are owned by your application. A custom attribute definition is owned by the application that created it. A custom attribute is owned by the application that created the corresponding custom attribute definition.
.visibleevent notifications are sent when changes are made to custom attribute definitions and custom attributes that are visible to your application. These changes apply to:
- All custom attribute definitions and custom attributes owned by your application.
- All other custom attribute definitions or custom attributes whose
Event payloads for both options contain the same information.
Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:
Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These
.visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you don't need to subscribe to an
.owned event when you subscribe to the corresponding
The following is an example
The following is an example
Note the following:
Your application receives booking custom attribute webhook events if the application has permissions to access the booking associated with custom attribute.
With the buyer-level permission (
APPOINTMENTS_READ), the application receives notifications of custom attribute events for the bookings it created.
With the seller-level permissions (
APPOINTMENTS_ALL_READ), the application receives notifications of all custom attribute events for all bookings in the seller account.
keyof the custom attribute definition or custom attribute in the notification is always the .
If you subscribe to the
.visibleoptions for the same event, Square sends both notifications for changes to custom attribute definitions and custom attributes owned by the subscribing application.
The value of the
data.idin the notification depends on the affected object:
- For custom attribute definition events,
data.idis the qualified key.
- For custom attribute events,
data.idis generated using the qualified key and the ID of the affected booking. This
data.idcannot be used directly with the Booking Custom Attributes API.
- For custom attribute definition events,
The following requirements, limitations, and other considerations apply when working with customer-related custom attributes:
Minimum Square version - Square version 2022-11-16 or later is required to work with the Booking Custom Attributes API.
Sensitive data - Custom attributes are intended to store additional information or store associations with an entity in another system. Don't use custom attributes to store any PCI data, such as credit card details. PII is supported in custom attribute values, but applications that create or read this data should observe applicable privacy laws and data regulations such as requesting the hard deletion of custom attribute data when a GDPR request for erasure is received. Never store secret-level information in a custom attribute. The use of custom attributes is subject to developers adhering to the Square API Data Policy Disclosures.
Unsupported data types - You can only create booking-related custom attribute definitions that specify a
schemafor a supported data type. The following data types aren't supported for booking-related custom attributes:
Search support - The Bookings API doesn't currently support search for custom attributes.
Limits - A seller account can have a maximum of 100 booking-related custom attribute definitions per application.
Unique name - If the
visibilityof a booking-related custom attribute definition is
namemust be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller. This requirement is intended to help sellers differentiate between custom attributes that are visible in the Square Appointments and other Square products.
Maximum value for Number custom attributes - The absolute value of a
Number-type custom attribute cannot exceed (2^63-1)/10^5 or 92233720368547.
OAuth permissions - Applications that use OAuth require
APPOINTMENTS_WRITEpermission to work with buyer-level booking-related custom attributes. Applications that use OAuth require
APPOINTMENTS_ALL_WRITEpermissions to work with seller-level booking-related custom attributes. For more information, see OAuth API Overview and Booking Custom Attributes.
If a seller revokes the permissions of the application that created a custom attribute definition, or if the token expires, the application cannot access the definition or corresponding custom attributes until permissions are restored. However, the definition and custom attributes remain available to other applications according to the
Idempotency - Including an idempotency key in a request guarantees that the request is processed only once. The following endpoints allow you to specify an
You should generate a unique idempotency key for each request. If an idempotency key is reused in requests to the same endpoint on behalf of the same seller, Square returns the response from the first request that was successfully processed using the key. Square doesn't process subsequent requests that use the same key, even if they contain different fields. For more information, see Idempotency.