Booking Limits & Restrictions

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

What Are Booking Limits?

Booking limits restrict appointment booking to prevent abuse, manage capacity, and ensure fair access. Limits can control:

• Total bookings – Maximum appointments per customer
• Daily limits – Appointments per day (by count or duration)
• Advance booking – How far ahead customers can book
• Resource limits – Maximum bookings for specific resources

Limits are configured at the service or resource level.

Types of Booking Limits

1. Booking Limit (Total Appointments)

Property: bookingLimit

Level: Service, Resource

Purpose: Limit total active appointments per customer

{
  "bookingLimit": 3
}

Behavior:

• Customer can have maximum 3 active appointments for this service/resource
• Once limit is reached, no new bookings allowed until an appointment is completed or cancelled
• Limit is per service (or resource if set on resource)

Use case:

• Prevent bulk booking abuse
• Ensure fair access to popular services
• Manage limited capacity resources

Example:

Personal training service with bookingLimit: 2:

• Customer books appointment #1: allowed
• Customer books appointment #2: allowed
• Customer tries to book #3: rejected (limit reached)
• Customer cancels appointment #1: Can now book appointment #3

2. Daily Booking Limit (By Count)

Property: dailyBookingLimitCount

Level: Service

Purpose: Limit appointments per day by count

{
  "dailyBookingLimitCount": 1
}

Behavior:

• Customer can book maximum 1 appointment for this service per day
• Applies across all times on the same calendar day
• Timezone-aware (day boundaries based on service/location timezone)

Use case:

• Services that should only be performed once per day
• Medical procedures with recovery time
• Daily class attendance limits

Example:

Fitness class with dailyBookingLimitCount: 1:

• Customer books 9:00 AM class: allowed
• Customer tries to book 6:00 PM class same day: rejected (limit reached)
• Customer can book class next day: allowed

3. Daily Booking Limit (By Duration)

Property: dailyBookingLimitMinutes

Level: Service

Purpose: Limit total appointment minutes per day

{
  "dailyBookingLimitMinutes": 90
}

Behavior:

• Customer can book up to 90 minutes of this service per day
• Multiple shorter appointments allowed if total doesn't exceed limit
• Minutes are cumulative across all appointments

Use case:

• Equipment rentals with daily usage limits
• Services billed by time
• Facility access with duration caps

Example:

Conference room rental with dailyBookingLimitMinutes: 180 (3 hours):

• Customer books 9:00-10:30 (90 min): allowed, 90 minutes used
• Customer books 2:00-3:00 (60 min): allowed, 150 minutes used
• Customer tries to book 4:00-5:00 (60 min): rejected (would exceed 180 minutes)

4. Maximum Booking Limit (Per Customer)

Property: maxBookingLimit

Level: Service

Purpose: Lifetime maximum appointments per customer for this service

{
  "maxBookingLimit": 10
}

Behavior:

• Customer can book this service maximum 10 times total
• Includes all completed, cancelled, and active appointments
• Permanent limit (doesn't reset)

Use case:

• Free trial services (limited sessions)
• Introductory offers
• One-time or limited-availability services

Example:

Free consultation service with maxBookingLimit: 1:

• Customer books consultation: allowed
• Appointment completes
• Customer tries to book another consultation: rejected (lifetime limit reached)

5. Maximum Resource Booking Limit

Property: maxResourceBookingLimit

Level: Service

Purpose: Maximum appointments per customer for a specific resource within this service

{
  "maxResourceBookingLimit": 5
}

Behavior:

• Customer can book appointments with each resource maximum 5 times
• Separate count per resource
• Useful for rotating customers across resources

Use case:

• Encourage trying different staff members
• Balance workload across resources
• Prevent over-reliance on one provider

Example:

Training service with maxResourceBookingLimit: 3:

• Customer books 3 appointments with Trainer A: limit reached for Trainer A
• Customer can still book with Trainer B, C, etc.
• Customer cannot book more with Trainer A until count resets or limit changes

6. Advance Booking Window

Properties: bookInAdvance, bookAheadUnit, bookAheadValue

Level: Service

Purpose: Control how far in the future customers can book

{
  "bookInAdvance": 1440,
  "bookAheadUnit": 3,
  "bookAheadValue": 30
}

• bookInAdvance – Minimum minutes from now booking can be made (default: 0)
• bookAheadUnit – Time unit for maximum window (1=minutes, 2=hours, 3=days, 4=weeks)
• bookAheadValue – Number of units customers can book ahead

Behavior:

• Customers must book at least bookInAdvance minutes from now
• Customers cannot book beyond bookAheadValue units into future

Use case:

• Prevent last-minute bookings (require 24-hour notice)
• Cap how far ahead bookings can be made (e.g., 30 days)
• Seasonal services (open booking window gradually)

Example:

Service requiring 24-hour notice, max 60 days ahead:

{
  "bookInAdvance": 1440,
  "bookAheadUnit": 3,
  "bookAheadValue": 60
}

• Customer tries to book today: rejected (need 24 hours notice)
• Customer books tomorrow: allowed
• Customer books 70 days ahead: rejected (beyond 60-day window)

Configuring Limits

On Services

curl -X PUT https://v3.onsched.com/v3/service/SERVICE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingLimit": 3,
    "dailyBookingLimitCount": 1,
    "dailyBookingLimitMinutes": 90,
    "maxBookingLimit": 10,
    "bookAheadUnit": 3,
    "bookAheadValue": 30
  }'

On Resources

curl -X PUT https://v3.onsched.com/v3/resource/RESOURCE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingLimit": 5
  }'

Resource limits apply only when booking that specific resource.

How Limits Are Enforced

During Availability Checks

Availability requests (GET /v3/availability) respect limits:

• Slots shown only if customer hasn't reached limit
• If limit reached, no slots returned (or empty response)

During Booking

Appointment creation (POST /v3/appointment) validates limits:

• If limit exceeded, request fails with 422 Unprocessable Entity
• Error message indicates which limit was exceeded
• Customer must cancel existing appointment or wait for limit to reset

Validation Flow

1. Customer requests booking
2. System checks all applicable limits:
   • Service bookingLimit
   • Service dailyBookingLimitCount
   • Service dailyBookingLimitMinutes
   • Service maxBookingLimit
   • Service maxResourceBookingLimit (if resource specified)
   • Resource bookingLimit (if resource specified)
   • Advance booking window
3. If any limit exceeded, booking fails
4. If all limits pass, booking proceeds

Combining Limits

You can set multiple limits simultaneously. ALL must pass for booking to succeed.

Example:

{
  "bookingLimit": 5,
  "dailyBookingLimitCount": 1,
  "bookAheadUnit": 3,
  "bookAheadValue": 14
}

Customer must satisfy:

• ✅ Have fewer than 5 active appointments
• ✅ Not already booked today
• ✅ Booking is at least today (bookInAdvance: 0 by default) and within 14 days

Limit Precedence

Limits don't have precedence—they all apply. Most restrictive wins effectively:

• bookingLimit: 10 AND dailyBookingLimitCount: 1 → Customer can have 10 active appointments, but only 1 per day
• Both conditions must be met

Use Cases

Free Trial Services

{
  "maxBookingLimit": 3
}

Allow 3 free consultations per customer, then require paid service.

High-Demand Resources

{
  "bookingLimit": 2,
  "bookAheadUnit": 3,
  "bookAheadValue": 7
}

Customers can book maximum 2 appointments, only within next 7 days. Ensures fair access and prevents hoarding.

Medical Appointments

{
  "dailyBookingLimitCount": 1,
  "bookInAdvance": 2880
}

One appointment per day, requires 48-hour notice. Allows proper scheduling and preparation.

Equipment Rentals

{
  "dailyBookingLimitMinutes": 240
}

Maximum 4 hours of equipment rental per customer per day.

Membership Tiers

Different services for different membership levels:

• Bronze service: maxBookingLimit: 5 per month
• Silver service: maxBookingLimit: 10 per month
• Gold service: No limit

Implement monthly resets via custom logic (OnSched limits don't auto-reset by period).

Resetting Limits

Automatic Resets

• Daily limits (dailyBookingLimitCount, dailyBookingLimitMinutes) reset at midnight in service/location timezone
• Active appointment limits (bookingLimit) reset when appointments are completed or cancelled
• Lifetime limits (maxBookingLimit, maxResourceBookingLimit) do NOT reset automatically

Manual Resets

To reset lifetime limits:

• Modify maxBookingLimit to higher value temporarily
• Or handle via custom logic (track bookings in CustomFields, implement your own reset schedule)

Exemptions and Overrides

Admin Bookings

If creating appointments via API with admin credentials, consider:

• Use bookingLimit: 0 to indicate "unlimited" (if 0 means no limit in your configuration)
• Or bypass validation by booking directly without limit checks (requires custom implementation)

VIP Customers

To exempt specific customers from limits:

• Create separate service with different limits
• Or use custom logic to check customer tier before enforcing limits
• Store exemption status in customer CustomFields

Error Handling

When limit is exceeded:

{
  "statusCode": 422,
  "name": "UnprocessableEntityError",
  "message": "Booking limit reached. You have 3 active appointments for this service. Cancel an appointment to book another.",
  "errors": [
    {
      "field": "bookingLimit",
      "message": "Customer has reached maximum booking limit for this service"
    }
  ]
}

Display user-friendly message:

"You've reached your booking limit. Please cancel an existing appointment or complete your current appointments before booking again."

Best Practices

Set Realistic Limits

• Don't over-restrict unnecessarily
• Balance access fairness with customer convenience
• Monitor booking patterns before setting limits

Communicate Limits Clearly

In booking interface:

• Show remaining bookings ("2 of 3 appointments used")
• Explain why booking failed ("Daily limit reached. Try tomorrow.")
• Provide alternatives ("This service is full. Try [similar service].")

Test Limit Behavior

Before going live:

• Book appointments up to limit
• Verify limit enforcement
• Test limit reset (for daily limits)
• Confirm error messages are clear

Use Limits Strategically

Good uses:

• Prevent abuse
• Ensure fair access
• Manage capacity
• Trial period controls

Avoid:

• Overly restrictive limits that frustrate customers
• Limits that don't match business model
• Limits without clear customer communication

Monitor and Adjust

Track:

• How often limits are hit
• Customer complaints about limits
• Booking patterns

Adjust limits based on data, not assumptions.

Troubleshooting

Limit not enforced

Check:

1. Limit is set to non-zero value
2. Service or resource has limit configured
3. Validation is enabled (not bypassed in custom code)

Wrong limit applied

Check:

1. Service limit vs resource limit (both apply if both set)
2. Customer's appointment count is accurate
3. Timezone affecting daily limit boundaries

Customer claims limit is wrong

Verify:

1. Count customer's active appointments for service
2. Check daily bookings for customer
3. Review lifetime booking count
4. Ensure cancelled appointments are excluded from active count

Limit not resetting daily

Check:

1. Timezone configuration (daily reset at midnight in service timezone)
2. System time is accurate
3. Appointments from previous day are properly dated

Common Questions

Can limits differ by customer type?

Not directly. Create separate services with different limits for different customer tiers:

• "Basic Membership Appointment" (bookingLimit: 2)
• "Premium Membership Appointment" (bookingLimit: 10)

Do cancelled appointments count toward limits?

• Active limits (bookingLimit): No, cancelled don't count
• Lifetime limits (maxBookingLimit): Yes, all bookings count (even cancelled)
• Daily limits: Only active appointments on that day count

Can I set monthly limits?

Not natively. Options:

• Use maxBookingLimit and manually reset monthly
• Track in CustomFields and enforce via custom logic
• Use daily limits as approximation (e.g., 1 per day ≈ 30 per month)

How do I disable limits?

Set to 0 (if 0 means unlimited) or omit the property:

{
  "bookingLimit": 0,
  "dailyBookingLimitCount": 0
}

Check API documentation for how 0 is interpreted.

Can limits apply to groups?

Limits are per customer. For group bookings:

• Each attendee counted separately (if separate customer records)
• Or use bookingsPerSlot for capacity (not a customer limit)

Related Documentation

• Services Overview – Service configuration
• Resources Overview – Resource settings
• Settings Overview – All configuration options
• Max Capacity – Group booking capacity
• Availability Guide – How limits affect availability

Booking limits give you control over access and capacity. Configure thoughtfully, communicate clearly, and adjust based on customer feedback to find the right balance for your business.