---
title: "Create a booking"
method: POST
path: "/book"
---

# Create a booking

`POST /book`

## Request

- Base URL: `https://api.tellandgo.com/api/v1/agent`
- URL: `https://api.tellandgo.com/api/v1/agent/book`
- Auth: API key in header `X-API-Key`

Creates a booking from a valid quote. Quotes that require prebook must be
locked before payment. Provide at least one valid adult lead guest per
booked room. Do not send placeholder guests for children or unnamed
occupants; the quote already stores the occupancy. Returns a
Stripe-hosted checkout URL for payment by default. `stripe_checkout`
is a hosted browser payment flow, not a headless server-to-server
payment call: redirect the customer browser to the returned
`payment.url`. After payment, Tell&Go confirms the booking server-side
from the Stripe webhook and supplier status checks. API consumers can
read final status with GET /bookings/{id} and may optionally register
partner webhooks for async status events.

## Headers

- `Idempotency-Key` string, required

## Request body

- BookingRequest
  - `quote_id` string, required
  - `guests` object[], required: Guest details. Provide at least one valid adult lead guest per booked room. Remaining occupants from the quote are not auto-populated into supplier guest names.
    - `first_name` string, required
    - `last_name` string, required
    - `email` string, email
    - `phone` string
    - `is_primary` boolean
    - `is_child` boolean: Optional; only set when providing accurate child details.
    - `age` number: Required when is_child is true.
  - `special_requests` string
  - `payment_method` 'stripe_checkout' | 'redirect': Payment method. `stripe_checkout` (default) returns a Stripe-hosted payment URL. `redirect` (deprecated) returns a URL to our checkout page.
  - `success_url` string, uri: Optional HTTPS URL to return the payer to after Stripe-hosted checkout succeeds. Tell&Go appends booking_id and session_id when missing.
  - `cancel_url` string, uri: Optional HTTPS URL to return the payer to if Stripe-hosted checkout is cancelled. Tell&Go appends booking_id and payment=cancelled when missing.

## Response `201`

Booking created

- BookingResponse
  - `success` boolean
  - `booking` object
    - `id` string
    - `status` 'pending_payment' | 'confirmed' | 'cancelled' | 'completed'
    - `reference` string
    - `confirmation_number` string
    - `property` object
      - `id` string
      - `name` string
    - `room` object
      - `name` string
    - `dates` object
      - `check_in` string, date
      - `check_out` string, date
      - `nights` integer
    - `guests` object[]
      - `name` string
      - `is_primary` boolean
    - `payment` object
      - `method` 'stripe_checkout' | 'redirect': Payment method used
      - `status` 'pending' | 'completed' | 'failed' | 'refunded'
      - `amount` number
      - `currency` string
      - `url` string, uri: Payment URL. For hosted checkout, this is a hosted payment page.
      - `session_id` string: Hosted checkout session ID (only for hosted checkout)
      - `expires_at` string, date-time
    - `created_at` string, date-time

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid
- `404`: Resource not found

---

[API](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api.md) · [All operations](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tellandgo/apis/tell-go-travel-agent-api/revisions/3d84f816eb4f?raw)