Single Allocation Guide

When to Use

• Offer temporary pop-up availability (e.g., “Open house on July 6 from 10–14”).
• Block time for one-off events such as training sessions or holidays.
• Apply overrides for a resource, for a service (all linked resources), or for a specific resource on a specific service without rewriting the global schedule.

Concepts

• Date-based windows: Define explicit startDate / endDate timestamps (ISO 8601 strings). They can span multiple days.
• Target scope: You must provide at least one of ResourceId or ServiceId. Optionally provide both for pair scope (that resource when booked for that service only).
• Description: Optional field to help internal teams understand why the override exists.

Pair-scoped single allocations follow the same layering rules as pair weekly allocations: they apply to the service+resource combination and set Service.availabilityType to allocation when needed; they do not by themselves flip Resource.availabilityType the way resource-only allocations do.

Endpoint Overview

Payload Examples

Resource-specific allocation:

{
  "ResourceId": "<uuid>",
  "startDate": "2025-07-06T10:00:00-04:00",
  "endDate": "2025-07-06T14:00:00-04:00",
  "description": "Open studio session"
}

Service-wide allocation (applies to all resources linked to the service):

{
  "ServiceId": "<uuid>",
  "startDate": "2025-07-06T10:00:00-04:00",
  "endDate": "2025-07-06T14:00:00-04:00",
  "description": "Holiday special hours"
}

Pair-scoped allocation (one resource on one service):

{
  "ServiceId": "<service-uuid>",
  "ResourceId": "<resource-uuid>",
  "startDate": "2025-07-06T10:00:00-04:00",
  "endDate": "2025-07-06T14:00:00-04:00",
  "description": "Extra shift for this provider on this service"
}

• Dates must be ISO-8601 compliant; the API stores them in UTC internally.
• With only ServiceId, the override applies to every eligible resource linked to that service.
• With both IDs, the override applies to that resource in the context of that service only.

Editing Strategies

• Bulk Manage: setSingleAllocations is ideal for UI workflows like drag-and-drop calendars. Submit allocations: [ ... ] together with the same ServiceId / ResourceId (or pair) you use for create. The API replaces the existing set for that scope atomically.
• Incremental Changes: Use the standard CRUD endpoints when scripts need to add or remove a single override.

Interaction with Availability

Single allocations combine with weekly allocations and other layers:

• Add availability: Create an allocation that represents extra working hours outside the usual schedule.
• Remove availability: Pair single allocations with recurring blocks or delete conflicting weekly windows to prevent slot creation.
• Pair scope: Affects availability for the given resource on that service only; other resources on the service keep their normal rules unless they have their own overrides.

Every create/update/delete call invalidates availability caches so new slots reflect the change immediately.

Troubleshooting

• Missing ResourceId/ServiceId: The API returns a validation error if you omit both. Send at least one; send both for pair scope.
• Overlapping windows: Overlaps are allowed, but they may create duplicate-looking availability. Keep your overrides tidy to avoid confusion in admin tools.
• Time zone confusion: Always pass localized timestamps (e.g., America/New_York). When in doubt, append the offset explicitly.

Single allocations give you precise control over exceptional days without rewriting your recurring schedule.