Custom Attributes for Bookings

Applies to: Booking Custom Attributes API | OAuth API | Bookings API

Learn how to create and manage custom attributes for Square bookings using the Booking Custom Attributes API.

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 Booking object.

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:

1. Create a custom attribute definition with at least a name and a key. The name and key values can be Ambient Music and ambient-music, respectively.
2. Create a new booking for a wedding reception or select an existing one to assign a custom attribute to.
3. Create a custom attribute of Ambient Music with 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.

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 the following section, 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.

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 schema for a supported data type. The following data types aren't supported for booking-related custom attributes:

  • DateTime
  • Duration

• 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 visibility of a booking-related custom attribute definition is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES, the name must 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_READ or APPOINTMENTS_WRITE permission to work with buyer-level booking-related custom attributes. Applications that use OAuth require APPOINTMENTS_READ and APPOINTMENTS_ALL_READ or APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE permissions to work with seller-level, booking-related custom attributes. For more information, see OAuth API 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 visibility setting.

• Idempotency - Including an idempotency key in a request guarantees that the request is processed only once. The following endpoints allow you to specify an idempotency_key:

  • CreateBookingCustomAttributeDefinition
  • UpdateBookingCustomAttributeDefinition
  • UpsertBookingCustomAttribute
  • BulkUpsertBookingCustomAttributes

  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.

In general, using the API to enable custom attributes for a booking involves the following types of programming tasks:

1. Call CreateBookingCustomAttributeDefinition to create a CustomAttributeDefinition object, specifying in the input appropriate values on the key, name, schema, visibility, and other fields:

   • The key value uniquely identifies the custom attribute definition and the corresponding custom attribute.
   • The schema field specifies the format of the custom attribute value.
   • The visibility field defines how the custom attribute can be accessed by other applications.

2. Call UpsertBookingCustomAttribute to set a CustomAttribute object for a booking according to the custom attribute definition, specifying the key, booking_id, value, and possibly other field values in the input:

   • The key field must be assigned the same value as the key field of the corresponding CustomAttributeDefinition.
   • The booking_id is the ID of the Booking object to associate the custom attribute with.
   • The value field takes an assigned value of the custom attribute. Its format must conform to the schema of the corresponding CustomAttributeDefinition object.

3. 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 String type:

The 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:

• The booking_id path parameter specifies the associated booking.
• The key path parameter (ambient-music) must match the key field value of the corresponding custom attribute definition of Ambient Music.
• The value body parameter in the request assigns a value to the custom attribute. This value must conform to the schema specification stated in the custom attribute definition. In this example, the value ("Jazz") is of the String type.

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 booking_id):

The successful request returns in the response a payload similar to the following:

{
  "custom_attribute": {
    "key": "ambient-music",
    "version": 1,
    "updated_at"