> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plec-it.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create booking

> Create a new booking request. Returns either approval_required (host must approve), instant checkout URL, or payment sheet credentials.



## OpenAPI

````yaml POST /bookings/create
openapi: 3.0.0
info:
  title: PLEC API
  description: PLEC backend API reference
  version: '1.0'
  contact: {}
servers:
  - url: https://api.plec-it.com
    description: Production
  - url: https://api-staging.plec-it.com
    description: Staging
  - url: http://localhost:3000
    description: Local Development
security: []
tags: []
paths:
  /bookings/create:
    post:
      tags:
        - Bookings
      summary: Create booking
      description: >-
        Create a new booking request. Returns either approval_required (host
        must approve), instant checkout URL, or payment sheet credentials.
      operationId: BookingsController_createBooking
      parameters:
        - name: dryRun
          required: true
          in: query
          description: >-
            When true, validates and simulates the request but performs no
            writes. Recommended when calling from docs.
          schema:
            type: string
            enum:
              - 'true'
            default: 'true'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookingDto'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBookingResponseDto'
        '400':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '401':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '404':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '409':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
      security:
        - bearer: []
components:
  schemas:
    CreateBookingDto:
      type: object
      properties:
        items:
          description: Booking line items (venue and/or services)
          type: array
          items:
            $ref: '#/components/schemas/CreateBookingItemDto'
        date:
          type: string
          description: Booking date (ISO date)
          example: '2025-12-04'
        time:
          type: string
          description: Start time
          example: '09:00'
        duration:
          type: object
          description: Duration in hours
          example: 4
        startTime:
          type: string
          description: Start timestamp (ISO)
          example: '2025-12-04T09:00:00Z'
        endTime:
          type: string
          description: End timestamp (ISO)
          example: '2025-12-04T13:00:00Z'
        packageId:
          type: string
          description: 'DEPRECATED: Use items[].selectedPackages instead'
        upgradeBookingId:
          type: object
          description: If provided, upgrade existing booking instead of creating new one
        specialRequests:
          type: string
          description: Optional message to host (e.g. purpose of event)
        paymentFlow:
          type: string
          description: 'Payment flow: hosted_checkout (redirect) or payment_sheet (native)'
          enum:
            - hosted_checkout
            - payment_sheet
      required:
        - items
        - date
        - time
    CreateBookingResponseDto:
      type: object
      properties:
        mode:
          type: string
          description: Result mode
          enum:
            - approval_required
            - instant_booking
          example: instant_booking
        bookingId:
          type: string
          description: >-
            Booking ID (when mode is approval_required or instant_booking with
            payment sheet)
          example: 550e8400-e29b-41d4-a716-446655440000
        message:
          type: string
          description: Message for user when approval is required
          example: Your request has been sent to the host.
        checkoutUrl:
          type: string
          description: >-
            Stripe Checkout URL (when mode is instant_booking and payment flow
            is hosted_checkout)
          example: https://checkout.stripe.com/c/pay/cs_...
        paymentIntentClientSecret:
          type: string
          description: >-
            Stripe PaymentIntent client secret (when mode is instant_booking and
            payment flow is payment_sheet)
          example: pi_xxx_secret_xxx
        publishableKey:
          type: string
          description: >-
            Stripe publishable key (when mode is instant_booking and payment
            flow is payment_sheet)
          example: pk_test_...
      required:
        - mode
    ApiErrorResponseDto:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Validation failed
        code:
          type: string
          description: Machine-readable error code
          example: BAD_REQUEST
        details:
          type: object
          description: Additional validation or context details
          example:
            - date must be a valid ISO 8601 date
      required:
        - message
    CreateBookingItemDto:
      type: object
      properties:
        listingId:
          type: string
          description: Listing ID
          example: '10000001'
        type:
          type: string
          description: Item type
          enum:
            - venue
            - service
        price:
          type: object
          description: Price in dollars (or string from JSON)
          example: 200
        guestCount:
          type: object
          description: Guest count
          example: 10
        selectedPackages:
          description: Packages selected for this item (e.g., Premium tier)
          type: array
          items:
            $ref: '#/components/schemas/SelectedPackageDto'
      required:
        - listingId
        - type
        - price
    SelectedPackageDto:
      type: object
      properties:
        packageId:
          type: string
          description: Package identifier
          example: pkg-premium
        packageName:
          type: string
          description: Display name of the package
          example: Premium tier
        price:
          type: number
          description: Price in dollars
          example: 150
      required:
        - packageId
        - packageName
        - price
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````