Learn how custom attributes can support additional properties on the Booking object.
Bookings API

Custom Attributes for Bookings

Custom attributes for Booking objects store properties or metadata (which can be added to the Booking objects to support custom business logic) that are not 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, and

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

  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:

Create Booking Custom Attribute Definition
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/bookings/custom-attribute-definitions \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute_definition": {
      "key": "ambient-music",
      "visibility": "VISIBILITY_READ_ONLY",
      "schema": {
        "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
      },
      "name": "Ambient Music",
      "description": "The genre of the ambient music being played for the customer during a booked service."
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'

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.

Upsert Booking Custom Attribute
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/bookings/1234567890/custom-attributes/ambient-music \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_attribute": {
      "value": "Jazz"
    }
  }'

Note

Square also provides the BulkUpsertBookingCustomAttributes endpoint to support creating multiple custom attributes for specified bookings in a single request.

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

Retrieve Booking Custom Attribute
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/bookings/1234567890/custom-attributes/ambient-music \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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.

Note

Working with custom attributes is different than working with native attributes on the Booking object that are accessed using the Bookings API. For example, custom attributes are not returned in a RetrieveBooking or ListBookings response or managed using CreateBooking or UpdateBooking.

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:

  • String

  • Email

  • PhoneNumber

  • Address

  • Date

  • Boolean

  • Number

  • Selection

Note

Customer-related custom attributes do not support DateTime or Duration data types.

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.

Did you know?

To simplify management, you might want to keep all definitions that use the same key synchronized across seller accounts. Therefore, if you change a definition for one seller, you should consider making the same change for all other sellers.

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:

Custom attribute definition Custom attribute
Visibility setting READ WRITE READ WRITE
VISIBILITY_HIDDEN (default) No No No No
VISIBILITY_READ_ONLY Yes No Yes No
VISIBILITY_READ_WRITE_VALUES Yes No Yes Yes

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

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{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.

Note

Be aware of the following behaviors when using custom attributes that are owned by other applications:

  • If the visibility of a custom attribute definition is updated, the change propagates to all corresponding custom attributes within a few seconds.

  • If a custom attribute definition is deleted, all corresponding custom attributes are also deleted from bookings.

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:

Event
Description
booking.custom_attribute_definition.owned.createdA custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
boooking.custom_attribute_definition.owned.updatedA custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
booking.custom_attribute_definition.owned.deletedA custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
booking.custom_attribute.owned.updatedA custom attribute owned by your application was created or updated for a booking.
booking.custom_attribute.owned.deletedA custom attribute owned by your application was deleted from a booking.

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 do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event
Description
booking.custom_attribute_definition.visible.createdA custom attribute definition that is visible to your application was created.
booking.custom_attribute_definition.visible.updatedA custom attribute definition that is visible to your application was updated.
booking.custom_attribute_definition.visible.deletedA custom attribute definition that is visible to your application was deleted.
booking.custom_attribute.visible.updatedA custom attribute that is visible to your application was created or updated for a booking.
booking.custom_attribute.visible.deletedA custom attribute that is visible to your application was deleted from a booking.

Note

Upserting or deleting a custom attribute for a booking does not invoke a booking.updated webhook.

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

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

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

    The key provided during creation prefixed by the application ID of the definition owner: {application ID}:{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 Overview.

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. Do not 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 are not supported for booking-related custom attributes:

    • DateTime

    • Duration

  • Search support. The Bookings API does not 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 Overview and OAuth Permissions Reference.

    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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.