Service catalogs and locked booking

Build service catalogs, calendar-first browsing, service detail pages, and booking embeds for a selected service or category. First, complete the installation.

Render a customer flow service catalog

Use service attributes to build a custom catalog from the services connected to a customer flow. Your Webflow or website-builder elements remain in full control of the layout and styling.

Set data-tiquo-services to the customer flow ID. The first data-tiquo-service-item child is the template that Tiquo hides and clones for each service.

<div data-tiquo-services="CUSTOMER_FLOW_ID" data-tiquo-limit="20">
  <article data-tiquo-service-item>
    <a
      data-tiquo-service-link="/services/{slug}?tiquoServiceId={id}"
    >
      <img data-tiquo-service="image" alt="" />
      <h2 data-tiquo-service="name"></h2>
      <span data-tiquo-service="categoryName"></span>
      <p data-tiquo-service="categoryDescription"></p>
    </a>

    <p data-tiquo-service="shortDescription"></p>
    <span data-tiquo-service="priceLabel"></span>
    <span data-tiquo-service="durationLabel"></span>
  </article>

  <p data-tiquo-empty>No services available.</p>
</div>

The customer flow ID is the ID in its booking or embed URL. For example, use CUSTOMER_FLOW_ID from https://book.tiquo.app/embed/CUSTOMER_FLOW_ID.

data-tiquo-service-link sets the element's href and supports these URL-encoded placeholders:

If the attribute has no value, its default link is ?tiquoServiceId={id}. Use data-tiquo-limit to cap the number of services; the default is 100.

Public services render without a customer session. When the customer is signed in, the collection also includes membership-gated services that customer is allowed to book. Inactive services, services outside their visibility window, and services unavailable to the current customer are not rendered.

Service fields

Set data-tiquo-service to any supported field:

When data-tiquo-service="image" or another image URL field is placed on an img, Tiquo safely sets src. On a link, it safely sets href. The existing data-tiquo-hide-empty, data-tiquo-preserve-text, and data-tiquo-style data attributes also work with service fields.

image is the simplest choice for catalog cards because it prefers an image configured directly on the service and automatically falls back to the first associated category image. Use serviceImage or categoryImage when the image source must be explicit. The plural images and categoryImages fields render as comma-separated URLs on text elements.

For example, use a service image as a background:

<div
  data-tiquo-service="image"
  data-tiquo-style="background-image"
  data-tiquo-hide-empty
></div>

Image galleries

Services and categories each hold an ordered gallery of up to 15 images. To build your own carousel, add a data-tiquo-service-images container with one data-tiquo-service-image template inside a service item or detail page. Tiquo copies the template once per image:

<div data-tiquo-service-images data-tiquo-hide-empty>
  <img data-tiquo-service-image alt="" />
</div>

Tiquo sets data-tiquo-image-count on the container to the number of images and data-tiquo-image-index on each copy, which you can use for carousel controls and styling.

Use categoryName to display the first associated category. If a service is assigned to multiple flow categories, use categoryNames to display every category as comma-separated text:

<span data-tiquo-service="categoryName"></span>
<span data-tiquo-service="categoryNames"></span>

Use categoryDescription to display the first configured description from an associated category. Use categoryDescriptions to display every configured associated category description as comma-separated text:

<p data-tiquo-service="categoryDescription"></p>
<p data-tiquo-service="categoryDescriptions"></p>

To render the two sources separately:

<img
  data-tiquo-service="serviceImage"
  data-tiquo-hide-empty
  alt=""
/>
<img
  data-tiquo-service="categoryImage"
  data-tiquo-hide-empty
  alt=""
/>

Render a custom service detail page

Set data-tiquo-service-detail to the same customer flow ID:

<section data-tiquo-service-detail="CUSTOMER_FLOW_ID">
  <img data-tiquo-service="image" alt="" />
  <h1 data-tiquo-service="name"></h1>
  <p data-tiquo-service="description"></p>
  <p data-tiquo-service="categoryDescription"></p>
  <span data-tiquo-service="priceLabel"></span>

  <div data-tiquo-service-booking></div>

  <p data-tiquo-empty>
    This service is unavailable.
  </p>
</section>

By default, the detail container reads the service ID from the tiquoServiceId query parameter written by the catalog link. To render a fixed service instead, set it directly:

<section
  data-tiquo-service-detail="CUSTOMER_FLOW_ID"
  data-tiquo-service-id="SERVICE_ID"
>
  <!-- Service fields and booking container -->
</section>

data-tiquo-service-booking becomes an automatically resizing customer-flow iframe. The requested service is preselected, category and service-catalog navigation are removed, and the customer cannot return to select another service. The remaining availability, quantity, payment, and booking steps continue normally.

If the service is missing or unavailable to the current visitor, Tiquo clears the service fields, hides the booking container, and shows data-tiquo-empty. It never falls back to the full flow catalog.

Calendar-first service browsing

Use Tiquo.getFlowAvailability(bookingConfigId, options) to display dates first and show available services after a visitor clicks a date. This method is available in Hosted Package 1.2.2 and newer. The unversioned installation URL loads the current version.

Build this interaction with the JavaScript API after window.Tiquo.ready. The data-tiquo-services collection renders a service catalog; it does not create calendar buttons or filter that collection when a date is selected. The example below renders the calendar and service list explicitly.

<div id="availability-calendar" aria-label="Available dates"></div>
<p id="availability-status" role="status"></p>
<ul id="available-services"></ul>
<div id="calendar-booking"></div>

<script>
  window.Tiquo.ready(async function (tiquo) {
    const flowId = 'CUSTOMER_FLOW_ID';
    const calendar = document.querySelector('#availability-calendar');
    const serviceList = document.querySelector('#available-services');
    const status = document.querySelector('#availability-status');

    try {
      const summary = await tiquo.getFlowAvailability(flowId, {
        dateFrom: '2026-09-14',
        dateTo: '2026-09-20',
        partySize: 2,
      });

      if (summary.partial) {
        throw new Error('Some availability could not be loaded. Please retry.');
      }

      const servicesById = new Map(
        summary.services.map((service) => [service.id, service]),
      );
      calendar.replaceChildren();
      serviceList.replaceChildren();
      status.textContent = summary.days.some((day) => day.isAvailable)
        ? 'Choose a date to see available services.'
        : 'No services are available this week.';

      for (const day of summary.days) {
        const dateButton = document.createElement('button');
        dateButton.type = 'button';
        dateButton.textContent = day.date;
        dateButton.disabled = !day.isAvailable;
        dateButton.setAttribute('aria-pressed', 'false');
        dateButton.addEventListener('click', () => {
          for (const button of calendar.querySelectorAll('button')) {
            button.setAttribute('aria-pressed', String(button === dateButton));
          }
          serviceList.replaceChildren();
          status.textContent = 'Available services for ' + day.date;

          for (const serviceId of day.serviceIds) {
            const service = servicesById.get(serviceId);
            if (!service) continue;
            const item = document.createElement('li');
            const bookButton = document.createElement('button');
            bookButton.type = 'button';
            bookButton.textContent = service.name;
            bookButton.addEventListener('click', async () => {
              bookButton.disabled = true;
              try {
                await tiquo.embedServiceBooking(
                  flowId, service.id, '#calendar-booking',
                  { date: day.date, partySize: 2 },
                );
              } catch (error) {
                status.textContent = 'Booking could not be loaded. Please retry.';
              } finally {
                bookButton.disabled = false;
              }
            });
            item.append(bookButton);
            serviceList.append(item);
          }
        });
        calendar.append(dateButton);
      }
    } catch (error) {
      status.textContent = error.message || 'Availability could not be loaded.';
    }
  });
</script>

Replace the example date range with the week the visitor is browsing.

Availability options and response

Fetch additional calendar pages by advancing the date range one week at a time. Use dates in the venue's timezone, rather than converting them from the visitor's local timezone.

The response includes the same membership-filtered services, categories, catalogSections, and flow information as getFlowServices(), plus:

Match each day's serviceIds to the objects in services to render names, images, and prices. Complete results with no availability retain the date with an empty serviceIds array. Daily and nightly services can be available on a date without exposing time slots.

If partial is true, show an incomplete-availability message and retry the request. Do not treat failedServiceIds as sold out. Re-fetch availability when the party size or customer session changes.

Load time slots after choosing a date

Run this inside the Tiquo.ready callback or a date-click handler that has access to its tiquo argument.

// selectedDate is the YYYY-MM-DD value from the clicked calendar day.
const detail = await tiquo.getFlowAvailability('CUSTOMER_FLOW_ID', {
  dateFrom: selectedDate,
  dateTo: selectedDate,
  partySize: 2,
  includeSlots: true,
});

if (detail.partial) {
  throw new Error('Some availability could not be loaded. Please retry.');
}

const servicesById = new Map(
  detail.services.map((service) => [service.id, service]),
);
const slots = (detail.days[0]?.slots ?? []).map((slot) => ({
  time: slot.time,
  services: slot.serviceIds
    .map((id) => servicesById.get(id))
    .filter(Boolean),
}));
// Render slots, then show the services for the customer's chosen time.

After the visitor chooses a service and time, pass the same date, start time and party size to embedServiceBooking() so the customer doesn't choose them again. See JavaScript API. The embedded flow re-checks availability, and the customer can still change anything.

JavaScript API

Service catalogs and locked booking are also available programmatically:

<div id="service-booking"></div>

<script>
  window.Tiquo.ready(async function (tiquo) {
    const catalog = await tiquo.getFlowServices("CUSTOMER_FLOW_ID");
    const service = await tiquo.getFlowService(
      "CUSTOMER_FLOW_ID",
      catalog.services[0].id
    );

    if (service) {
      await tiquo.embedServiceBooking(
        "CUSTOMER_FLOW_ID",
        service.id,
        "#service-booking",
        { minHeight: "240px" }
      );
    }
  });
</script>

getFlowService() returns null when the requested service is not available to the current visitor. embedServiceBooking() uses the same secure authenticated iframe handoff and automatic resizing as embedCustomerFlow().

When your page already asked for the day, time, number of people or booking length, pass them in the options so the customer doesn't choose them again:

await tiquo.embedServiceBooking("CUSTOMER_FLOW_ID", service.id, "#service-booking", {
  date: "2026-10-14",  // venue-local YYYY-MM-DD
  startTime: "14:00",  // HH:mm on that date
  partySize: 6,        // the partySize you searched with
  lengthMinutes: 120,  // for a service where the customer chooses the length
});

The calendar opens on date. startTime is selected only while it's still free for the booking length and party size, and behaves like the customer's own click. partySize sets the flow's people stepper, within the flow's limits; flows that sell a quantity of tickets ignore it. lengthOptionId pre-selects one of the service's set lengths. Everything stays editable, and availability is checked again when the customer books. Values in the wrong format reject the returned promise.

Embed booking for a selected category

Use embedCustomerFlow() with categoryId and lockCategory=true to embed a category-locked booking flow. This is supported on the /embed/ surface used by both the DOM Package and Hosted Package.

For example, a Boxing Sessions category can contain separate Member, Guest, and Public services. A category card should open that category and let the customer choose their eligible booking type in the flow's own service step. The category is preselected and cannot be changed inside the embed; the remaining steps follow the flow's configured order.

Use getFlowServices() to load the catalog and render one card per entry in catalog.categories. Store each category's id on its card and pass the clicked category's ID when opening the booking. Do not choose the first service in the category or group categories by name alone.

Use the JavaScript API for this category-card pattern. The data-tiquo-service-booking attribute and service bookingUrl field select one service and should not be used for category cards.

<div id="category-booking"></div>

<script>
  window.Tiquo.ready(async function (tiquo) {
    const bookingConfigId = "CUSTOMER_FLOW_ID";
    const catalog = await tiquo.getFlowServices(bookingConfigId);
    const categoryId = "CATEGORY_ID"; // ID from the clicked category card.
    const category = catalog.categories.find((item) => item.id === categoryId);

    if (!category) throw new Error("Category is unavailable in this flow");

    const url = new URL(
      "https://book.tiquo.app/embed/" + encodeURIComponent(bookingConfigId)
    );
    url.searchParams.set("categoryId", category.id);
    url.searchParams.set("lockCategory", "true");

    await tiquo.embedCustomerFlow(url.toString(), "#category-booking", {
      minHeight: "240px",
      autoResize: true,
    });
  });
</script>

Replace CATEGORY_ID with the clicked card's catalog.categories[].id. CUSTOMER_FLOW_ID is the booking configuration ID already used with getFlowServices() and found in the flow's booking URL.

Leave serviceId and lockService out of category URLs. A locked service takes precedence and prevents the customer from choosing another booking type. Continue using embedServiceBooking() when the customer has already chosen one specific service.

Customer authentication and booking-type visibility

The embed uses the package's authenticated customer session and the flow's normal membership and service-access rules. Ensure the customer is signed in through the package before opening the embed when member options are needed. Signing into the separate member portal alone does not establish that website session. embedCustomerFlow() handles the authenticated iframe handoff and automatic resizing.

Category locking narrows the selection; it does not grant access to Member, Guest, or Public services. The options offered depend on the customer's access and the flow configuration. An invalid category or one with no accessible services does not fall back to unrelated services.

Is the additional flowId parameter required?

No. A correctly configured public embed resolves the flow using the booking configuration ID in /embed/CUSTOMER_FLOW_ID.

The portal may also include flowId, the underlying flow record ID returned as catalog.flow.id. It is distinct from catalog.bookingConfigId and is used for a fallback lookup where permitted. It does not authenticate the customer or enable member booking types. Omit it from the category embed shown above.

See Rendering and empty states for shared collection behaviour.

Booking length configuration

A returned service can include bookingLength for calendar-based Minutes or Hourly bookings. With mode: 'options', each option has an id, minutes, optional label, price, and optional isDefault. With mode: 'range', the configuration supplies minMinutes, maxMinutes, stepMinutes, defaultMinutes, and optional maxPrice.

Use this configuration to explain the available lengths in a custom catalogue. The Tiquo booking flow checks the selected length against availability and calculates the final price. A catalogue response does not reserve a slot or establish that the full duration is available.