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: Resource-only and pair rows use the resource timezone (then its location, then company). Service-level rows use the service’s location timezone, then company. GET /v3/weeklyAllocation formats each row with that same rule so listed startDate/endDate match create.
• 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.

Same-slot capacity (bookingsPerSlot, service+resource only)

Optional cap on how many concurrent appointments may occupy the same instant for a service+resource weekly allocation (both ServiceId and ResourceId on create/set). This is not an ISO-week booking quota.

Service-only or resource-only weekly allocations do not accept or return bookingsPerSlot. Weekly booking quota fields are rejected. For capacity on other scopes, use bookingsPerSlot on Service, Resource, or SingleAllocation.

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

When concurrent capacity at a slot is exhausted, GET /v3/availability omits that slot; other slots in the same week remain available.

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), a resource with no pair row for that service does not inherit resource-wide leftover. GET /v3/availability with that resource id still returns 200 with no slots. Pair hours trim leftover only on days the resource-wide calendar already covers; they do not open days the provider did not grant. 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: Pass allocation times as wall-clock hours for the location you book. Availability converts those hours using the request LocationId timezone (not a frozen schedule iana from another location or the company default).
• 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.
• Merchant portal Resource → Allocations: The allocation scope filter chooses one write-set. Resource-wide allocations (default) shows and saves resource-wide windows only (ResourceId, no ServiceId); pair rows are omitted from that replace. One linked service shows and saves that resource's resource-specific allocations (ServiceId + ResourceId), including pair bookingsPerSlot. All service-specific allocations lists every pair for the resource, grouped by service, read-only, with no Save. Pair editors show that resource's overlapping resource-wide leftover hours; they do not change the leftover by saving the pair. GET by ResourceId can still return mixed rows; the portal filters the visible set client-side.

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

Resource-hours coverage warnings

Allocation saves remain successful even when resource hours do not cover the saved
service-specific hours. Native weekly and single allocation create, replace, update
(where supported), and delete responses include a sibling warnings array alongside
success and the existing data. Resource updates and weekly-availability saves
also recheck remaining service-specific allocations, so shortening or deleting
resource-wide hours can produce warnings about existing allocations.

• RESOURCE_AVAILABILITY_UNCOVERED: coverage: "none" means none of the remaining
  hours are covered; "partial" means only some are. The warning identifies the
  resource, service and weekly allocation, and includes a tip and repair action.
• RESOURCE_AVAILABILITY_CHECK_UNAVAILABLE: the save succeeded, but the advisory
  could not finish (for example, a read failure or an unusually large configuration).
  This does not mean the hours are covered. Review the resource's settings.
• warnings: []: no resource-hours gaps were found for the checked scope. This
  does not guarantee bookable slots: service/location hours, duration, padding,
  capacity, booking rules, appointments and external-calendar conflicts still apply.

Checks cover the full remaining stored allocation period, excluding elapsed time.
When that remaining window is shorter than a week, the check still samples one extra
week from the remaining start so each pair-open weekday is evaluated (Sunday-only
hours on a Friday–Saturday card still warn if the resource is closed Sunday).
Up to three uncovered intervals are returned per allocation, with their UTC offsets
and timezone. These are examples, not a shortened checking horizon. When a resource
inherits different location timezones, warnings identify the relevant LocationId.

A resource in allocation mode needs resource-wide coverage for its weekly pair
hours. A resource in schedule mode can legitimately have no resource-wide
allocations. Valid overrides are respected: one-time pair allocations add available
resource time, and weekly pairs can reopen a fully closed schedule day.

In the Merchant Portal, Saved with warnings displays a persistent panel after
saving, grouped by resource and service. Use Edit resource availability to open
Resource → Allocations or Resource → Availability. Saves that span multiple requests
can partially succeed; the portal reports this and retains the edits for review.
Warnings describe the configuration at save time, not an ongoing availability monitor.