Max Capacity (Group Bookings)

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

What Is Max Capacity?

Max capacity allows multiple customers to book the same service at the same time. Instead of one appointment per slot, you can configure how many simultaneous bookings are allowed.

This feature is essential for:

• Group classes – Fitness, yoga, workshops
• Shared resources – Equipment, vehicles, rooms
• Events – Tours, experiences, seminars
• Multi-practitioner services – Services where multiple staff can work simultaneously

How It Works

The bookingsPerSlot property controls capacity:

• Default value: 1 (one customer per slot)
• Higher values: Multiple customers share the same slot
• Availability calculation: Slot appears until capacity is reached

Example:

A yoga class has bookingsPerSlot: 20. The 9:00 AM slot:

• Shows as available to all customers initially
• Remains available as bookings accumulate (1, 2, 3... customers)
• Disappears from availability after the 20th booking
• Returns if someone cancels (capacity freed up)

Configuring Max Capacity

On Services

Set bookingsPerSlot when creating or updating a service:

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Yoga Class",
    "duration": 60,
    "scope": "LOCATION",
    "LocationId": "location-uuid",
    "bookingsPerSlot": 20
  }'

On Resources

Resources can also have bookingsPerSlot for when the resource itself is the capacity constraint:

{
  "name": "Conference Room A",
  "bookingsPerSlot": 50
}

When both service and resource have bookingsPerSlot set, the system uses the service's value for availability calculations but respects the resource's capacity limit.

Availability Behavior

Slot Visibility

A slot shows in availability results when:

Current bookings < bookingsPerSlot

As customers book:

• 0 bookings: Slot shows, capacity = 20/20
• 5 bookings: Slot shows, capacity = 15/20
• 19 bookings: Slot shows, capacity = 1/20
• 20 bookings: Slot disappears (fully booked)

Simultaneous Requests

OnSched handles race conditions gracefully. If two customers try to book the last spot simultaneously:

• First request succeeds
• Second request fails with 422 Unprocessable Entity
• Second customer must choose another slot

Resource Assignment

For group bookings, typically:

• All customers in a slot are assigned to the same resource(s)
• Resources represent instructors, facilitators, or the shared asset

Example:

Yoga class at 9:00 AM:

• 15 customers book
• All assigned to resource: "Instructor: Sarah"
• Sarah's schedule shows one appointment with 15 attendees

Use Cases

Fitness Classes

Configuration:

{
  "name": "Spin Class",
  "duration": 45,
  "bookingsPerSlot": 25,
  "scope": "LOCATION"
}

Behavior:

• Class runs at fixed times (9:00 AM, 10:00 AM, 6:00 PM)
• Up to 25 customers can book each session
• All customers share the instructor resource

Equipment Rental

Configuration:

{
  "name": "Kayak Rental",
  "duration": 120,
  "bookingsPerSlot": 10,
  "scope": "LOCATION"
}

Behavior:

• 10 kayaks available
• Customers book 2-hour rental slots
• Each booking "consumes" one kayak from the pool
• Once 10 bookings exist for a slot, no more rentals available

Workshops or Seminars

Configuration:

{
  "name": "Marketing Workshop",
  "duration": 180,
  "bookingsPerSlot": 50,
  "allDayBooking": true,
  "scope": "COMPANY"
}

Behavior:

• One-time or recurring event
• 50 seats available
• Attendees book their spot
• No overbooking beyond capacity

Tours or Experiences

Configuration:

{
  "name": "Winery Tour",
  "duration": 90,
  "bookingsPerSlot": 15,
  "scope": "LOCATION"
}

Behavior:

• Multiple tour times per day
• 15 people per tour
• Customers book slots throughout the day

Capacity Management Strategies

Fixed-Time Classes

For classes at specific times (not rolling availability):

1. Create service with bookingsPerSlot matching class size
2. Use resource schedules or allocations to define when classes occur
3. Block out class times in resource availability

Example:

Yoga classes at 6:00 AM, 9:00 AM, and 6:00 PM daily:

• Service: "Yoga Class" (bookingsPerSlot: 20)
• Resource: "Studio A" with availability blocks at class times
• Customers see only these fixed times, not rolling 60-minute slots

Rolling Availability

For rentals or services without fixed schedules:

1. Set bookingsPerSlot to equipment count
2. Define broad resource availability (e.g., 8 AM - 8 PM)
3. Let availability engine generate slots dynamically

Example:

10 bikes available for hourly rental:

• Service: "Bike Rental" (bookingsPerSlot: 10, duration: 60)
• Resource: "Bike Fleet" (available 8 AM - 8 PM)
• Customers can start rentals any hour, as long as fewer than 10 are active

Tiered Capacity

For VIP or different experience levels:

1. Create separate services for each tier
2. Set different bookingsPerSlot values
3. Link to different resources if needed

Example:

• "Standard Tour" (bookingsPerSlot: 30)
• "VIP Tour" (bookingsPerSlot: 10)

Both might run concurrently but with different capacities and resources.

Booking Flow

Customer Perspective

1. Customer checks availability
2. Slot shows as available (capacity not yet reached)
3. Customer books
4. System checks current bookings < bookingsPerSlot
5. If space available, booking confirms
6. If full, booking fails with conflict error

Handling Full Slots

When a slot reaches capacity:

• It disappears from future availability requests
• Existing bookings remain valid
• Cancellations free up capacity (slot reappears if within search window)

Best practice: Display remaining capacity in your UI:

{
  "slot": "2025-12-01T09:00:00Z",
  "capacity": 15,
  "booked": 8,
  "available": 7
}

This encourages customers to book before slots fill.

Combining with Other Features

With Padding

Padding applies to the entire slot, not per customer:

{
  "duration": 60,
  "padding": 15,
  "bookingsPerSlot": 20
}

• Class runs 9:00 - 10:00
• Padding blocks 10:00 - 10:15
• Next class can start at 10:15
• All 20 customers experience the same timeframe

With Resource Capacity

If both service and resource have bookingsPerSlot:

• Service capacity determines how many customers can book the service
• Resource capacity limits how many the resource can handle

Example:

• Service: "Group Training" (bookingsPerSlot: 20)
• Resource: "Trainer Joe" (bookingsPerSlot: 10)

When booking, the system might allow up to 20 for the service, but if only Trainer Joe is available and he has a limit of 10, availability reflects the more restrictive limit.

With Round Robin

Round robin behaves differently with group bookings:

• RANDOM – Picks any available resource (all customers assigned to same resource)
• BALANCED – Distributes load, but for group bookings all customers in one slot go to the same resource
• NONE – Requires specifying resources, all customers assigned to those resources

Group bookings typically use a single resource (instructor, room) rather than round robin assignment.

API Examples

Creating a Group Service

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pilates Class",
    "description": "All levels welcome",
    "duration": 60,
    "bookingsPerSlot": 15,
    "scope": "LOCATION",
    "LocationId": "location-uuid"
  }'

Checking Capacity in Availability

curl "https://v3.onsched.com/v3/availability?\
startDate=2025-12-01&\
endDate=2025-12-07&\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response shows available slots. Each slot can accept up to bookingsPerSlot bookings.

Booking a Slot

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Customer": {
      "firstName": "Alex",
      "lastName": "Morgan",
      "email": "[email protected]"
    },
    "Unavailability": {
      "startTime": "2025-12-01T09:00:00Z",
      "endTime": "2025-12-01T10:00:00Z"
    },
    "duration": 60
  }'

If capacity is available, the booking succeeds. If full, you get a 422 error.

Reporting and Analytics

Tracking Utilization

For group services, track:

• Bookings per slot – How full is each class/session?
• No-show rate – Are customers not showing up?
• Capacity trends – Do you need larger classes or more sessions?

Query appointments filtered by service and time range to calculate metrics.

Cancellations

Cancellations free capacity immediately. Consider:

• Waitlists – Notify interested customers when spots open
• Cancellation policies – Discourage last-minute cancellations for group events
• Automated reminders – Reduce no-shows with timely notifications

Common Questions

Can I overbook intentionally?

Not directly. bookingsPerSlot is a hard limit. If you expect no-shows and want to overbook:

• Set bookingsPerSlot higher than physical capacity (e.g., 25 for a 20-person class)
• Manage risk in your own logic
• Communicate clearly with customers

Can capacity vary by time?

Not per slot. bookingsPerSlot applies to all slots for that service. To vary capacity:

• Create separate services (e.g., "Morning Class" with 30 capacity, "Evening Class" with 15)
• Use different resources with different bookingsPerSlot values

What if someone books multiple spots?

OnSched treats each appointment as one booking against capacity. If a customer wants to bring guests:

• Create separate appointments for each guest
• Or track guest count in appointment CustomFields and manage manually

How do refunds work for group bookings?

Payment processing is external to OnSched. When a customer cancels:

• Their appointment is removed
• Capacity frees up
• Your application handles refund logic based on policies

Best Practices

Set Realistic Capacity

• Don't max out physical limits – Leave buffer for comfort and safety
• Account for equipment/space – 50-person room shouldn't have 50-person classes if people need space
• Consider staff ratios – Ensure instructor-to-student ratios are safe and effective

Communicate Capacity

Show customers:

• How many spots remain ("Only 3 spots left!")
• When classes fill up ("This class is full. Try another time.")
• Waitlist options ("Join the waitlist and we'll notify you if space opens.")

Handle No-Shows

For group services where no-shows affect revenue:

• Require payment upfront
• Send reminders 24 hours before
• Implement cancellation fees
• Overbook slightly if patterns justify it

Test Thoroughly

Before launching group services:

• Book multiple appointments for the same slot
• Verify availability updates correctly as capacity fills
• Test cancellation flow (capacity should reopen)
• Confirm capacity limits are enforced (can't book beyond limit)

Troubleshooting

Capacity not updating

If availability doesn't reflect current bookings:

• Check cache settings (availability is cached up to 1 hour)
• Verify appointment status (cancelled appointments shouldn't count)
• Confirm appointments reference the correct service and slot time

Slots disappearing prematurely

If slots vanish before reaching capacity:

• Check if resource also has bookingsPerSlot (more restrictive limit applies)
• Verify no overlapping unavailability blocks
• Look for resource availability gaps

Overbooking occurring

If more customers book than capacity allows:

• Race conditions are handled, but check for manual overrides
• Ensure hold expirations are processing correctly
• Verify appointment creation validates against current count

Related Documentation

• Services Overview – Core service configuration
• Resources Overview – Resource capacity settings
• Availability Guide – How capacity affects availability
• Appointments – Booking flow and validation
• Booking Limits – Other restriction types

Max capacity unlocks group booking scenarios while maintaining the same reliable availability and booking workflows. Configure bookingsPerSlot thoughtfully, and OnSched handles the complexity of multi-customer slots automatically.