Round Robin Booking

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 Round Robin?

Round robin is the strategy OnSched uses to automatically assign resources to appointments when multiple resources can fulfill a service. Instead of always picking the same resource, round robin distributes bookings fairly.

Why Use Round Robin?

Without Round Robin

If the system always picked the first available resource:

• Resource A gets overbooked (100 appointments)
• Resource B sits idle (10 appointments)
• Resource C barely works (5 appointments)

This creates uneven workload and poor resource utilization.

With Round Robin

The system intelligently distributes appointments:

• Resource A gets 40 appointments
• Resource B gets 38 appointments
• Resource C gets 37 appointments

Everyone stays busy, and no one is overwhelmed.

Round Robin Modes

OnSched supports three modes, configured per service:

RANDOM (Default)

How it works:

• System picks any available resource randomly
• Each resource has equal chance of being selected
• No consideration of existing workload

Use when:

• You don't care about distribution balance
• All resources are equally preferred
• Simplicity is priority

Example:

Service "Haircut" has 3 stylists. Customer checks availability:

• All 3 are free at 2:00 PM
• System randomly picks "Stylist B"
• Customer books with Stylist B

Next customer at 2:30 PM:

• All 3 are free
• System randomly picks "Stylist C"

Configuration:

{
  "name": "Haircut",
  "roundRobin": "RANDOM"
}

BALANCED

How it works:

• System counts existing appointments for each resource in the search window
• Picks resource with fewest appointments
• Distributes workload evenly over time

Use when:

• Fair workload distribution matters
• You want to prevent overworking some staff
• Resources have similar capacity

Example:

Service "Consultation" has 3 consultants. Over the past week:

• Consultant A: 15 appointments
• Consultant B: 12 appointments
• Consultant C: 18 appointments

Customer checks availability for next week:

• All 3 are free at 3:00 PM
• System assigns Consultant B (has fewest bookings)
• This balances the load

Configuration:

{
  "name": "Consultation",
  "roundRobin": "BALANCED"
}

Load calculation window:

The system counts appointments within the availability search date range (startDate to endDate). This means "balance" is relative to the search window, not all-time bookings.

NONE

How it works:

• No automatic assignment
• Requires explicit resource selection
• For coordinated appointments (multiple resources) or manual selection

Use when:

• Customer must choose a specific resource (stylist preference, doctor selection)
• Appointment requires multiple resources simultaneously (dentist + hygienist)
• Manual control is required

Example:

Service "Team Consultation" requires 2 consultants:

• roundRobin: NONE
• Must specify ResourceIds=consultant1&ResourceIds=consultant2
• Availability only shows when ALL specified resources are free
• System assigns all specified resources to appointment

Configuration:

{
  "name": "Team Consultation",
  "roundRobin": "NONE"
}

When using NONE, customers can't book unless they specify which resource(s) they want.

Mode Comparison

Configuring Round Robin

Round robin mode is set on the service, not the resource:

curl -X POST https://v3.onsched.com/v3/service \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Massage",
    "duration": 60,
    "roundRobin": "BALANCED",
    "scope": "COMPANY"
  }'

All bookings for "Massage" will use balanced assignment unless overridden with explicit ResourceIds.

API Behavior

Availability Requests

When calling GET /v3/availability:

Without ResourceIds (uses round robin):

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

• Returns slots where at least one resource is available
• Doesn't specify which resource (determined at booking)
• Round robin applies when booking

With ResourceIds (bypasses round robin):

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

• Returns slots where specified resources are available
• Round robin mode ignored (explicit selection)

Appointment Creation

When calling POST /v3/appointment:

Without ResourceIds (uses round robin):

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": {...},
    "Unavailability": {
      "startTime": "2025-12-01T14:00:00Z",
      "endTime": "2025-12-01T14:30:00Z"
    },
    "duration": 30
  }'

• System applies round robin based on service configuration
• Assigns resource automatically
• Response includes assigned ResourceIds

With ResourceIds (bypasses round robin):

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID&\
ResourceIds=RESOURCE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

• System assigns specified resource
• Round robin ignored
• Fails if specified resource is unavailable

Practical Examples

Scenario 1: Hair Salon (RANDOM)

Setup:

• Service: "Basic Haircut" (roundRobin: RANDOM)
• Resources: 4 stylists

Behavior:

• Customer books 2:00 PM slot
• All 4 stylists are available
• System randomly picks "Stylist C"
• Customer booked with Stylist C

No preference—everyone gets equal opportunity.

Scenario 2: Consulting Firm (BALANCED)

Setup:

• Service: "Strategy Session" (roundRobin: BALANCED)
• Resources: 3 consultants

Situation:

• Consultant A: 8 appointments this week
• Consultant B: 5 appointments this week
• Consultant C: 10 appointments this week

Behavior:

• Customer books Thursday 10:00 AM
• All 3 are available
• System assigns Consultant B (lowest count)
• Balances workload over time

Ensures fair distribution.

Scenario 3: Dental Procedure (NONE)

Setup:

• Service: "Root Canal" (roundRobin: NONE)
• Resources: Dr. Martinez (dentist), Lisa (assistant)

Behavior:

• Customer requests availability
• Must specify both resource IDs
• Availability shows only when both are free simultaneously
• Appointment assigns both resources

No round robin—explicit coordination required.

Scenario 4: Customer Preference (Override)

Setup:

• Service: "Personal Training" (roundRobin: BALANCED)
• Resources: 5 trainers

Behavior:

• Customer wants "Trainer Mike" specifically
• Request includes ResourceIds=trainer-mike-id
• Round robin bypassed
• Availability shows only Mike's open slots
• Appointment assigns Mike

Customer choice overrides round robin.

Advanced Considerations

BALANCED with Different Capacity Resources

If resources have different bookingsPerSlot values:

• Resource A: bookingsPerSlot: 1
• Resource B: bookingsPerSlot: 2 (can handle 2 simultaneous appointments)

BALANCED mode counts appointments, not capacity utilization. Resource B might handle twice as many appointments before being considered "busy."

Recommendation: Use BALANCED with resources of similar capacity, or implement custom load balancing in your application layer.

BALANCED with New Resources

When adding a new resource:

• They start with 0 appointments
• BALANCED mode will heavily favor them initially
• After a few bookings, distribution normalizes

This is expected behavior—new resources naturally receive more initial assignments.

Time Window Effects

BALANCED counts appointments only within the availability search date range. Implications:

• Searching next week? Counts bookings next week only.
• Searching today only? Counts appointments today only.
• Different search windows yield different "balanced" assignments.

For consistent long-term balancing, use broader search windows or implement external tracking.

Round Robin with Holds

When creating holds (POST /appointment/hold):

• Round robin applies the same way
• Holds count toward resource load for BALANCED mode
• Expired holds release the resource (load decreases)

Choosing the Right Mode

Ask these questions:

Do customers care which resource they get?

• No → RANDOM or BALANCED
• Yes → NONE (let customers choose)

Is workload distribution important?

• Yes → BALANCED
• No → RANDOM

Do appointments require multiple resources?

• Yes → NONE
• No → RANDOM or BALANCED

Do you want control over assignments?

• Maximum control → NONE (always specify resources)
• Automatic → RANDOM or BALANCED

Mixing Modes

Different services can use different modes:

[
  {
    "name": "Quick Trim",
    "roundRobin": "RANDOM"
  },
  {
    "name": "Color Treatment",
    "roundRobin": "BALANCED"
  },
  {
    "name": "Bridal Package",
    "roundRobin": "NONE"
  }
]

Match the mode to service requirements.

Overriding Round Robin

You can always override round robin by specifying ResourceIds in availability or appointment requests, regardless of service configuration.

Use override for:

• Customer preferences ("I want Dr. Smith")
• Returning customers (book with same resource)
• VIP experiences (specific staff member)
• Testing (assign to specific resource for QA)

Troubleshooting

BALANCED not distributing evenly

Check:

1. Search date range—BALANCED counts appointments within search window only
2. Resource availability—if some resources have limited hours, they naturally get fewer bookings
3. Booking patterns—balancing happens over time; short-term imbalances are normal

NONE mode failing with error

Check:

1. Did you specify ResourceIds?
2. Are all specified resources available during the slot?
3. Are specified resources linked to the service?

Resources still getting uneven bookings with BALANCED

Possible reasons:

1. Resources have different availability (one works part-time)
2. External calendar blocks (one resource has many external events)
3. Different bookingsPerSlot values
4. Customers explicitly requesting certain resources

Balanced mode helps but doesn't guarantee perfect distribution if underlying factors differ.

Round robin applying when I don't want it

Solution:

• Always specify ResourceIds to bypass round robin
• Or set service to roundRobin: NONE to require explicit selection

Best Practices

Start with RANDOM

Unless you have specific needs:

• Begin with RANDOM mode
• Monitor booking distribution
• Switch to BALANCED if imbalances emerge

Use BALANCED for Staff Fairness

If fair workload matters (compensation, morale, burnout prevention):

• Choose BALANCED
• Monitor actual distribution over time
• Adjust resource availability if needed

Reserve NONE for Special Cases

Don't use NONE unless:

• Customers must choose resources
• Multi-resource coordination is required

NONE adds complexity to booking flow.

Let Customers Override When Appropriate

Even with RANDOM or BALANCED:

• Allow customers to request specific resources
• Show resource profiles (photos, bios, reviews)
• Pass ResourceIds for preferred bookings

Flexibility improves customer satisfaction.

Document Your Choice

Record why you chose each mode:

• "Haircut uses BALANCED because stylists prefer equal bookings"
• "Massage uses RANDOM because all therapists are equally popular"
• "Team Consult uses NONE because it requires specific partner pairs"

This helps future decision-making.

Related Documentation

• Resources Overview – Resource configuration
• Services Overview – Service setup
• Availability Guide – How round robin affects availability
• Appointments – Booking with resource assignment
• Linked Resources – Connecting resources to services

Round robin makes resource assignment automatic and fair. Choose the right mode for your business model, and OnSched handles the complexity of distribution for you.