# Availability Alternatives

Occasionally a booking that looked available at the time it was reserved will fail confirmation — the supplier's inventory changed, the local availability cache was momentarily stale, or a capacity limit was hit before your customer clicked "confirm". This has always returned a 422 error, and it always will.

To make recovery smoother, we now attach optional `alternatives` to that error. When enabled for your API key, a failed `PUT /v2/bookings/{uuid}/confirm` response tells you what else is bookable right now — so your customer flow can offer another timeslot or date without a second round-trip.

This is an **opt-in additive change**: partners that haven't enabled it see identical responses to before.

## Enabling the feature

Contact your BeMyGuest account manager to have it enabled for you in the demo environment, once you've tested against it in the demo environment you can request for it to be enabled on production.

## Response shape

The `alternatives` object appears alongside the usual `code` / `message` / `http_code` fields on a 422 response. Its contents depend on the product type and on what's still bookable.

### Requested slot

Always echoed back so you can correlate the response with the failing request:

```json
"requested": {
  "date": "2026-08-10",
  "timeslot": "10:00"
}
```

`timeslot` is present for timeslotted products only.

### Timeslotted products — same-date fallback

If the requested date still has other timeslots with capacity, every one of them is returned:

```json
"alternatives": {
  "requested": { "date": "2026-08-10", "timeslot": "10:00" },
  "same_date_timeslots": [
    { "timeslot": "09:00", "qty": 3 },
    { "timeslot": "11:00", "qty": 4 },
    { "timeslot": "14:30", "qty": 6 }
  ],
  "nearby_dates": []
}
```

### Timeslotted products — next-available-day fallback

If the whole requested date is sold out, the next future date with any bookable timeslot (scanned up to 7 days forward) is returned as a single entry:

```json
"alternatives": {
  "requested": { "date": "2026-08-10", "timeslot": "10:00" },
  "same_date_timeslots": [],
  "nearby_dates": [
    {
      "date": "2026-08-11",
      "qty": 7,
      "timeslots": [
        { "timeslot": "09:00", "qty": 2 },
        { "timeslot": "10:00", "qty": 5 }
      ]
    }
  ]
}
```

We deliberately return only the next available day, not the full week, to keep payloads small for products that fire many timeslots per day.

### Non-timeslotted products

Up to three future dates within the next three days that have any bookable capacity:

```json
"alternatives": {
  "requested": { "date": "2026-08-10" },
  "same_date_timeslots": [],
  "nearby_dates": [
    { "date": "2026-08-11", "qty": 5 },
    { "date": "2026-08-12", "qty": 2 },
    { "date": "2026-08-13", "qty": 8 }
  ]
}
```

## `qty` semantics

Reported `qty` values are the maximum any single price category could book at that slot — an upper bound. They are informational hints, not booking guarantees: **before confirming an alternative for a customer you should validate it against a fresh availability check.** Inventory can change between the moment we compute the alternatives and the moment your customer commits.

## Absent fields

- `alternatives` is omitted entirely when the feature is disabled for your API key.
- `alternatives` is omitted when we cannot compute any suggestion (e.g. the booking has no attached product type).
- Within `alternatives`, `same_date_timeslots` and `nearby_dates` are always both present as arrays — either or both may be empty when we have nothing to offer.


## Backwards compatibility

`alternatives` is a strictly additive field. Existing clients that don't parse it will continue to work unchanged. The error `code`, `message`, and `http_code` fields on the 422 response are unaffected.