About the Bookings Attributes API

The Bookings Attributes API lets you define typed custom properties (string, number, or boolean) and attach values to entities in your business. It's designed for back-office admins who need to capture structured data about resources, services, or other entities, and for sites that need to display that data to end users.

With the Bookings Attributes API, you can:

• Define typed attributes (string, number, boolean) with a default value. String attributes have a list of allowed values; number attributes have a required integer minimum and maximum range.
• Upsert per-entity attribute values from the back office, and delete them when they're no longer needed.
• Retrieve an entity's values paired with their definitions, suitable for rendering forms or public-facing listings.
• Query and filter attribute definitions and values for back-office and consumer-facing experiences.

For example, a vacation rentals app might define Bed Type (string), Capacity (number), and Has WiFi (boolean) attributes, then store per-room values that get displayed on the public site next to each room.

How Attributes work

The API uses two core concepts:

• An attribute definition is the schema: name, value type, optional configuration (such as allowed string values or an integer range), and a default value. Definitions exist once per site.
• An attribute value is the value of an attribute definition for a specific entity. Each attribute value references its definition and the entity it belongs to.

An entity is any item your application owns that you want to attach values to, for example a resource in a Wix Rentals integration. The entity's identity is supplied by the caller via entityId; the API does not own or validate it.

Define attributes once with Create Attribute Definition. Set values for a specific entity with Bulk Upsert Attribute Values, remove them with Bulk Delete Attribute Values, and read an entity's values, each paired with its definition, with List Entity Attributes.

Visibility

Each attribute definition has a visibility flag that indicates whether the attribute is intended for end users on the public site. When visibility is false, back-office admins can still see and edit the attribute, but it should be hidden from site visitors. Visibility is not enforced by the API: List Entity Attributes and Query Attribute Values return values regardless of visibility, so callers fetching attributes for public display are responsible for filtering out hidden attributes when rendering.

Before you begin

It's important to note the following points before starting to code:

• An entity's ID is supplied by the caller. The API does not validate that the ID refers to a real entity in another service. Make sure the entity IDs you pass refer to a resource your application owns.
• An attribute definition's valueType is immutable. To switch types, delete the attribute definition (which deletes all related attribute values) and create a new one.
• Deleting an attribute definition is permanent: there's no restore, and all of its attribute values are removed.
• Changing an attribute definition's configuration re-validates stored values: any value that no longer conforms to the new configuration is reset to the attribute's default.
• name on an attribute definition is a single-language string. If your site supports multiple languages, you need to handle translation outside this API.
• Attribute definitions can be tagged with the Wix tagging system; attribute values cannot. To group or filter attribute values by tag, tag the parent attribute definition and resolve the relationship in your application.
• Each entity supports up to 50 attribute values.

Use cases

• Set up attributes and display values on the public site

Terminology

• Attribute definition: A typed custom property (string, number, or boolean) with a name, optional configuration, and a default value. Defined once per site.
• Attribute value: The value of an attribute definition for a specific entity.
• Entity: Any item that has attribute values. The entity's identity is supplied by the caller via entityId; this API does not own or validate it.
• Default value: The value a stored attribute value is reset to if a configuration change leaves it non-conforming.