Catalog Search: Sample Flows

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

All flows use the single Query Services by Filters endpoint with different filter combinations.

Show services bookable this week

If a site owner wants to display only the services a customer can actually book, you can query the catalog for services with availability in a date range.

To do this, your app can:

1. Call Query Services by Filters, specifying a serviceFilters with localStartDate, localEndDate, and timeZone. Leave exactMatch unset so a service is returned when it has at least 1 bookable slot anywhere in the window.

   Copy

2. Render the returned results. Each result contains the full service entity and an available flag, which is true for every service in this flow.

   Copy

3. If the response contains pagingMetadata.cursors.next, request the next page by passing it unchanged as query.cursorPaging.cursor. Repeat until next is absent.

   Copy

Filter the catalog by location and resource attributes

If a site owner wants customers to narrow the catalog to a specific business location and staff with certain attributes, you can apply location, resource type, and attribute filters.

To do this, your app can:

1. Call Query Services by Filters, specifying in serviceFilters the locationIds to match, the resourceTypes to include (such as STAFF), and one attributes entry per attribute condition. Values for the same attribute are OR'd (match any); values across different attributes are AND'd (match all).

The attributes field supports four value types depending on how the attribute was defined:

• enumValue (string): matches a specific enum option.

• numberRangeValue (object with min/max): matches a numeric range. To match an exact value, set both min and max to the same number.

• boolValue (boolean): matches a true/false flag.

• numberValues (array of numbers): matches if the resource's stored number equals any value in the set.

  Copy

2. Because no date range is provided, no availability check runs. All pre-filtered services are returned with available set to true.

   Copy

Build a filter sidebar with unavailable services greyed out

If a site owner wants to show the full catalog while distinguishing services that have no availability, you can include unavailable services in the response.

To do this, your app can:

1. Call Query Services by Filters, specifying a serviceFilters with the date range and includeUnavailable set to true.

   Copy

2. Render all results. Use each result's available flag to decide whether to show the service as bookable (true) or unavailable (false).

   Copy

Require availability for an entire multi-day range

If a site owner offers a multi-session experience, you can return only services that are bookable on every day of a multi-day window.

To do this, your app can:

1. Call Query Services by Filters, specifying a serviceFilters that spans 2 or more days with exactMatch set to true. For a days range, the service must have available slots on every day in the window.

   Copy

2. Only services with slots available on every day of the range are returned.

   Copy

Filter services by catalog fields

You can combine WQL catalog filters on the query field with an availability window. This lets you narrow by service properties (such as type or name) before the availability check runs.

To do this, your app can:

1. Call Query Services by Filters, specifying a query.filter using the same fields supported by Query Services, together with a serviceFilters for the date range.

   Copy

2. The catalog filter runs first, so only services of type CLASS reach the availability engine. This keeps latency low when the full catalog is large.

   Copy