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, resource, or weekly allocation level. Several limit types sound similar but enforce different rules — use the table below before picking a field.

Choose the right limit

0 or omitted = unlimited for numeric limits unless noted otherwise.

Three buckets — do not mix them up:

1. Same-slot capacity (bookingsPerSlot) — “How many people can share 9:00 AM right now?”
2. Service quotas (dailyBookingLimit*) — “How many bookings may this service accept in this calendar day?” (global across customers)
3. Per-customer caps (bookingLimit, maxBookingLimit, maxResourceBookingLimit) — “How many may this customer hold or book?”

See Max Capacity for group booking. See Weekly Allocations for allocation capacity.

Weekly allocation capacity vs customer limits

Weekly allocation capacity (bookingsPerSlot on service+resource POST /v3/weeklyAllocation and related routes) caps how many appointments may share the same instant for that pair-scoped pattern. Other slots in the same week are unaffected. Service-only or resource-only weekly rows do not use this field.

Customer booking limits (below) restrict how many appointments an individual customer may hold, reserve, or book. They are checked at hold, reserve, book, and reschedule when a customer is known. They are not applied to anonymous availability browsing — GET /v3/availability without a customer context does not hide slots based on per-customer caps.

Service-wide daily quotas (dailyBookingLimitCount, dailyBookingLimitMinutes) apply to all customers combined for that service. When exhausted, affected days disappear from availability for everyone.

See Weekly Allocations.

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 at most this many active appointments (BK booked + IN short holds) for this service
• RS (reserved) appointments block the slot in availability but do not count toward this active cap
• Cancelled (CN) and rescheduled-away (RE) rows do not count
• Once the cap is reached, new holds/books for that customer fail until an active appointment completes or is cancelled

Resource bookingLimit: Same active cap, but scoped to the current service and resource pair (not all services that resource serves).

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 (service-wide — not per customer)

Purpose: Limit total appointments for this service per calendar day across all customers

{
  "dailyBookingLimitCount": 1
}

Behavior:

• The service accepts at most this many booked + held appointments (BK + IN) whose start time falls on the same calendar day
• Day boundaries use the service-scoped timezone (company timezone for company-scoped services; location timezone for location-scoped services)
• When the quota is exhausted, no slots are returned for that day on GET /v3/availability until the next day

Use case:

• Hard daily capacity for a popular class or clinic day
• Regulatory or staffing caps on total daily volume

Example:

Fitness studio with dailyBookingLimitCount: 20:

• 20 customers book classes on Tuesday → Tuesday slots disappear for everyone
• Wednesday starts with a fresh quota

3. Daily Booking Limit (By Duration)

Property: dailyBookingLimitMinutes

Level: Service (service-wide — not per customer)

Purpose: Limit total booked minutes for this service per calendar day across all customers

{
  "dailyBookingLimitMinutes": 90
}

Behavior:

• Sum of appointment durations (by start time day) for BK + IN on this service cannot exceed the limit
• Multiple shorter appointments are allowed if the total stays under the cap
• When exhausted, that calendar day has no remaining slots on availability

Use case:

• Equipment or facility usage caps by total hours per day
• Shared resource pools billed by cumulative time

Example:

Conference center with dailyBookingLimitMinutes: 480 (8 hours):

• Morning bookings use 300 minutes → 180 minutes remain for that day
• A 240-minute request is rejected because only 180 minutes remain

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 at most this many times lifetime across all non-deleted appointment rows
• RE (rescheduled-away) rows do not count — moving an existing booking to a new time is still one lifetime use, aligned with daily quota rules
• CN (cancelled) rows do count toward the lifetime cap
• Enforced at hold, book, and reschedule when a customer is known; reschedule always runs the check (not only when time or resources change)
• Does not reset automatically

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
• Customer reschedules to a new time: allowed (prior row becomes RE, active booking remains one lifetime use)
• Customer tries to book a second 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
• RE (rescheduled-away) rows do not count; CN (cancelled) rows do
• 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": 0,
  "bookAheadValue": 30
}

• bookInAdvance – Minimum minutes from now booking can be made (default: 0)
• bookAheadUnit – Time unit for maximum window (0=days, 1=weeks, 2=months)
• 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

These same fields apply to GET /v3/availability: the server clamps the effective date range to that booking window before it computes slots. Integrators may send a wide startDate / endDate, but returned slots only fall inside the allowed window. If the request lies entirely outside it (entirely in the past, entirely before the minimum lead time, or entirely beyond the max horizon), the response contains no slots. This is not limited to appointment creation—any availability query for that service uses the same bounds.

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": 0,
  "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": 0,
    "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 when booking that specific resource on a service. The active cap is scoped to the service + resource pair (same as maxResourceBookingLimit).

How Limits Are Enforced

On GET /v3/availability

The availability engine applies:

• bookingsPerSlot — concurrent capacity per slot
• bookingsPerSlot (weekly, service+resource) — same-slot capacity for matching pair allocations
• dailyBookingLimitCount / dailyBookingLimitMinutes — service-wide daily quotas

Per-customer limits (bookingLimit, maxBookingLimit, maxResourceBookingLimit) do not filter anonymous availability responses. Build UX that checks limits at booking time when you know the customer, or call hold/book and handle errors.

See Availability Guide.

On hold, reserve, book, and reschedule

When creating or confirming appointments (POST /v3/appointment, /hold, /reserve, PUT …/book, PUT …/reschedule), the API validates:

1. Slot availability (including quotas and capacity above)
2. All applicable per-customer limits when Customer / CustomerId is present

If any check fails, the request returns 400 Bad Request with a message and optional errors array identifying the limit field.

Validation flow (booking time)

1. Customer (or integrator) submits hold/reserve/book/reschedule with customer context
2. System checks slot availability (capacity + quotas)
3. System checks customer limits:
   • Service bookingLimit
   • Resource bookingLimit (service-scoped, if resource specified)
   • Service maxBookingLimit
   • Service maxResourceBookingLimit (if resource specified)
4. If any step fails, booking is rejected
5. If all pass, booking proceeds

Combining Limits

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

Example:

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

Customer must satisfy:

• ✅ Fewer than 5 active appointments (BK + IN) for this service
• ✅ Service daily quota not exhausted (if configured — applies globally, not per customer)
• ✅ Booking is within the advance-booking window

Limit precedence

Layered limits all apply. There is no override order — every configured limit must pass. The API returns the first validation failure encountered (slot unavailable vs customer cap).

Use Cases

Free Trial Services

{
  "maxBookingLimit": 3
}

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

High-Demand Resources

{
  "bookingLimit": 2,
  "bookAheadUnit": 0,
  "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 service quotas — reset at midnight in the service-scoped timezone (new calendar day)
• Weekly allocation capacity — applies per matching slot instant; it does not accumulate or reset like a quota
• Active customer caps (bookingLimit) — decrease when appointments leave BK/IN (cancel, complete, or expire hold)
• Lifetime customer caps (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 a limit is exceeded at booking time:

{
  "success": false,
  "message": "Customer has reached the maximum number of active appointments for this service.",
  "errors": [
    {
      "field": "bookingLimit",
      "message": "Active booking limit reached"
    }
  ]
}

HTTP status is 400 Bad Request (not 422). Slot/quota failures often use message "The selected time slot is not available."

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, resource bookingLimit): No for CN / RE; only BK + IN count. RS does not count but still blocks the slot.
• Lifetime limits (maxBookingLimit, maxResourceBookingLimit): CN counts; RE does not (reschedule is not an extra lifetime booking).
• Daily service quotas: Cancelled, reserved, and rescheduled-away appointments are excluded from quota counts; booked + active holds 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.