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:

Query Timezones¶

An availability query involves up to three zones, and a slot offset such as -04:00 names none of them: an offset identifies an instant, not a clock, and it cannot be used to find the next local day across a daylight-saving transition. A platform may also reach this operation without having read the USP profile (for example, after UCP discovery), so it cannot rely on business.timezone from the business profile. The query therefore uses three fields, each named for its one meaning:

All three are IANA Time Zone Database identifiers.

Resolving the range.

• A date-only start_date resolves to 00:00 on that day in the applied date-bounds timezone. A date-only end_date includes that whole day: the range ends at 00:00 on the following day in that timezone. Days are resolved on the local calendar, so a day containing a daylight-saving transition is 23 or 25 hours long.
• A date-time bound carries an offset and is already an instant. date_bounds_timezone MUST NOT change its meaning. When both bounds are date-times, date_bounds_timezone has no effect on the range; applied_date_bounds_timezone still reports the zone the business would have applied to a date-only bound.
• date_bounds_timezone is optional. A platform that does not know the business timezone SHOULD omit it and send date-only bounds, so the business reads the requested days in its own zone.

What the business returns.

• The response MUST carry applied_date_bounds_timezone: the request date_bounds_timezone when the request carried one, otherwise the business timezone.
• The response MUST carry business_timezone: the business's own zone, equal to business.timezone in its USP profile. It does not change with date_bounds_timezone. When the request omits date_bounds_timezone, the two response fields are equal.
• Slot start and end remain RFC 3339 instants that carry an offset. Neither response field replaces or corrects that offset, and platforms MUST NOT infer a timezone from it.
• opening_hours are local times in business_timezone, whatever the request date_bounds_timezone.

What the platform does with them.

• To show a slot, convert its start and end instants into the zone being shown: business_timezone for the business's clock, the buyer's own zone for the buyer's clock. Platforms SHOULD use business_timezone, not applied_date_bounds_timezone, to name the business's clock and to compare it with the buyer's.
• To fetch the next window, send the next date-only range with the same date_bounds_timezone (or none). Do not add 24 hours to a slot offset.
• A platform that receives a response without a valid business_timezone SHOULD show slot times using each slot's own offset, SHOULD tell the user that the business did not name its timezone, and SHOULD NOT abandon the query on that basis alone.

{
  "service_id": "svc_haircut_001",
  "start_date": "2026-03-15",
  "end_date": "2026-03-21",
  "date_bounds_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",
  "applied_date_bounds_timezone": "America/New_York",
  "business_timezone": "America/New_York",
  "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.

When the booking questions extension is negotiated and the service has an applicable required preflight set, the request MUST carry booking_question_assessment_token from an eligible decision. The business MUST revalidate the token's scope, expiry, and set revisions before reserving capacity, and MUST reject a missing token with booking_eligibility_required and an expired or stale one with booking_eligibility_expired, creating no hold.

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