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": "2022-11-16T21:13:48Z",
    "value": "Jazz",
    "created_at": "2022-11-16T21:13:48Z",
    "visibility": "VISIBILITY_READ_ONLY"
  }
}

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:

• Address
• Boolean
• Date
• DateTime
• Duration
• Email
• Number
• PhoneNumber
• Selection
• String

For information about defining the data type for a booking-related custom attribute, see Specifying the schema.

A 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 READ and WRITE permissions to the definition and all instances of the corresponding custom attribute.

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

To access custom attributes or definitions owned by other applications, the following conditions must be met:

• The visibility field 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 the qualified key of a custom attribute for the following requests:

  • RetrieveBookingCustomAttributeDefinition
  • UpsertBookingCustomAttribute
  • BulkUpsertBookingCustomAttributes
  • RetrieveBookingCustomAttribute
  • DeleteBookingCustomAttribute

  To obtain a qualified key, call ListBookingCustomAttributeDefinitions or 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:

• .owned event 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.

• .visible event 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 visibility setting is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

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 .visible event.

The following is an example booking.custom_attribute_definition.visible.created notification:

{
  "merchant_id": "DM7VKY8Q63GNP",
  "type": "booking.custom_attribute_definition.visible.created",
  "event_id": "347ab320-c0ba-48f5-959a-4e147b9aefcf",
  "created_at": "2022-11-16T21:40:49.943Z",
  "data": {
    "type": "custom_attribute_definition",
    "id": "sq0idp-BushoY39o1X-GPxRRUWc0A:businessEmail",
    "object": {
      "created_at": "2022-11-16T21:40:49Z",
      "description": "Work email address",
      "key": "sq0idp-BushoY39o1X-GPxRRUWc0A:businessEmail",
      "name": "Work email",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Email"
      },
      "updated_at": "2022-11-16T21:40:49Z",
      "version": 1,
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  }
}

The following is an example booking.custom_attribute.visible.updated notification:

{
  "merchant_id": "DM7VKY8Q63GNP",
  "type": "booking.custom_attribute.visible.updated",
  "event_id": "1cc2925c-f6e2-4fb6-a597-07c198de59e1",
  "created_at": "2022-11-16T01:22:29Z",
  "data": {
    "type": "custom_attribute",
    "id": "sq0idp-BushoY39o1X-GPxRRUWc0A:businessEmail:BOOKING:TNQC0TYTWMRSFFQ157KK4V7MVR",
    "object": {
      "created_at": "2022-11-16T00:40:54Z",
      "key": "sq0idp-BushoY39o1X-GPxRRUWc0A:businessEmail",
      "updated_at": "2022-11-16T01:22:29Z",
      "value": "[email protected]",
      "version": 2,
      "visibility": "VISIBILITY_READ_WRITE_VALUES"
    }
  }
}

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_READ and APPOINTMENTS_ALL_READ), the application receives notifications of all custom attribute events for all bookings in the seller account.

• The key of the custom attribute definition or custom attribute in the notification is always the qualified key.

• If you subscribe to the .owned and .visible options 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.id in the notification depends on the affected object:

  • For custom attribute definition events, data.id is the qualified key.
  • For custom attribute events, data.id is generated using the qualified key and the ID of the affected booking. This data.id cannot be used directly with the Booking Custom Attributes API.

For more information about custom attribute webhooks, see Subscribing to webhooks. For more information about how to subscribe to events and validate notifications, see Square Webhooks.

• Create and Manage Custom Attribute Definitions for Bookings
• Create and Manage Custom Attribute for Bookings
• Custom Attributes
• API Reference: Custom Attributes for Bookings