Weekly Allocation Guide

When to Use

Set reliable business hours for services or individual resources.
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: Each weekly allocation applies to either a ServiceId or a ResourceId, not both. The validations in createWeeklyAllocation enforce this.
Timezone: Inherits from the associated location/service configuration.
Granularity: Windows are defined per day of week using HH:MM:SS strings.

Endpoint Overview

Endpoint	Purpose
`POST /v3/weeklyAllocation`	Create a new weekly pattern (`weeklyAvailability` array).
`POST /v3/weeklyAllocation/setWeeklyAllocations`	Replace all allocations for the supplied `ServiceId` or `ResourceId` in one request.
`GET /v3/weeklyAllocation`	List allocations; filter by `ServiceId`, `ResourceId`, `startDate`, or `endDate`.
`GET /v3/weeklyAllocation/:id`	Retrieve a single allocation.
`DELETE /v3/weeklyAllocation/:id`	Remove a recurring window.

All routes require authentication plus verifyCompany.

Payload Shape

{
  "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" }
  ]
}

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 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

Weekly allocations are the first layer consumed by getAvailability. They define where slots can exist; other entities (single allocations, recurring blocks, holds, external events) further subtract time. When you change an allocation, the API purges relevant caches so new availability requests reflect the update immediately.

Troubleshooting

“Only one of ResourceId or ServiceId should be provided” – Remove the extra field; weekly allocations cannot target both simultaneously.
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.

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