Entity Operating Hours

When to Use

• Establish predictable hours for locations or services (e.g., “Mon–Fri, 9–5”).
• Align booking hours with each location’s timezone.
• Provide a backbone that allocations, recurring blocks, and overrides can extend without exposing internal scheduling logic.

Components of Operating Hours

1. Location Timezone: Each location stores its IANA timezone (e.g., America/New_York). All subsequent schedules inherit this setting.
2. Schedule (weeklyAvailability): The baseline repeating hours for an entity using the schedule availability type. Every location must use this mode. Services or resources can optionally use it when their hours repeat every week.
3. Weekly/Single Allocations (allocation type): An alternative availability mode for services/resources that require a mix of recurring windows (weekly allocations) plus specific overrides (single allocations). An entity can use either schedule or allocation, never both simultaneously.
4. Recurring Blocks: Optional closures (holidays, maintenance) that happen repeatedly.
5. Single Allocations: (when using allocation mode) One-off overrides for special events or exceptions.
6. External Calendars: Bring in personal conflicts before slots are generated.

getAvailability combines these layers in real time to decide whether a slot should be returned.

Recommended Structure

Building Operating Hours

1. Set location timezone: PUT /v3/location/:id with timezone.
2. Choose availability type per entity:
   • Locations: Always use schedule mode (weeklyAvailability).
   • Services/Resources: Decide between schedule (predictable weekly hours) or allocation (mix of weekly + single allocations). You cannot mix both modes for the same entity.
3. If using schedule mode: Define weeklyAvailability blocks for the entity.
4. If using allocation mode: Configure weekly allocations for recurring patterns, then layer single allocations for specific dates.
5. Add recurring blocks: Define predictable closures (holidays, team meetings) regardless of the base mode.
6. Connect calendars: Let providers sync Google/Outlook for personal conflicts.

Whenever you update any layer, availability caches are purged, so subsequent GET /v3/availability responses reflect the change immediately.

Tips

• Use military local time: Even for weeklyAvailability entries use your local military time (HH:MM) for each day.
• Avoid overlapping windows: Overlaps are technically allowed but make timelines harder to visualize. Keep entries distinct.
• Document intent: Store descriptions on single allocations or recurring blocks so team members know why slots changed.
• Test with the API: After major schedule edits, run a test GET /v3/availability query covering the affected dates to confirm expected slots appear.

Troubleshooting

• Slots showing outside business hours: Confirm the location timezone is correct and that external calendars aren’t adding availability via misconfigured write calendars.
• Empty days for allocation entities: Confirm you created both weekly allocations (for recurring capacity) and any needed single allocations. Allocation mode assumes you manage both sets manually.
• Empty days for schedule entities: Ensure each resource participates in the service and inherits the correct weeklyAvailability.
• Conflicting overrides: When layers overlap, the engine subtracts the most restrictive rule first (closures/unavailability). Adjust whichever layer should be authoritative.

Designing clean operating hours upfront keeps downstream availability requests predictable and reduces the need for manual fixes.