Weekly Allocation Guide

When to Use

• Set reliable business hours for services or individual resources.
• Restrict a specific resource on a specific service to certain days (pair-scoped allocations).
• Establish rolling capacity weeks (e.g., every Monday 09:00–17:00).
• Provide a baseline schedule that GET /v3/availability uses before layering single allocations, recurring blocks, and appointments.

Concepts

Scope (how the API targets entities)

You must send at least one of ServiceId or ResourceId. The API resolves three scopes:

Pair-scoped rows are stored on ServiceWeeklyUnavailability with both IDs set. They layer on top of each resource’s existing weekly schedule or allocation; they do not switch the resource to allocation mode by themselves (that flag applies to resource-only weekly allocations).

When you create a service-scoped or pair-scoped weekly allocation and the service was in schedule mode, the API sets Service.availabilityType to allocation. Resource-scoped weekly allocations flip Resource.availabilityType to allocation when the resource was in schedule mode.

For pair scope, the API does not remove non-allocation weekly rows that belong only to the pair association (unlike pure service or resource scope), so pair rules can coexist with existing schedule data as designed.

• Timezone: Inherits from the associated resource, location, or service configuration (see API behavior for which entity wins).
• Granularity: Windows are defined per day of week using HH:MM:SS strings.

Endpoint Overview

All routes require authentication plus verifyCompany.

Payload Shape

Service-wide (all resources for this service):

{
  "ServiceId": "<uuid>",
  "weeklyAvailability": [
    { "dayOfWeek": 1, "startTime": "09:00:00", "endTime": "12:00:00" },
    { "dayOfWeek": 1, "startTime": "13:00:00", "endTime": "17:00:00" },
    { "dayOfWeek": 2, "startTime": "09:00:00", "endTime": "17:00:00" }
  ]
}

Pair-scoped (one resource on this service only):

{
  "ServiceId": "<service-uuid>",
  "ResourceId": "<resource-uuid>",
  "weeklyAvailability": [
    { "dayOfWeek": 3, "startTime": "09:00:00", "endTime": "17:00:00" }
  ]
}

Resource-only (omit ServiceId; use ResourceId):

{
  "ResourceId": "<uuid>",
  "weeklyAvailability": [
    { "dayOfWeek": 1, "startTime": "09:00:00", "endTime": "17:00:00" }
  ]
}

• dayOfWeek: 0 (Sunday) – 6 (Saturday).
• Multiple windows per day are allowed.
• If you need gaps (lunch breaks), submit multiple entries for the same day.

Editing Strategies

• Bulk Replace: Use setWeeklyAllocations when building UI forms. Send the full list you want persisted; the API deletes previous rows for that scope before inserting the new set.
• Partial Updates: For admin tooling where users tweak one window at a time, POST + DELETE individual records may be simpler.

Interaction with Availability

• Service-wide allocation mode: Service-level weekly rows (no ResourceId on the association) define which calendar days the service operates for allocation-type services. Pair rows then refine which resources are available on those days (or add extra days for specific resources where the SQL allows).
• Pair-only patterns: When every weekly row for the service is pair-scoped (no service-level rows), availability for non-targeted resources is not driven by the same “service operating days” rule as a purely service-scoped setup. See allocation coverage in the availability engine docs for how this is computed.
• Other layers (single allocations, recurring blocks, holds, external events) still apply after weekly rules.

When you change an allocation, the API purges relevant caches so new availability requests reflect the update immediately.

Troubleshooting

• “Either ResourceId or ServiceId must be provided” – Send at least one ID. To target a pair, send both.
• Unexpected local times: Ensure you pass times in the location’s timezone. The API does not convert naive strings.
• No slots generated: Verify that the associated service has a duration and that resources are linked; weekly allocations alone do not create availability unless the service/resource relationship is configured.
• Choosing service vs pair: Use service-wide when every provider should share the same recurring service hours. Use pair when only one staff member (or asset) has different recurring hours on that service.

Use weekly allocations as your backbone schedule; layer single allocations for exceptions and recurring blocks for known closures.