Availability¶

Capability: dev.usp-protocol.services.availability

The availability capability lets platforms query when services are available and, optionally, hold slots to prevent double-booking during the booking flow.

Feature Flags¶

Businesses declare feature flags inside the capability entry in their profile:

"dev.usp-protocol.services.availability": [
  {
    "version": "2026-08-20",
    "holds": true
  }
]

When holds is false or absent, the booking flow proceeds directly from slot query to booking creation without an intermediate hold step.

Time Slot¶

A time slot represents a specific, bookable combination of a time window and assigned resources, computed dynamically by the business from schedules, resource calendars, and existing bookings.

Time Slot Schema¶

Slot State Values¶

Hold¶

A hold is a temporary reservation of a time slot that prevents double-booking during the booking flow. Holds have a short TTL and are automatically released when they expire, are explicitly released, or are converted to a booking.

Hold Schema¶

Concurrent Hold Rules¶

The business MUST enforce hold concurrency rules matching the service's capacity model:

Hold Conversion¶

A hold exists to make the gap between slot selection and booking safe. That is only true if converting it cannot lose the reservation, so conversion is specified rather than left to each implementation.

Capacity accounting. Hold.spots and the booking request's party_size count the same capacity units from opposite ends of the flow: spots is what was reserved, party_size is what is being booked.

• With a hold_id, party_size (default 1) MUST NOT exceed the hold's spots (default 1). Exceeding it returns capacity_exceeded, because the surplus was never reserved and another buyer may hold it.
• A party_size lower than spots is allowed; unused spots MUST return to capacity.remaining on conversion.
• Without a hold_id, party_size is checked directly against capacity.remaining at booking time.

Conversion is atomic. Either the booking is created and the hold moves to converted, or neither happens. A hold MUST NOT be left converted with no booking, and a booking MUST NOT be created from a hold left active where it could convert again.

Two rows are deliberate. A converted hold replayed with the same request returns the existing booking rather than an error, which is what makes hold_id usable as an idempotency key. And capacity_exceeded leaves the hold active, so the platform can retry with a party_size that fits instead of losing the reservation.

An unrecognized hold_id returns validation_error, not hold_expired: the platform needs to tell a bad identifier from a lapsed reservation.

Operations¶

Query Availability -- POST /availability/query¶

Returns available time slots for a service within a date range. Use the Availability Hint on the service entity to narrow the date range before querying.

Request Fields:

{
  "service_id": "svc_haircut_001",
  "start_date": "2026-03-15",
  "end_date": "2026-03-21",
  "timezone": "America/New_York",
  "resource_id": "staff_jane",
  "location_id": "loc_main",
  "locale": "en-US"
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.availability": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "service_id": "svc_haircut_001",
  "slots": [
    {
      "id": "slot_20260315_0900",
      "service_id": "svc_haircut_001",
      "start": "2026-03-15T09:00:00-04:00",
      "end": "2026-03-15T10:00:00-04:00",
      "duration": "PT60M",
      "state": "available",
      "resources": [
        { "id": "staff_jane", "type": "staff", "name": "Jane Smith" }
      ],
      "location": { "id": "loc_main", "name": "Downtown Studio" }
    },
    {
      "id": "slot_20260315_1030",
      "service_id": "svc_haircut_001",
      "start": "2026-03-15T10:30:00-04:00",
      "end": "2026-03-15T11:30:00-04:00",
      "duration": "PT60M",
      "state": "available",
      "resources": [
        { "id": "staff_jane", "type": "staff", "name": "Jane Smith" }
      ],
      "location": { "id": "loc_main", "name": "Downtown Studio" }
    }
  ],
  "opening_hours": [
    {
      "day_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "opens": "09:00",
      "closes": "18:00"
    },
    {
      "day_of_week": ["saturday"],
      "opens": "10:00",
      "closes": "16:00"
    }
  ],
  "pagination": { "cursor": null, "has_more": false }
}

Response Fields:

opening_hours[] Fields:

Slots are returned in ascending start order.

Hold Slot -- POST /availability/holds¶

Creates a temporary hold on a time slot to prevent double-booking while the buyer completes the booking flow.

{
  "slot_id": "slot_20260315_0900",
  "service_id": "svc_haircut_001",
  "spots": 1
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.availability": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "hold": {
    "id": "hold_abc123",
    "slot_id": "slot_20260315_0900",
    "service_id": "svc_haircut_001",
    "spots": 1,
    "expires_at": "2026-03-15T08:10:00-04:00",
    "status": "active"
  }
}

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {}
  },
  "messages": [
    {
      "type": "error",
      "code": "slot_unavailable",
      "content": "The requested slot is no longer available.",
      "severity": "recoverable"
    }
  ]
}

Release Slot -- DELETE /availability/holds/{hold_id}¶

Explicitly releases a hold before it expires, freeing the slot for other buyers.

DELETE /availability/holds/hold_abc123

{
  "usp": {
    "version": "2026-08-20",
    "capabilities": {
      "dev.usp-protocol.services.availability": [
        { "version": "2026-08-20" }
      ]
    }
  },
  "hold": {
    "id": "hold_abc123",
    "slot_id": "slot_20260315_0900",
    "service_id": "svc_haircut_001",
    "spots": 1,
    "expires_at": "2026-03-15T08:10:00-04:00",
    "status": "released"
  }
}

Caching Strategy¶

Availability data has an inverse relationship between freshness and usefulness: near-term slots are the most actionable but change the fastest, while far-out availability is stable but less immediately useful. Platforms SHOULD use a tiered caching strategy:

This creates a natural funnel that balances user experience with data freshness:

graph TD
    H["1. Availability Hint (catalog-cached; valid_until cutout)"] -- "Agent narrows date range" --> S
    S["2. Slot Query (slot-level, short cache)"] --> D["Agent picks a slot"]
    D --> E{"3. Holds supported?"}
    E -- "Yes" --> F["Hold Slot (real-time)"]
    F --> G["4. Create Booking"]
    E -- "No" --> G