---
title: "Booking status: state machine position + structured outcome"
method: GET
path: "/v1/bookings/{booking_id}"
---

# Booking status: state machine position + structured outcome

`GET /v1/bookings/{booking_id}`

## Request

- Base URL: `https://mercantry.org`
- URL: `https://mercantry.org/v1/bookings/{booking_id}`
- Auth: none declared

## Path parameters

- `booking_id` string, uuid, required

## Query parameters

- `include_events` boolean

## Response `200`

Booking status.

- BookingStatus: Booking state machine position with structured outcome details.
  - `booking_id` string, uuid
  - `merchant_id` string, uuid
  - `state` 'pending' | 'queued' | 'in_progress' | 'needs_input' | 'confirmed' | 'failed' | 'cancelled'
  - `failure_reason` 'no_answer' | 'fully_booked' | 'closed' | 'policy_mismatch' | 'merchant_declined' | 'bad_data' | 'expired_sla' | 'needs_input_timeout'
  - `requested_time` string
  - `window_minutes` integer
  - `party_size` integer
  - `confirmed_time` string
  - `confirmation_code` string
  - `merchant_instructions` string
  - `needs_input_options` object[]: Merchant-offered alternatives awaiting the agent's decision (resolve via /v1/bookings/{id}/modify).
    - `time` string
    - `note` string
  - `needs_input_deadline` string
  - `attempts` integer
  - `sla_deadline` string: Terminal state guaranteed by this time (REQ-FUL-6).
  - `created_at` string
  - `updated_at` string

## Other responses

- `404`: unknown_booking.

---

[API](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror.md) · [All operations](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror/llms.txt) · [OpenAPI document](https://skmtc.dev/mercantry/apis/registry-agent-native-merchant-registry-rest-mirror/revisions/0a9bf614fe96?raw)