Use cases

Classes and group sessions

Yoga, spin, pilates, kids’ swimming, a group workshop: a class takes an instructor and a room for an hour, and has a number of places that customers book one by one. In Tiempo the class is a session (a booking with seats), and each customer is an attendee taking one or more of them.

The session occupies the instructor and the room like any booking, so nobody can book the studio for a private session on top of it. Seats are counted under a lock, so the last place goes to exactly one person.

Put a class on the timetable

Create the session as confirmed with its segments and seats. Keep the class type, price and description in your app, with the booking id; metadata is handy for your own ids.

Thursday yoga, 12 places

curl -X POST "$TIEMPO/v1/bookings" \
  -H "Authorization: Bearer $TIEMPO_KEY" \
  -H "Tiempo-Account: $ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "seats": 12,
    "segments": [
      {
        "resource": "res_maya",
        "start": "2026-11-19T18:00:00Z",
        "end": "2026-11-19T19:00:00Z"
      },
      {
        "resource": "res_studio_1",
        "start": "2026-11-19T18:00:00Z",
        "end": "2026-11-19T19:00:00Z"
      }
    ],
    "metadata": {
      "class_id": "cls_vinyasa"
    }
  }'

Customers take a place

Adding an attendee without a status holds the place while they pay, just like a booking hold, and it lapses if they leave. Confirm it after payment. When the class is full, you get 409 seats_unavailable with seats_available, so you can offer the waitlist.

Attendees have the same lifecycle as bookings: cancel, mark completed or no_show after the class starts. The session shows seats_taken. Cancelling the session cancels its attendees too.

Hold one place

curl -X POST "$TIEMPO/v1/bookings/bkg_…/attendees" \
  -H "Authorization: Bearer $TIEMPO_KEY" \
  -H "Tiempo-Account: $ACCOUNT" \
  -H "Idempotency-Key: order_5521-place" \
  -H "Content-Type: application/json" \
  -d '{
    "seats": 1,
    "metadata": {
      "customer_id": "cus_204"
    }
  }'

Full

{
  "error": {
    "type": "conflict_error",
    "code": "seats_unavailable",
    "message": "Requested 1 seat(s) but only 0 available.",
    "seats_available": 0
  }
}

A weekly timetable

A series creates the class every week (or any RRULE) as real sessions, a rolling window ahead. Each occurrence keeps its local time through clock changes. If one clashes with something already booked, it’s skipped and you get series.occurrence_skipped rather than a double-booked studio.

Customers book a place on an occurrence like any session. To change the timetable from a date, edit the series in place; to cancel one week, cancel that session.

Tuesdays and Thursdays at 07:00

curl -X POST "$TIEMPO/v1/series" \
  -H "Authorization: Bearer $TIEMPO_KEY" \
  -H "Tiempo-Account: $ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{
    "rrule": "FREQ=WEEKLY;BYDAY=TU,TH",
    "start_date": "2026-11-17",
    "start_time": "07:00",
    "timezone": "Europe/London",
    "template": {
      "seats": 12,
      "segments": [
        {
          "resource": "res_maya",
          "offset_minutes": 0,
          "duration_minutes": 60
        },
        {
          "resource": "res_studio_1",
          "offset_minutes": 0,
          "duration_minutes": 60
        }
      ]
    }
  }'

Waitlists

Tiempo doesn’t keep a waitlist, because who gets offered a place first (and whether they pay a deposit) is your product’s decision. It tells you when a place frees up: listen for attendee.cancelled and attendee.expired, then offer the place to the next person and hold it for them with a new attendee.

Private sessions in the same studio are ordinary bookings on the same resources. See the attendees reference for every field.