Bookings Attributes API: Sample Flows

This article presents a possible use case and corresponding sample flow that you can support. It provides a useful starting point as you plan your implementation.

Set up attributes and display values on the public site

A vacation rentals app wants to capture structured properties (such as Bed Type, Capacity, and Has WiFi) for its "room" resources, let admins set per-room values from the back office, and display those values on each room's public-facing page.

To set up attributes and display values on the public site:

Part 1: Define attributes (one-time setup)

1. Call Create Attribute Definition for each property you want to support. For each call, specify a unique name, a valueType, type-specific configuration (stringConfig.allowedValues for strings, numberConfig.min/max for numbers), and a defaultValue. Save the returned attributeDefinitionId for each definition. Definitions are created once per site.

Part 2: Manage per-entity values (back office)

2. When an admin opens the form for a specific entity (for example, a room), call List Entity Attributes with the entity's entityId. The response contains the entity's current AttributeValues, each paired with its AttributeDefinition (name, type, and config). Render the form from these pairs, and offer the remaining site definitions (from Query Attribute Definitions) for attributes the entity doesn't have a value for yet.

3. When the admin submits the form, call Bulk Upsert Attribute Values with the entityId and the list of values entered. Each entry is matched by attributeDefinitionId, and only the listed attributes are updated. To remove attributes from the entity, call Bulk Delete Attribute Values with the entityId and the attributeDefinitionIds to clear.

Part 3: Display values on the public site

4. When the public site renders a page for a specific entity, call List Entity Attributes with the entity's entityId. Filter the returned pairs to those where attributeDefinition.visibility is true (the API does not enforce visibility), then render the attributeDefinition.name and the value from the matching attributeValue.

5. To build a filtered listing of entities (for example, "rooms with WiFi"), call Query Attribute Values with a WQL filter on the relevant typed value field (boolData, numberData, or stringData). Pair the resulting entityIds with your entity catalog to render the filtered list.