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

# Create Booking

> Creates a booking for an activity variation. Returns a booking with status `Booking Attempt`.
Proceed to `/create-payment` to confirm and pay.




## OpenAPI

````yaml POST /users/add-booking
openapi: 3.0.3
info:
  title: Seyaha Affiliate API
  description: >
    API for affiliates who list and book Seyaha activities on behalf of their
    users.

    All endpoints require a JWT bearer token issued by Seyaha in the
    `Authorization` header.
  version: 1.0.0
servers:
  - url: /api/v1/affiliates
    description: Affiliate API base URL
security:
  - bearerAuth: []
tags:
  - name: Activities
    description: Browse the activity catalog
  - name: Bookings
    description: Create and manage bookings
  - name: Payments
    description: Process payments for bookings
paths:
  /users/add-booking:
    post:
      tags:
        - Bookings
      summary: Create booking
      description: >
        Creates a booking for an activity variation. Returns a booking with
        status `Booking Attempt`.

        Proceed to `/create-payment` to confirm and pay.
      operationId: createBooking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookingRequest'
            example:
              activity_id: 6744810075becd2ef8c140f7
              variation_id: 6751ad2d7533f379c9a1711b
              customer_details:
                name: Jane Smith
                email: jane@example.com
                phone: '+966501234567'
              booking_details:
                booking_date: '2026-07-15'
                booking_time: '10:00'
                currency: SAR
                guests:
                  adult: 2
                  child: 1
                  infant: 0
                  senior: 0
                pickup_address:
                  address: Riyadh Marriott Hotel
                  lat: 24.6877
                  lng: 46.7219
      responses:
        '200':
          description: Booking created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateBookingRequest:
      type: object
      required:
        - activity_id
        - variation_id
        - customer_details
        - booking_details
      properties:
        activity_id:
          type: string
          example: 6744810075becd2ef8c140f7
        variation_id:
          type: string
          example: 6751ad2d7533f379c9a1711b
        promoCode:
          type: string
          nullable: true
          example: SUMMER20
        customer_details:
          type: object
          required:
            - name
            - email
            - phone
          properties:
            name:
              type: string
              example: Jane Smith
            email:
              type: string
              format: email
              example: jane@example.com
            phone:
              type: string
              example: '+966501234567'
        booking_details:
          type: object
          required:
            - booking_date
            - booking_time
            - currency
            - guests
          properties:
            booking_date:
              type: string
              format: date
              example: '2026-07-15'
            booking_time:
              type: string
              example: '10:00'
            currency:
              type: string
              example: SAR
            guests:
              type: object
              properties:
                adult:
                  type: integer
                  example: 2
                child:
                  type: integer
                  example: 1
                infant:
                  type: integer
                  example: 0
                senior:
                  type: integer
                  example: 0
            pickup_address:
              type: object
              nullable: true
              properties:
                address:
                  type: string
                lat:
                  type: number
                lng:
                  type: number
    BookingResponse:
      type: object
      properties:
        success:
          type: integer
          example: 1
        data:
          $ref: '#/components/schemas/Booking'
    Booking:
      type: object
      properties:
        _id:
          type: string
          example: 67c896a6639e6ff76dd2f882
        user_id:
          type: string
        activity_id:
          type: string
        variation_id:
          type: string
        status:
          type: string
          enum:
            - Booking Attempt
            - Paid by Customer
            - Cancelled
          example: Booking Attempt
        partnerConfirmation:
          type: string
          enum:
            - Pending
            - Confirmed
            - Rejected
            - Not Required
          example: Not Required
        price:
          type: object
          properties:
            individuals:
              type: object
              properties:
                adults:
                  type: object
                  properties:
                    number:
                      type: integer
                    price:
                      type: number
                children:
                  type: object
                  properties:
                    number:
                      type: integer
                    price:
                      type: number
            discountPercentage:
              type: number
            deservedAmount:
              type: number
            affiliateDeservedAmount:
              type: number
            value:
              type: number
              example: 500
        bookingDate:
          type: string
          example: '2026-07-15'
        bookingTime:
          type: string
          example: '10:00'
        configurations:
          type: object
          properties:
            serviceFee:
              type: number
            taxes:
              type: number
            currency:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        success:
          type: integer
          enum:
            - 0
          example: 0
        error:
          type: array
          items:
            type: string
          example:
            - error detail
        message:
          type: string
          example: Error description
        code:
          type: integer
          example: 400
  responses:
    ValidationError:
      description: Request body failed validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: 0
            error:
              - 'booking_date: Required'
            message: Validation Error
            code: 400
    Unauthorized:
      description: Missing or invalid JWT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: 0
            error:
              - unauthorized access
            message: unauthorized access
            code: 401
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: 0
            error:
              - rate limit exceeded
            message: rate limit exceeded
            code: 429
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT issued by Seyaha — include as `Authorization: Bearer <token>`'

````