Create and Manage Custom Attribute Definitions for Bookings

A custom attribute definition determines the shape and format of a custom attribute. The key property is used to identify the custom attribute definition and the corresponding custom attribute. The visibility setting specifies how other applications can access the definition. The schema field specifies the data type of the custom attribute. Other fields can be used to describe other information about the custom attribute definition.

After a booking-related custom attribute definition is created, instances of the corresponding custom attribute can be created with appropriate values for bookings in the seller account. For more information about how to work with booking-related custom attributes, see Custom Attributes for Bookings.

Link to section

CustomAttributeDefinition object

A custom attribute definition is represented by a CustomAttributeDefinition object. The following example shows a custom attribute definition that defines a "Favorite Drink" custom attribute of the String data type:

{ "custom_attribute_definition": { "key": "favorite-drink", "name": "Favorite Drink", "description": "The favorite drink of the customer", "version": 1, "updated_at": "2022-05-20T02:41:37Z", "schema": { "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String" }, "created_at": "2022-05-20T02:41:37Z", "visibility": "VISIBILITY_READ_WRITE_VALUES" } }

Using this custom attribute definition, you can create custom attributes of various drinks for a customer to choose when, for example, the customer books a wedding event.

A custom attribute definition has the following core properties:

FieldDescription
keyThe identifier for the definition and its corresponding custom attributes. This key is unique for the application and cannot be changed after the definition is created.

If the requesting application isn't the definition owner, the value is a qualified key. A qualified key is the application ID of the definition owner followed by the key that was provided when the definition was created, in the following format: {application ID}:{key}.

For custom fields created by sellers in Square Appointments, the qualified key is square:{key}.
nameThe name for the custom attribute. This name must be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller. This field is required if visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.
descriptionThe description for the custom attribute. This field is required if visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.
visibilityThe access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. Valid values are VISIBILITY_HIDDEN, VISIBILITY_READ_ONLY, and VISIBILITY_READ_WRITE_VALUES. For more information, see Access control.

Regardless of the visibility setting, all custom attribute data is visible to sellers when booking data is exported.
schemaThe data type of the custom attribute value. For more information, see Specifying the schema. The total schema size cannot exceed 12 KB.
versionThe version number of the custom attribute definition. The version number is initially set to 1 and incremented each time the definition is updated. Include this field in update operations to enable optimistic concurrency control and in read operations for strong consistency.
Link to section

Create a custom attribute definition for bookings

Call the CreateBookingCustomAttributeDefinition endpoint to create a custom attribute definition for bookings in a seller account. Note the following:

  • key is the identifier of the definition and its corresponding custom attributes. The value must be unique for the application. It can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-) and must match the following regular expression:

^[a-zA-Z0-9\._-]{1,60}$

  • visibility is the access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:

    • VISIBILITY_HIDDEN (default)
    • VISIBILITY_READ_ONLY
    • VISIBILITY_READ_WRITE_VALUES
  • schema is the data type of the custom attribute. For more information, see Specifying the schema.

  • name and description are the name and description of the custom attribute. Each field can contain up to 255 characters.

    Both fields are required when visibility is set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. If provided, name must be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller. Seller-facing custom attributes should be given a friendly name and description.

  • idempotency_key is a unique ID for the request that can be optionally included to ensure idempotency.

The following example request defines a "Favorite Drink" custom attribute of the String type:

Create booking custom attribute definition

The successful response is similar to the following:

{ "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" } }

Now that the custom attribute definition is created, you can proceed to create a corresponding custom attribute and set its value for a booking in the seller account. For more information, see Create or update a booking custom attribute or Bulk create or update booking custom attributes.

After a custom attribute definition is created, the booking.custom_attribute_definition.owned.created and booking.custom_attribute_definition.visible.created webhook events are dispatched to subscribing applications.

A seller account can have a maximum of 100 booking-related custom attribute definitions per application.

Link to section

Specifying the schema

The data type of a custom attribute is specified by the schema field of the definition. Square uses the schema to validate the custom attribute value when it is assigned to a booking. The total schema size cannot exceed 12 KB. When setting the value of the custom attribute for a booking, the total value size cannot exceed 5 KB.

The following data types are supported for booking-related custom attributes:

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

Note

The Date, DateTime, Duration, Email, Number, or PhoneNumber data type takes a string value.

In a CreateBookingCustomAttributeDefinition request, the schema field specifies a data type by referencing a JSON schema or meta-schema object hosted on the Square CDN.

Link to section

JSON schema objects

For the data types in the following table, specify a $ref value that references the corresponding schema object, as shown in the following example:

"schema": { "$ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String" },
Data typeDescription
StringA string with up to 1000 UTF-8 characters. Empty strings are allowed.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
EmailAn email address consisting of ASCII characters that matches the regular expression for the HTML5 email type.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Email
PhoneNumberA string representation of a phone number in E.164 format. For example, +17895551234.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.PhoneNumber
AddressAn Address object. For information about Address fields, see Working with Addresses.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Address
DateA date in ISO 8601 format: YYYY-MM-DD. Booking-related custom attributes don't support DateTime or Duration data types.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Date
BooleanA true or false value.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean
NumberA 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.

For numeric values that act as identifiers rather than representing a quantity (such as account numbers), consider using the String data type so that the value isn't subject to limitations of a number range.

$ref value:
https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
Link to section

JSON meta-schema object

For a Selection data type, the schema contains a $schema field that references a JSON meta-schema object and additional fields. Note the following:

  • $schema references the https://developer-production-s.squarecdn.com/meta-schemas/v1/selection.json meta-schema hosted on the Square CDN.

  • type must be array.

  • items must include a names array that contains strings representing the display names of the predefined options that can be selected. Note that the order of the options might not be respected by all UIs.

  • maxItems is an integer that represents the maximum number of allowed selections. Corresponding custom attributes can have zero or more selected values, up to the specified maximum. The minimum value is 1 and cannot exceed the number of options in the names field.

  • uniqueItems must be true.

The following example request creates a Selection-type custom attribute definition that contains three named options and allows one selection:

Create booking custom attribute definition

The following is an example response. For each named option, Square generates a UUID and adds it to the enum field. The options in the names field map by index to the UUIDs in the enum field. The first option maps to the first UUID, the second option maps to the second UUID, and so on.

These UUIDs are used to set the value of the custom attribute or update the option names.

Note

In API Explorer, use the Custom option for schema to specify the JSON object.

Link to section

Update a booking custom attribute definition

Use the UpdateBookingCustomAttributeDefinition endpoint to update a custom attribute definition for a seller account. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type

Only new or changed fields need to be included in the request. For more information, see Updatable definition fields.

Note the following about an UpdateBookingCustomAttributeDefinition request:

  • A custom attribute definition can be updated only by the definition owner.

  • The key path parameter is the key of the to-be-updated custom attribute definition.

  • The version field can be optionally included to enable optimistic concurrency control. If included, version must match the current version of the custom attribute definition; otherwise, the request fails with a CONFLICT error. Square increments the version number each time the definition is updated.

  • The idempotency_key is a unique ID for the request that can be optionally included to ensure idempotency.

The following example request updates the visibility setting of a definition:

Update booking custom attribute definition

The following is an example response:

{ "custom_attribute_definition": { "key": "favorite-drink", "name": "Favorite Drink", "description": "The favorite drink of the customer", "version": 2, "updated_at": "2022-11-16T04:17:09Z", "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_ONLY" } }

After a custom attribute definition is updated, the booking.custom_attribute_definition.owned.updated and booking.custom_attribute_definition.visible.updated webhook events are dispatched to subscribing applications.

Link to section

Updatable definition fields

The UpdateBookingCustomAttributeDefinition endpoint can be used to update one or more of the following fields. The endpoint supports sparse updates, so only new or changed fields need to be included in the request. Square ignores custom attribute definition fields that are unchanged or read-only.

  • name - The name of the custom attribute of up to 255 characters. Seller-facing custom attributes should be given a user-friendly name. The name must be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller.

  • description - The description of the custom attribute of up to 255 characters. Seller-facing custom attributes should be given a user-friendly description.

  • visibility - The access control setting that determines whether other applications can view the definition and view or edit corresponding custom attributes. The following are valid values:

    • VISIBILITY_HIDDEN (default)
    • VISIBILITY_READ_ONLY
    • VISIBILITY_READ_WRITE_VALUES

    Changes to the visibility setting are propagated to corresponding custom attributes within a few seconds. At that time, the updated_at and version fields of the custom attributes are also updated. For VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES settings, both name and description are required.

  • schema - For a Selection data type. Only changes to the named options and maximum number of selections are supported, as described in the following section. The total schema size cannot exceed 12 KB.

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 the definition for one seller, you should consider making the same change for all other sellers.

Link to section

Updating a Selection schema

For a Selection data type, you can update the maximum number of allowed selections and the set of predefined named options.

Note

Square validates custom attribute selections on upsert operations, so these changes apply only to future upsert operations. They don't affect custom attributes that have already been set on bookings.

The information you send in the UpdateBookingCustomAttributeDefinition request depends on the change you want to make:

  • To change the maximum number of allowed selections, include the maxItems field with the new integer value. The minimum value is 1 and cannot exceed the number of options in the names field.

  • To change the set of predefined named options, include the items field with the complete names and enum arrays. The options in the names array map by index to the Square-assigned UUIDs in the enum array, which are unique per seller. The first option maps to the first UUID, the second option maps to the second UUID, and so on.

    • To add an option:

      • Add the name of the new option at the end of the names array. New options must always be added to the end of the array.
      • Don't change the enum array. Square generates a UUID for the new option and adds it to the end of the enum array.
    • To reorder the options:

      • Change the order of the names in the names array.

      • Change the order of the UUIDs in the enum array so that the order of the UUIDs matches the order of the corresponding named options.

        Note that the order might not be respected by all UIs.

    • To remove an option:

      • Remove the name of the option from the names array.
      • Remove the corresponding UUID from the enum array.

The following example UpdateBookingCustomAttributeDefinition request adds two new options by adding the names at the end of the names array.

Update booking custom attribute definition

The following example response includes the UUID that Square generated for the new X-Small and X-Large options:

Link to section

List booking custom attribute definitions

Use the ListBookingCustomAttributeDefinitions endpoint to list the booking custom attribute definitions in a seller account. Note the following:

  • The limit query parameter optionally specifies a maximum page size of 1 to 100 results. The default limit is 20.

    If the results are paged, the cursor field in the response contains a value that you can send with the cursor query parameter to get the next page of results.

The following example request includes the limit query parameter:

List booking custom attribute definitions

When all pages are retrieved, all custom attribute definitions created by the requesting application are included in the results. The key for these definitions is the key that was provided when the definition was created.

Custom attribute definitions created by other applications are included if their visibility is VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. The key for these definitions is a qualified key.

The following is an example response:

The example response contains four custom attribute definitions:

  • "Favorite Drink" and "Entity ID" were created by the requesting application. Because "Entity ID" is set to VISIBILITY_HIDDEN, it is returned only when requested by the definition owner.

  • "Work email" was created by another third-party application. Note that the qualified key includes the ID of the application that created the custom attribute definition.

  • "Is Premium Member" was created by the seller in the Square Appointments. For first-party Square products, the application_id is square.

If no custom attribute definitions are found, Square returns an empty response.

{}
Link to section

Retrieve a booking custom attribute definition

Use the RetrieveBookingCustomAttributeDefinition endpoint to retrieve a custom attribute definition using the key. Note the following:

  • The key path parameter is the key of the custom attribute definition.

    • 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 definition must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

  • The version query parameter is optionally used 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 later version if one exists. If the specified version is later than the current version, Square returns a 400 BAD_REQUEST error.

The following is an example request:

Retrieve booking custom attribute definition

Note

Square also returns custom attribute definitions for RetrieveBookingCustomAttribute or ListBookingCustomAttributes requests if you set the with_definition or with_definitions query parameter to true, respectively. For more information, see Retrieve a booking custom attribute or List booking custom attributes.

The following is an example response:

{ "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" } }

If the custom attribute definition isn't found, Square returns an errors field that contains a 404 NOT_FOUND error.

Link to section

Delete a booking custom attribute definition

Use the DeleteBookingCustomAttributeDefinition endpoint to delete a custom attribute definition from a seller account. Note the following:

  • A custom attribute definition can be deleted only by the definition owner.

  • The key path parameter is the key of the custom attribute definition.

  • Deleting a custom attribute definition also deletes the corresponding custom attribute from all bookings in the seller account.

The following is an example request:

Delete booking custom attribute definition

If successful, Square returns a 200 OK response containing an empty errors object.

{ "errors": [] }

After a custom attribute definition is deleted, Square invokes the booking.custom_attribute_definition.owned.deleted and booking.custom_attribute_definition.visible.deleted webhook events.

Link to section

See also