---
title: "Get Booking By Confirmation"
method: GET
path: "/bookings/ref/{ref}"
tags: ["Bookings"]
---

# Get Booking By Confirmation

`GET /bookings/ref/{ref}`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/bookings/ref/{ref}`
- Auth: HTTP bearer

Retrieve a booking, or a multi-stay checkout, by its lookup secret.

*ref* is a booking's confirmation number (``TP-{property}-{32 hex}``) or
a multi-stay checkout's bearer (``TPC-{32 hex}``, Phase 4 Stage 6a). Each
acts as a bearer secret for unauthenticated access (post-checkout
confirmation page). Rate-limited to prevent enumeration.

- A checkout bearer returns ``checkout``: every stay, each stay's lines,
  and the one payment. The top-level fields describe the first stay's
  first booking. It finds nothing until the checkout has booked.
- A booking's confirmation number returns that booking, its Phase 2
  ``group``, and, when it belongs to a multi-stay checkout, only a
  ``checkout_pointer``. Each park holds its own booking's number (the
  PMS UniqueID), so it never sees the guest's other parks.
- A ``TPC-`` display code is not a lookup key.

## Path parameters

- `ref` string, required

## Headers

- `API-Version` '1'

## Response `200`

Booking details retrieved successfully

- BookingDetailResponse: Detailed booking response for confirmation page.
  - `booking_id` integer, required: Total Parks booking ID
  - `confirmation_number` string, required: Bearer-secret confirmation number. Used in `?ref=...` URLs and the unauthenticated `GET /bookings/ref/{confirmation_number}` lookup. **Do not display to humans — use `booking_code` instead.**
  - `pms_confirmation_id` string, nullable: PMS confirmation/reservation ID
  - `status` string, required: Reservation status (e.g., 'confirmed')
  - `payment_status` string, required: Payment status (e.g., 'succeeded')
  - `check_in` string, date, required: Check-in date
  - `check_out` string, date, required: Check-out date
  - `adults` integer, required: Number of adults
  - `children` integer: Number of children
  - `infants` integer: Number of infants
  - `total` string, required: Accommodation subtotal (PMS nightly rates only). Excludes pet_fee_total and service_fee.
  - `pet_fee_total` string, nullable: Pet fee charged to the guest (park revenue, refundable). None for legacy bookings; treat as zero.
  - `service_fee` string, required: Total Parks service fee
  - `grand_total` string, nullable: Total Stripe charge amount (total + pet_fee_total + service_fee).
  - `currency` string, required: Currency code (ISO 4217)
  - `discount_amount` string, nullable: Phase 3 — realised discount applied to the accommodation total. Null on legacy or non-promo bookings; treat as zero. The confirmation page renders a `Discount` row when this is > 0.
  - `campaign_id` integer, nullable: Phase 3 — TP-side campaign id (joined to ``campaigns.id``).
  - `promo_code` string, nullable: Phase 3 — canonical promo code applied to this booking, resolved via ``Booking.campaign_id → Campaign.code``.
  - `guest_first_name` string, required: Guest's first name
  - `guest_last_name` string, required: Guest's last name
  - `guest_email` string, required: Guest's email address
  - `guest_phone` string, required: Guest's phone number
  - `special_requests` string, nullable: Guest comments
  - `property_id` integer, required: Property ID
  - `property_name` string, required: Property name
  - `property_slug` string, required: Property URL slug
  - `property_state` string, required: Property state
  - `property_address` string, required: Property address
  - `property_email` string, nullable: Property contact email
  - `property_phone` string, nullable: Property contact phone
  - `room_type_id` integer, required: Room type ID
  - `room_type_name` string, required: Room type name
  - `room_type_slug` string, required: Room type URL slug
  - `pet_booking_mode` string, nullable: Effective pet booking mode applied to this booking.
  - `pet_declaration` PetDeclaration: Pet declaration captured during checkout.
    - `traveling_with_pets` boolean: Whether the guest is travelling with pets.
    - `pet_count` integer, nullable: Number of pets travelling.
    - `pet_type` string, nullable: Primary pet type (e.g. dog).
    - `pet_size` 'small' | 'medium' | 'large', nullable: Optional pet size declaration.
    - `pet_weight_kg` number, nullable: Optional pet weight in kilograms.
    - `pet_breed_attestation` PetBreedAttestation: Guest attestation for property-level restricted breed lists.
      - `attested_at` string, date-time, required: When the guest confirmed their pet is not a restricted breed.
      - `restricted_list_snapshot` string[], required: Restricted breed slugs shown to the guest at attestation time.
  - `equipment_type` string, nullable: Canonical equipment type (e.g. 'caravan', 'motorhome'). Set at booking time for site bookings; always None for cabins and for legacy bookings pre-dating migration 096.
  - `equipment_length` string, nullable: Equipment length in metres (site bookings only).
  - `created_at` string, date-time, required: Booking creation timestamp
  - `is_linked_to_account` boolean: Whether this booking is linked to a user account
  - `group` BookingGroupSummary: Phase 2 group booking: N lines paid with one PaymentIntent.
    - `reference` string, required: Group display reference: the primary (position 0) booking's booking_code. There is no separate cart-level identifier.
    - `line_count` integer, required
    - `position` integer, required: Position of the looked-up booking within the group
    - `total` string, required: Sum of line accommodation subtotals
    - `pet_fee_total` string, required
    - `discount_amount` string, required
    - `service_fee` string, required: The one cart service fee
    - `grand_total` string, required: The one Stripe charge amount
    - `currency` string, required
    - `bookings` BookingGroupLine[], required: Every line in stable position order
      - `booking_id` integer, required: Total Parks booking ID for this line
      - `booking_code` string, required: Human-readable code for this line. The sibling's bearer-secret confirmation_number is never exposed here.
      - `position` integer, required: 0-based line position; 0 is the primary
      - `status` string, required: Reservation status of this line
      - `room_type_id` integer, required
      - `room_type_name` string, required
      - `adults` integer, required
      - `children` integer
      - `infants` integer
      - `equipment_type` string, nullable
      - `equipment_length` string, nullable
      - `pet_declaration` PetDeclaration: Pet declaration captured during checkout.
        - `traveling_with_pets` boolean: Whether the guest is travelling with pets.
        - `pet_count` integer, nullable: Number of pets travelling.
        - `pet_type` string, nullable: Primary pet type (e.g. dog).
        - `pet_size` 'small' | 'medium' | 'large', nullable: Optional pet size declaration.
        - `pet_weight_kg` number, nullable: Optional pet weight in kilograms.
        - `pet_breed_attestation` PetBreedAttestation: Guest attestation for property-level restricted breed lists.
          - `attested_at` string, date-time, required: When the guest confirmed their pet is not a restricted breed.
          - `restricted_list_snapshot` string[], required: Restricted breed slugs shown to the guest at attestation time.
      - `special_requests` string, nullable
      - `guest_first_name` string, required: Lead guest for this line
      - `guest_last_name` string, required: Lead guest for this line
      - `pms_reference` string, nullable: This line's own park (PMS) reservation reference, when assigned. Never the TP confirmation number: NewBook children use their UniqueID (the TP confirmation number) as pms_confirmation_id, so the NewBook reservation ID is shown instead.
      - `total` string, required: Accommodation subtotal (pre-discount)
      - `pet_fee_total` string
      - `discount_amount` string
      - `service_fee` string, required: Allocated share of the cart service fee
      - `grand_total` string, required: This line's share of the one charge
  - `checkout` CheckoutSummary: A checkout that booked stays at several parks on one payment (D-04). Returned only for the ``TPC-`` bearer, never for one booking's own confirmation number, because each park holds its own booking's number.
    - `checkout_code` string, required: The ``TPC-`` display code (``TPC-`` plus 8 hex characters). Labelled "Total Parks reference"; not a lookup key.
    - `stays_count` integer, required
    - `line_count` integer, required
    - `stays` CheckoutStay[], required: Every stay in date order (earliest check-in first).
      - `stay_id` integer, required
      - `property_id` integer, required
      - `property_name` string, required
      - `property_slug` string, required
      - `property_state` string, nullable
      - `property_address` string, nullable
      - `property_email` string, nullable
      - `property_phone` string, nullable
      - `cancellation_policy_note` string, nullable: The park's free-text cancellation terms, when it has any.
      - `check_in` string, date, required: Earliest line check-in
      - `check_out` string, date, required: Latest line check-out
      - `line_count` integer, required
      - `lines` BookingGroupLine[], required: Every room or site of this stay in line order, each with that park's own booking_code. Never a booking's confirmation_number.
        - `booking_id` integer, required: Total Parks booking ID for this line
        - `booking_code` string, required: Human-readable code for this line. The sibling's bearer-secret confirmation_number is never exposed here.
        - `position` integer, required: 0-based line position; 0 is the primary
        - `status` string, required: Reservation status of this line
        - `room_type_id` integer, required
        - `room_type_name` string, required
        - `adults` integer, required
        - `children` integer
        - `infants` integer
        - `equipment_type` string, nullable
        - `equipment_length` string, nullable
        - `pet_declaration` PetDeclaration: Pet declaration captured during checkout.
          - `traveling_with_pets` boolean: Whether the guest is travelling with pets.
          - `pet_count` integer, nullable: Number of pets travelling.
          - `pet_type` string, nullable: Primary pet type (e.g. dog).
          - `pet_size` 'small' | 'medium' | 'large', nullable: Optional pet size declaration.
          - `pet_weight_kg` number, nullable: Optional pet weight in kilograms.
          - `pet_breed_attestation` PetBreedAttestation: Guest attestation for property-level restricted breed lists.
            - `attested_at` string, date-time, required: When the guest confirmed their pet is not a restricted breed.
            - `restricted_list_snapshot` string[], required: Restricted breed slugs shown to the guest at attestation time.
        - `special_requests` string, nullable
        - `guest_first_name` string, required: Lead guest for this line
        - `guest_last_name` string, required: Lead guest for this line
        - `pms_reference` string, nullable: This line's own park (PMS) reservation reference, when assigned. Never the TP confirmation number: NewBook children use their UniqueID (the TP confirmation number) as pms_confirmation_id, so the NewBook reservation ID is shown instead.
        - `total` string, required: Accommodation subtotal (pre-discount)
        - `pet_fee_total` string
        - `discount_amount` string
        - `service_fee` string, required: Allocated share of the cart service fee
        - `grand_total` string, required: This line's share of the one charge
      - `total` string, required: Accommodation subtotal (pre-discount)
      - `pet_fee_total` string, required
      - `discount_amount` string, required
      - `service_fee` string, required: This stay's own service fee (D-03)
      - `grand_total` string, required: This stay's share of the one charge
      - `currency` string, required
    - `payment` CheckoutPayment, required: The one charge that paid for every stay.
      - `grand_total` string, required: The one Stripe charge amount
      - `currency` string, required
      - `payment_status` string, nullable
      - `statement_descriptor_suffix` string, nullable
      - `statement_descriptor` string, nullable: The card statement line, ``{prefix}* {suffix}``; null when the platform prefix is not configured.
  - `checkout_pointer` CheckoutPointer: That a booking belongs to a multi-stay checkout, without its other parks.
    - `checkout_code` string, required
    - `stays_count` integer, required
  - `booking_code` string, required: Human-readable short code derived from ``confirmation_number``.

## Other responses

- `404`: Booking not found
- `422`: Validation Error

---

[API](https://skmtc.dev/totalparks/apis/total-parks-public-api.md) · [All operations](https://skmtc.dev/totalparks/apis/total-parks-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/totalparks/apis/total-parks-public-api/revisions/dcb4c822e2c6?raw)