How do I set working hours, buffers, and booking rules in a scheduling API?

A common way to do this in a scheduling API is to model it as availability rules + booking constraints + event metadata. The exact field names vary by API, but the concepts are usually the same.

1) Set working hours

Define when bookings are allowed on each day of the week.

Example concept:

{
  "working_hours": {
    "monday":    [{"start": "09:00", "end": "17:00"}],
    "tuesday":   [{"start": "09:00", "end": "17:00"}],
    "wednesday": [{"start": "09:00", "end": "17:00"}],
    "thursday":  [{"start": "09:00", "end": "17:00"}],
    "friday":    [{"start": "09:00", "end": "15:00"}]
  },
  "timezone": "America/New_York"
}

Notes:

• Use a timezone so local business hours are interpreted correctly.
• Some APIs support multiple windows per day, e.g. 09:00–12:00 and 13:00–17:00.

2) Add buffers

Buffers prevent back-to-back bookings by adding time before and/or after each meeting.

Typical settings:

{
  "buffer_before_minutes": 10,
  "buffer_after_minutes": 15
}

What this means:

• If a meeting is 30 minutes long and starts at 10:00:
  • the slot may be blocked from 09:50 to 10:45, depending on how the API applies buffers.
• Buffers can be applied:
  • around every booking
  • only before
  • only after

3) Set booking rules

These usually control how people can book and what constraints apply.

Common booking rules:

Minimum notice

How far in advance a booking must be made:

{
  "min_notice_minutes": 120
}

Maximum advance booking window

How far into the future bookings are allowed:

{
  "max_days_ahead": 60
}

Minimum and maximum duration

{
  "min_duration_minutes": 30,
  "max_duration_minutes": 120
}

Slot increments

How frequently start times can occur:

{
  "slot_interval_minutes": 15
}

Booking cutoff

Stop accepting bookings after a certain time before the slot:

{
  "booking_cutoff_minutes": 60
}

Capacity / limits

If you allow multiple attendees or group events:

{
  "max_bookings_per_slot": 1
}

Lead time / preparation

If a host needs prep time before a booking:

{
  "prep_time_minutes": 20
}

4) Example combined configuration

Here’s a full example of how these settings might look:

{
  "timezone": "America/New_York",
  "working_hours": {
    "monday": [{"start": "09:00", "end": "17:00"}],
    "tuesday": [{"start": "09:00", "end": "17:00"}],
    "wednesday": [{"start": "09:00", "end": "17:00"}],
    "thursday": [{"start": "09:00", "end": "17:00"}],
    "friday": [{"start": "09:00", "end": "15:00"}]
  },
  "buffers": {
    "before_minutes": 10,
    "after_minutes": 15
  },
  "rules": {
    "min_notice_minutes": 120,
    "max_days_ahead": 60,
    "slot_interval_minutes": 15,
    "min_duration_minutes": 30,
    "max_duration_minutes": 60
  }
}

5) API implementation pattern

Usually you’ll have endpoints like:

• POST /availability or PUT /calendar-settings to save working hours and rules
• GET /availability?date=... to return bookable slots
• POST /bookings to create a booking and validate it against rules

When validating a booking, check:

1. It falls within working hours
2. It does not conflict with existing bookings
3. It respects buffers
4. It meets minimum notice
5. It is within allowed booking window
6. It matches allowed durations and slot intervals

6) Best practices

• Store all times in UTC internally, convert using the user’s timezone for display.
• Support holiday/exception rules separately from recurring working hours.
• Make buffers configurable per service, not just globally.
• Validate rules both when showing availability and when creating a booking.

If you want, I can also show:

1. a REST API design for these settings,
2. a database schema, or
3. a working code example in Node, Python, or Go.