# Bookings across businesses

Availability, holds, bookings and changes across many businesses at once, for your own customers.

## Availability across businesses

`POST /bookings/availability/batch` answers up to 50 services in different businesses in one call, each with its slots or its own error. Every slot says its `capacity` and the `seatsLeft` for the party you asked. Call it from your server and keep the answer for seconds, not longer.

Request:

```
curl -sS https://api.rivier.ai/bookings/availability/batch \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-12-01T00:00:00Z", "to": "2026-12-08T00:00:00Z", "partySize": 2, "items": [{"business": "$A", "serviceId": "$SERVICE_A"}, {"business": "$B", "serviceId": "$SERVICE_B"}]}'
```

## Holding places, all or none

`POST /bookings/holds/batch` holds places in several businesses at once, or none: a failure names the items that could not be held. `owner` is your own name for who holds (a trip, a conversation); the same owner holding again releases what it held before. Read it back with `GET /bookings/holds/batch/{owner}`.

Request:

```
curl -sS https://api.rivier.ai/bookings/holds/batch \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "trip:981", "idempotencyKey": "trip-981-1", "holdMinutes": 20, "items": [{"business": "$A", "serviceId": "$SERVICE_A", "start": "2026-12-02T09:00:00Z"}, {"business": "$B", "serviceId": "$SERVICE_B", "start": "2026-12-03T14:00:00Z", "partySize": 2}]}'
```

## Booking for your customer

Book in each business with its `holdId` and `platformCustomer` instead of a contact: the person is linked to the business as its contact, and nothing else of them is copied there. `metadata` carries your own references. A hold that ran out is refused as `hold_expired` and books nothing.

Request:

```
curl -sS https://api.rivier.ai/bookings \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "x-rivier-business: $A" \
  -H "Content-Type: application/json" \
  -d '{"serviceId": "$SERVICE_A", "start": "2026-12-02T09:00:00Z", "holdId": "$HOLD_A", "platformCustomer": "$CUSTOMER", "metadata": {"trip": "981"}, "idempotencyKey": "trip-981-a"}'
```

## Changing and cancelling

`POST /bookings/reschedule/batch` moves several bookings, all or none, taking the new places before giving up the old. A cancel says `by`: `customer` when you pass on your customer's own cancel (the business's policy applies) or `platform` for your own, which costs the customer nothing. Every change takes an idempotency key.

## Your customers

`GET /platform-customers/{id}/bookings` lists what you booked for a customer in every business. `POST /platform-customers/{id}/export` gives one file of what Rivier holds for them. `DELETE /platform-customers/{id}?erase=bookings` erases them: coming bookings are cancelled, every booking stays the business's record without your link and data, and each business is asked to erase its contact.

## What you hear

Every booking event says `by` (business, platform, customer, rule, system), `reason`, your `metadata` and the `platformCustomer`. A request the business declines is `bookings.booking.cancelled` with reason `declined`; one nobody answered in time is `.expired`; a hold that lapsed is `bookings.hold.expired`.
