openapi: 3.0.0
info:
  version: 0.0.1
  title: Channels Plus Channel API
  description: >
    The Channels Plus Channel API enables partners to search for properties, view room availability and pricing,
    create and manage reservations with support for deals, commissions, and virtual credit cards.


    **Key Features:**

    - Geospatial property search for location-based queries

    - Support for deal codes

    - Multi-room booking with flexible guest allocation

    - Commission models including net invoicing

    - Multi-language content support


    **Authentication:**

    All endpoints require authentication using `x-sm-api-id` and `x-sm-api-key` headers.


    **Rate Limiting:**

    Requests are rate-limited per channel. Rate limit information is provided in response headers.

paths:
  /properties:
    get:
      operationId: listProperties
      description: >-
        Search for properties within a specified radius of a location, with optional filters for amenities,
        star ratings, property type, and deals etc.


        **Key Features:**

        - Location-based search using latitude, longitude, and radius

        - Support for deal codes and deal-only filtering

        - Guest group allocation to match rooms with occupancy requirements

        - Optional filters for breakfast, free cancellation, swimming pool, and more

        - Sorting by distance or property name

        - Multi-language content support


        **Response:**

        Returns an array of properties with their best available rates. Each property includes one or more room options
        with pricing. If deal codes are specified, the best available deal room rate for each supported
        deal code will also be provided. Properties without available inventory for the specified dates will be excluded.


        **Note:**

        Results are paginated. Properties are sorted by distance (nearest first) by default.
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: page
          description: The page number of the results to fetch
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          description: >-
            The number of results per page. Must be a multiple of 10 (10, 20, 30, etc.).
            Use smaller values for faster response times, larger values to reduce API calls.
            Default: 20, Maximum: 100.
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 20
            multipleOf: 10
        - name: latitude
          description: >-
            Latitude coordinate for the center of the search area.
            Used with longitude and radius to define a geospatial search circle.
            Valid range: -90 to 90 degrees.
          required: true
          in: query
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: longitude
          description: >-
            Longitude coordinate for the center of the search area.
            Used with latitude and radius to define a geospatial search circle.
            Valid range: -180 to 180 degrees.
          required: true
          in: query
          schema:
            type: number
            minimum: -180
            maximum: 180
        - name: radius
          description: >-
            The search radius in kilometers around the specified latitude and longitude.
            Properties within this distance from the center point will be included in results.
            Results are sorted by distance (nearest first) by default.
            Minimum: 15km, Maximum: 100km, Default: 15km.
          in: query
          schema:
            type: number
            default: 15
            minimum: 15
            maximum: 100
        - name: checkin
          description: The arrival date. Must be within 500 days in the future and in the format yyyy-mm-dd.
          required: true
          in: query
          schema:
            type: string
            format: date
        - name: checkout
          description: The departure date. Must be later than checkin. Must be between 1 and 30 days after checkin. Must be within 500 days in the future and in the format yyyy-mm-dd.
          required: true
          in: query
          schema:
            type: string
            format: date
        - name: rooms
          description: >-
            Specify exact occupancy for each room to get the pricing and availability.
            Provide an array of room objects with specific adult and child counts for each room.


            **Important Notes:**

            - Use this parameter for precise room allocation (e.g., Room 1: 2 adults + 1 child, Room 2: 2 adults)

            - **Mutually exclusive** with totalAdults/totalChildren/totalRooms parameters

            - Minimum 1 room, maximum 10 rooms


            **Example:** `[{"adults": 2, "children": 1}, {"adults": 2, "children": 0}]` for 2 rooms with different occupancies
          in: query
          schema:
            type: array
            minItems: 1
            maxItems: 10
            items:
              type: object
              additionalProperties: false
              properties:
                adults:
                  type: integer
                  minimum: 0
                  maximum: 65535
                  description: Number of adults in this specific room
                children:
                  type: integer
                  minimum: 0
                  maximum: 65535
                  description: Number of children in this specific room
              required:
                - adults
                - children
        - name: totalAdults
          description: >-
            Specify total adults across all rooms when exact per-room allocation is not needed.
            Must be used together with `totalRooms`. The system will distribute guests across rooms.


            **Use Case:** When you know the total guest count but not the specific room allocation.


            **Example:** `totalAdults=4, totalChildren=2, totalRooms=2` could match any room configuration
            that accommodates 4 adults and 2 children across 2 rooms.


            **Mutually exclusive** with the `rooms` parameter.
          in: query
          schema:
            type: integer
            minimum: 0
        - name: totalChildren
          description: >-
            Total number of children across all rooms. Must be used with `totalRooms`.
            **Mutually exclusive** with the `rooms` parameter.
          in: query
          schema:
            type: integer
            minimum: 0
        - name: totalRooms
          description: >-
            Total number of rooms needed. Must be used with `totalAdults` and/or `totalChildren`.
            The system will find room configurations that can accommodate the total guest count.
            **Mutually exclusive** with the `rooms` parameter.
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10
        - name: sortBy
          description: Specify the sorting criteria for the results.
          in: query
          schema:
            type: string
            enum:
              - distance
              - name
            default: distance
        - name: sortDirection
          description: Specify the sorting direction for the results.
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: minStarRating
          description: Minimum star rating for properties in the results.
          in: query
          schema:
            type: number
            enum:
              - 1
              - 1.5
              - 2
              - 2.5
              - 3
              - 3.5
              - 4
              - 4.5
              - 5
              - 5.5
              - 6
        - name: maxStarRating
          description: Maximum star rating for properties in the results.
          in: query
          schema:
            type: number
            enum:
              - 1
              - 1.5
              - 2
              - 2.5
              - 3
              - 3.5
              - 4
              - 4.5
              - 5
              - 5.5
              - 6
        - name: propertyType
          description: >-
            Filter results to only include properties of a specific type.
            Common property types include: Hotel, Resort, Apartment, Guest House, Hostel, Motel, Villa, Bed & Breakfast, etc.
            This field is case-sensitive and must match the exact property type string configured in the system.
          in: query
          schema:
            type: string
            maxLength: 255
        - name: swimmingPoolAvailable
          description: Only return rates for properties that have a swimming pool.
          in: query
          schema:
            type: boolean
        - name: breakfastIncluded
          description: Only return rates with breakfast included.
          in: query
          schema:
            type: boolean
        - name: freeCancellation
          description: Only return rates with free cancellation periods.
          in: query
          schema:
            type: boolean
        - name: dealCodes
          description: >-
            Return deal rates for properties participating in the specified deals.
            Provide one or more deal codes to include deal-specific pricing in the response.
            The API will validate that deals are active and applicable for the requested stay period.


            **Important Notes:**

            - When deal codes are provided, the response includes both standard rates and deal rates for each property

            - Each property may support different deal codes

            - Deal rates appear in the `prices` array within each room, with the `dealCode` field populated

            - Standard (non-deal) rates will have `dealCode` as null
          in: query
          schema:
            type: array
            items:
              type: string
        - name: dealOnly
          description: >-
            When set to true, only return properties that have active rates for the specified deal codes.
            Properties without the deal or without available deal inventory will be excluded from results.
            This parameter requires dealCodes to be specified.

          in: query
          schema:
            type: boolean
        - name: language
          description: >-
            Specify the preferred language for returned content (property descriptions, room types, amenities).
            Falls back to the property's default language if the requested language is not available.
            Supported: de (German), en (English), es (Spanish), fr (French), id (Indonesian), it (Italian), pt (Portuguese), th (Thai).
          in: query
          schema:
            type: string
            enum:
              - de
              - en
              - es
              - fr
              - id
              - it
              - pt
              - th
        - name: excludeSelfRated
          in: query
          description: >-
            Exclude self-rated properties from the response.
            Self-rated properties have star ratings assigned by the property owner rather than an official rating authority.
            Set to `true` to only include officially rated properties.
          schema:
            type: boolean

      responses:
        "200":
          description: successful
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: uuid of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: uuid used for tracing, useful to provide to SiteMinder when raising issues.
            ratelimit-policy:
              schema:
                type: string
              description: Shows the number of request allowed per number of seconds window. e.g. '100;w=60' means 100 request in a 60 seconds window.
            ratelimit-limit:
              schema:
                type: integer
              description: The number of requests allowed per window
            ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            ratelimit-reset:
              schema:
                type: integer
              description: The number of seconds left for the window to reset
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    uuid:
                      type: string
                      description: Unique identifier for the property.
                    name:
                      type: string
                      description: The name of the property.
                    propertyType:
                      $ref: '#/components/schemas/TranslationText'
                      description: The type of the property with language information.
                    description:
                      $ref: '#/components/schemas/TranslationText'
                      description: A description of the property with language information.
                    address:
                      type: string
                      description: The address of the property.
                    suburb:
                      type: string
                      description: The suburb where the property is located.
                    state:
                      type: string
                      description: The state or region where the property is located.
                    country:
                      type: string
                      description: The country where the property is located.
                    email:
                      type: string
                      description: The contact email for the property.
                    phoneNumber:
                      type: string
                      description: The contact phone number for the property.
                    language:
                      type: string
                      maxLength: 16
                      description: The primary language used by the property.
                    latitude:
                      type: number
                      description: The latitude coordinate of the property.
                    longitude:
                      type: number
                      description: The longitude coordinate of the property.
                    checkinStartTime:
                      type: string
                      minLength: 1
                      maxLength: 10
                      description: The earliest time guests can check in.
                    checkinEndTime:
                      type: string
                      minLength: 1
                      maxLength: 10
                      description: The latest time guests can check in.
                    checkoutEndTime:
                      type: string
                      minLength: 1
                      maxLength: 10
                      description: The latest time guests must check out.
                    starRating:
                      $ref: '#/components/schemas/StarRatings'
                      description: The star rating of the property.
                    currency:
                      type: string
                      description: The currency of the price
                    photo:
                      $ref: '#/components/schemas/Photo'
                      description: A photo representing the property.
                    amenities:
                      type: array
                      description: Amenities that are available at this property
                      items:
                        $ref: '#/components/schemas/TranslationText'
                    acceptedCardTypes:
                      type: array
                      description: >-
                        Credit card types accepted for payment at this property.
                        Card type codes: AX (American Express), DN (Diners), DS (Discover),
                        JC (JCB), MC (Mastercard), CU (China UnionPay), VI (Visa).
                        When confirming a reservation, the card type provided must be in this list.
                      items:
                        type: string
                        enum:
                          - AX
                          - DN
                          - DS
                          - JC
                          - MC
                          - CU
                          - VI
                      minItems: 1
                    totalCommissionPercentage:
                      type: number
                      description: >-
                        The total commission percentage for bookings at this property.
                        This represents the combined commission split between SiteMinder and the channel partner.
                        Formula: `totalCommissionPercentage = siteminderCommissionPercentage + channelCommissionPercentage`
                    siteminderCommissionPercentage:
                      type: number
                      description: >-
                        SiteMinder's portion of the total commission percentage.
                    channelCommissionPercentage:
                      type: number
                      description: >-
                        The channel partner's portion of the total commission percentage.
                    rooms:
                      type: array
                      description: Available rooms and their details.
                      items:
                        type: object
                        additionalProperties: false
                        properties:
                          roomRateUuid:
                            type: string
                            description: Unique identifier for this room rate.
                          roomTypeName:
                            $ref: '#/components/schemas/TranslationText'
                            description: The name of the room type with language information.
                          roomTypeDescription:
                            $ref: '#/components/schemas/TranslationText'
                            description: A description of the room type with language information.
                          ratePlanName:
                            type: string
                            description: >-
                              The name of the rate plan for this room.
                              For Internal use only, not to be displayed to guests.
                          breakfastIncluded:
                            type: boolean
                            description: Indicates whether breakfast is included in the rate.
                          roomArea:
                            type: string
                            description: room area from room type with the unit of measurement
                            nullable: true
                          photo:
                            $ref: '#/components/schemas/Photo'
                            description: A photo of the room.
                          amenities:
                            type: array
                            description: Amenities that are available at this property
                            items:
                              $ref: '#/components/schemas/TranslationText'
                          views:
                            type: array
                            description: >-
                              Views available from this room type (e.g., ocean view, city view, garden view, mountain view).
                              Multiple views may be listed if the room type offers different view options.
                              Each view is provided with language-specific translations.
                            items:
                              $ref: '#/components/schemas/TranslationText'
                          bedConfigurations:
                            type: array
                            description: >-
                              Available bed configurations for this room type.
                              Common bed types include: King, Queen, Double, Twin, Single, Sofa Bed, Bunk Bed.
                              A room may have multiple bed types (e.g., 1 King + 1 Sofa Bed).
                              Each bed type is provided with language-specific translations.
                            items:
                              type: object
                              additionalProperties: false
                              properties:
                                bedCode:
                                  $ref: '#/components/schemas/TranslationText'
                                  description: The type of bed (e.g., "King", "Queen", "Twin") with language information.
                                quantity:
                                  type: number
                                  minimum: 1
                                  description: The number of beds of this type in the room (e.g., 2 for "2 Twin beds").
                          adults:
                            type: integer
                            description: The number of adults this rate is for.
                          children:
                            type: integer
                            description: The number of children this rate is for.
                          cancellationPolicy:
                            $ref: '#/components/schemas/CancelationPolicy'
                            description: The cancellation policy for this room rate.
                          prices:
                            type: array
                            description: The pricing options for this room, including any applicable deals.
                            items:
                              type: object
                              additionalProperties: false
                              properties:
                                totalPrice:
                                  type: number
                                  minimum: 0
                                  description: The total price for the stay.
                                dealCode:
                                  type: string
                                  description: The code of any deal applied to this price.
                                totalCommissionPercentage:
                                  type: number
                                  description: The total commission percentage for this specific rate.
                                siteminderCommissionPercentage:
                                  type: number
                                  description: SiteMinder's portion of the commission for this rate.
                                channelCommissionPercentage:
                                  type: number
                                  description: The channel partner's portion of the commission for this rate.
                              required:
                                - totalPrice
                                - totalCommissionPercentage
                                - siteminderCommissionPercentage
                                - channelCommissionPercentage
                          rateType:
                            type: string
                            enum:
                              - sell
                              - net
                            description: Indicates whether this is a sell rate or net rate.
                          lowInventory:
                            type: boolean
                            description: >-
                              Indicates whether this room type has low inventory available.
                              When `true`, only a few rooms remain for the specified dates, signaling scarcity to encourage booking.
                              Use this flag to display urgency messaging (e.g., "Only 2 rooms left!") to guests.
                        required:
                          - roomRateUuid
                          - roomTypeName
                          - ratePlanName
                          - breakfastIncluded
                          - adults
                          - children
                          - cancellationPolicy
                          - rateType
                          - prices
                          - lowInventory
                    specialConditions:
                      $ref: '#/components/schemas/SpecialConditions'
                      description: Special conditions that apply to this property.
                    selfRated:
                      type: boolean
                      description: Indicates if the rating is self-rated
                  required:
                    - uuid
                    - name
                    - address
                    - state
                    - country
                    - phoneNumber
                    - language
                    - latitude
                    - longitude
                    - currency
                    - checkinStartTime
                    - checkoutEndTime
                    - acceptedCardTypes
                    - totalCommissionPercentage
                    - siteminderCommissionPercentage
                    - channelCommissionPercentage
                    - rooms
                    - specialConditions
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"

  /properties/{uuid}:
    get:
      operationId: showProperty
      description: >-
        Get detailed information and room rates for a specific property that satisfies the given search criteria.
        This endpoint provides more comprehensive data about a single property, including its room types and available rates.
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: uuid
          description: The unique identifier of the property
          required: true
          in: path
          schema:
            type: string
        - name: checkin
          description: The arrival date. Must be within 500 days in the future and in the format yyyy-mm-dd.
          required: true
          in: query
          schema:
            type: string
            format: date
        - name: checkout
          description: The departure date. Must be later than checkin. Must be between 1 and 30 days after checkin. Must be within 500 days in the future and in the format yyyy-mm-dd.
          required: true
          in: query
          schema:
            type: string
            format: date
        - name: rooms
          description: >-
            Use the rooms list to specify exact occupants in each room. Provides more accurate pricing.
            Do not use this if searching by totalAdults, totalChildren & totalRooms.
          in: query
          schema:
            type: array
            minItems: 1
            maxItems: 10
            items:
              type: object
              additionalProperties: false
              properties:
                adults:
                  type: integer
                  minimum: 0
                  maximum: 65535
                  description: Number of adults in the room
                children:
                  type: integer
                  minimum: 0
                  maximum: 65535
                  description: Number of children in the room
              required:
                - adults
                - children
        - name: totalAdults
          description: >-
            Specify the total number of adults across all rooms. Must also specify totalRooms field.
            Do not use this if searching with the occupants rooms list.
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 655350
        - name: totalChildren
          description: >-
            Specify the total number of children across all rooms. Must also specify totalRooms field.
            Do not use this if searching with the occupants rooms list.
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 655350
        - name: totalRooms
          description: >-
            Specify the total number of rooms. Must also specify totalAdults and/or totalChildren fields.
            Do not use this if searching with the occupants rooms list.
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10
        - name: dealCode
          description: Only return rates associated with the given deal code
          in: query
          schema:
            type: string
        - name: language
          description: Specify the preferred language for returned content. Falls back to the property's default language if unavailable.
          in: query
          schema:
            type: string
            enum:
              - de
              - en
              - es
              - fr
              - id
              - it
              - pt
              - th

      responses:
        "200":
          description: Successful response
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
            ratelimit-policy:
              schema:
                type: string
              description: Shows the number of requests allowed per number of seconds window. e.g. '100;w=60' means 100 requests in a 60 seconds window.
            ratelimit-limit:
              schema:
                type: integer
              description: The number of requests allowed per window
            ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            ratelimit-reset:
              schema:
                type: integer
              description: The number of seconds left for the window to reset
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  uuid:
                    type: string
                    description: Unique identifier of the property
                  name:
                    type: string
                    description: Name of the property
                  propertyType:
                    $ref: '#/components/schemas/TranslationText'
                    description: Type of the property with language information
                  description:
                    $ref: '#/components/schemas/TranslationText'
                    description: Detailed description of the property with language information
                  address:
                    type: string
                    description: Street address of the property
                  suburb:
                    type: string
                    description: Suburb where the property is located
                  state:
                    type: string
                    description: State or region where the property is located
                  country:
                    type: string
                    description: Country where the property is located
                  email:
                    type: string
                    description: Contact email address for the property
                  phoneNumber:
                    type: string
                    description: Contact phone number for the property
                  language:
                    type: string
                    maxLength: 16
                    description: Primary language used by the property
                  latitude:
                    type: number
                    description: Latitude coordinate of the property's location
                  longitude:
                    type: number
                    description: Longitude coordinate of the property's location
                  checkinStartTime:
                    type: string
                    minLength: 1
                    maxLength: 10
                    description: Earliest time guests can check in
                  checkinEndTime:
                    type: string
                    minLength: 1
                    maxLength: 10
                    description: Latest time guests can check in
                  checkoutEndTime:
                    type: string
                    minLength: 1
                    maxLength: 10
                    description: Latest time guests must check out
                  starRating:
                    $ref: '#/components/schemas/StarRatings'
                    description: Star rating of the property
                  currency:
                    type: string
                    description: Currency used for pricing at this property
                  photos:
                    type: array
                    description: Array of photos representing the property
                    items:
                      $ref: '#/components/schemas/Photo'
                  amenities:
                    type: array
                    description: Amenities available at this property
                    items:
                      $ref: '#/components/schemas/TranslationText'
                  acceptedCardTypes:
                    type: array
                    description: Credit card types accepted at this property
                    items:
                      type: string
                      enum:
                        - AX
                        - DN
                        - DS
                        - JC
                        - MC
                        - CU
                        - VI
                    minItems: 1
                  totalCommissionPercentage:
                    type: number
                    description: Total commission percentage for bookings at this property
                  siteminderCommissionPercentage:
                    type: number
                    description: SiteMinder's portion of the commission percentage
                  channelCommissionPercentage:
                    type: number
                    description: Channel partner's portion of the commission percentage
                  roomTypes:
                    type: array
                    description: Array of room types available at this property
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        uuid:
                          type: string
                          description: Unique identifier for this room type
                        name:
                          $ref: '#/components/schemas/TranslationText'
                          description: Name of the room type with language information
                        description:
                          $ref: '#/components/schemas/TranslationText'
                          description: Detailed description of the room type with language information
                        roomArea:
                          type: string
                          description: Size of the room, including the unit of measurement
                          nullable: true
                        photos:
                          type: array
                          description: Array of photos representing the room type
                          items:
                            $ref: '#/components/schemas/Photo'
                        amenities:
                          type: array
                          description: Amenities available in this room type
                          items:
                            $ref: '#/components/schemas/TranslationText'
                        views:
                          type: array
                          description: Views available from this room type
                          items:
                            $ref: '#/components/schemas/TranslationText'
                        bedConfigurations:
                          type: array
                          description: Possible bed configurations for this room type
                          items:
                            type: object
                            additionalProperties: false
                            properties:
                              bedCode:
                                $ref: '#/components/schemas/TranslationText'
                                description: Type of bed (e.g., "King", "Twin") with language information
                              quantity:
                                type: number
                                minimum: 1
                                description: Number of beds of this type in the room
                        roomRates:
                          type: array
                          description: Available rates for this room type
                          items:
                            type: object
                            additionalProperties: false
                            properties:
                              uuid:
                                type: string
                                description: Unique identifier for this room rate
                              ratePlanUuid:
                                type: string
                                description: Unique identifier for the rate plan
                              ratePlanName:
                                type: string
                                description: >-
                                  Name of the rate plan.
                                  For Internal use only, not to be displayed to guests.
                              breakfastIncluded:
                                type: boolean
                                description: Indicates if breakfast is included in the rate
                              totalPrice:
                                type: number
                                description: Total price for the stay in this room
                                minimum: 0
                              taxes:
                                type: array
                                description: Breakdown of taxes applicable to this rate
                                items:
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    name:
                                      type: string
                                      description: Name of the tax
                                    amount:
                                      type: number
                                      description: Amount of the tax
                                  required:
                                    - name
                                    - amount
                              fees:
                                type: array
                                description: Breakdown of fees applicable to this rate
                                items:
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    name:
                                      type: string
                                      description: Name of the fee
                                    amount:
                                      type: number
                                      description: Amount of the fee
                                  required:
                                    - name
                                    - amount
                              adults:
                                type: integer
                                description: Number of adults this rate is for
                              children:
                                type: integer
                                description: Number of children this rate is for
                              cancellationPolicy:
                                $ref: '#/components/schemas/CancelationPolicy'
                                description: Cancellation policy for this rate
                              dealCode:
                                type: string
                                description: Code of any deal applied to this rate
                              totalCommissionPercentage:
                                type: number
                                description: Total commission percentage for this specific rate
                              siteminderCommissionPercentage:
                                type: number
                                description: SiteMinder's portion of the commission for this rate
                              channelCommissionPercentage:
                                type: number
                                description: Channel partner's portion of the commission for this rate
                              rateType:
                                type: string
                                enum:
                                  - sell
                                  - net
                                description: Indicates whether this is a sell rate or net rate.
                              lowInventory:
                                type: boolean
                                description: Indicates if this room type has low inventory available
                            required:
                              - uuid
                              - ratePlanUuid
                              - ratePlanName
                              - breakfastIncluded
                              - totalPrice
                              - taxes
                              - fees
                              - adults
                              - children
                              - cancellationPolicy
                              - totalCommissionPercentage
                              - siteminderCommissionPercentage
                              - channelCommissionPercentage
                              - rateType
                              - lowInventory
                      required:
                        - uuid
                        - name
                  specialConditions:
                    $ref: '#/components/schemas/SpecialConditions'
                    description: Special conditions that apply to this property.
                required:
                  - uuid
                  - name
                  - address
                  - state
                  - country
                  - phoneNumber
                  - language
                  - latitude
                  - longitude
                  - checkinStartTime
                  - checkoutEndTime
                  - acceptedCardTypes
                  - totalCommissionPercentage
                  - siteminderCommissionPercentage
                  - channelCommissionPercentage
                  - currency
                  - roomTypes
                  - specialConditions

        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"

  /properties/{uuid}/reservations:
    post:
      operationId: createPendingReservation
      description: >-
        Create a pending reservation to lock in rates and availabilities for a specific property.
        This endpoint allows you to temporarily hold a reservation before confirming it,
        ensuring the rates and room availability are secured for a short period.


        **Pending Reservation Workflow:**

        1. Call this endpoint to create a pending reservation

        2. The response includes a `bookingReferenceId` and `expiresInMinutes`

        3. Complete payment collection from the guest

        4. Call `/reservations/{bookingReferenceId}/confirmation` before expiration

        5. If not confirmed within the expiration window, the reservation is automatically released


        **Room Allocation Rules:**

        - Maximum 10 rooms per reservation

        - Each room must specify `roomRateUuid`, `adults`, and `children` count

        - The `roomRateUuid` must correspond to a valid rate returned from property search endpoints

        - Occupancy (`adults` + `children`) should not exceed the room type's maximum capacity

        - Use `applyDeal` per room to selectively apply deal rates when a `dealCode` is specified


        **Deal Application:**

        - Set `dealCode` at the reservation level to apply a deal

        - Use `applyDeal: true` for specific rooms to apply the deal rate to those rooms

        - Rooms with `applyDeal: false` or `null` will use standard rates even if a deal code is specified

        - This allows mixed bookings with both deal and non-deal rooms
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: uuid
          description: The unique identifier of the property for which the reservation is being made
          required: true
          in: path
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                checkin:
                  type: string
                  format: date
                  description: The arrival date. Must be within 500 days in the future and in the format yyyy-mm-dd.
                checkout:
                  type: string
                  format: date
                  description: The departure date. Must be later than checkin. Must be between 1 and 30 days after checkin. Must be within 500 days in the future and in the format yyyy-mm-dd.
                dealCode:
                  type: string
                  nullable: true
                  description: The code of any deal to be applied to the reservation. If null, no deal will be applied.
                netInvoicing:
                  type: boolean
                  default: false
                  description: >-
                    Indicates whether net invoicing should be applied to the reservation.
                    When set to true, the commission is deducted from the booking amount, and the property
                    receives the net amount (total minus commission).
                rooms:
                  type: array
                  description: An array of room bookings for this reservation. Minimum 1, maximum 10 rooms.
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      roomRateUuid:
                        type: string
                        maxLength: 36
                        description: The unique identifier for the specific room rate being booked.
                      adults:
                        type: integer
                        minimum: 0
                        maximum: 255
                        description: The number of adults for this room booking.
                      children:
                        type: integer
                        minimum: 0
                        maximum: 255
                        description: The number of children for this room booking.
                      applyDeal:
                        type: boolean
                        nullable: true
                        description: Indicates whether to apply the deal (if any) to this specific room booking.
                    required:
                      - roomRateUuid
                      - adults
                      - children
                  minItems: 1
                  maxItems: 10

              required:
                - checkin
                - checkout
                - rooms
      responses:
        "200":
          description: Successful response. A pending reservation has been created.
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  propertyUuid:
                    type: string
                    description: The unique identifier of the property for which the reservation is made.
                  propertyEmail:
                    type: string
                    description: The contact email address for the property.
                  propertyPhoneNumber:
                    type: string
                    description: The contact phone number for the property.
                  bookingReferenceId:
                    type: string
                    description: The unique identifier for this pending reservation.
                  expiresInMinutes:
                    type: number
                    description: The number of minutes before the pending reservation expires and is no longer valid.
                    minimum: 0
                  currencyCode:
                    type: string
                    description: The currency code for all monetary values in this response.
                  paymentTotal:
                    type: number
                    description: The total payment amount for the reservation, including all taxes and fees.
                  paymentTotalLessCommission:
                    type: number
                    description: The total payment amount minus the commission.
                  taxes:
                    type: array
                    description: An array of taxes applicable to this reservation.
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          description: The name or type of the tax.
                        amount:
                          type: number
                          description: The amount of the tax.
                      required:
                        - name
                        - amount
                  fees:
                    type: array
                    description: An array of fees applicable to this reservation.
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          description: The name or type of the fee.
                        amount:
                          type: number
                          description: The amount of the fee.
                      required:
                        - name
                        - amount
                  rooms:
                    type: array
                    description: An array of rooms included in this reservation.
                    items:
                      additionalProperties: false
                      properties:
                        roomUuid:
                          type: string
                          description: The unique identifier for this specific room.
                        roomTypeName:
                          type: string
                          description: The name of the room type.
                        roomRateUuid:
                          type: string
                          minLength: 1
                          maxLength: 36
                          description: The unique identifier for the rate plan applied to this room.
                        adults:
                          type: integer
                          minimum: 0
                          description: The number of adults for this room.
                        children:
                          type: integer
                          minimum: 0
                          description: The number of children for this room.
                        paymentTotal:
                          type: number
                          description: The total payment amount for this room.
                        totalCommissionPercentage:
                          type: number
                          description: The total commission percentage for this room booking.
                        siteminderCommissionPercentage:
                          type: number
                          description: SiteMinder's portion of the commission percentage for this room booking.
                        channelCommissionPercentage:
                          type: number
                          description: The channel partner's portion of the commission percentage for this room booking.
                      required:
                        - roomUuid
                        - roomTypeName
                        - roomRateUuid
                        - adults
                        - children
                        - paymentTotal
                        - totalCommissionPercentage
                        - siteminderCommissionPercentage
                        - channelCommissionPercentage
                    minItems: 1
                    maxItems: 10
                  licenses:
                    type: array
                    description: >-
                      An array of business licenses and permits applicable to this property or specific rooms.
                      These may include hotel operating licenses, business registration numbers, or regulatory permits
                      required in certain jurisdictions (e.g., Japan's inn operation licenses, Singapore hotel licenses).
                      Display these to guests where legally required.
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        licenseType:
                          type: string
                          enum:
                            - property
                            - room
                          description: >-
                            Indicates whether the license applies to the entire property or to a specific room.
                        licenseNumber:
                          type: string
                          description: The official license or permit number issued by the regulatory authority.
                        licenseIssueDate:
                          type: string
                          description: The date when the license was issued, in YYYY-MM-DD format.
                      required:
                        - licenseType
                        - licenseNumber
                        - licenseIssueDate
                  cancellationPolicy:
                    $ref: '#/components/schemas/CancelationPolicy'
                    description: The cancellation policy applicable to this reservation.
                required:
                  - propertyUuid
                  - propertyPhoneNumber
                  - bookingReferenceId
                  - expiresInMinutes
                  - currencyCode
                  - paymentTotal
                  - paymentTotalLessCommission
                  - rooms
                  - cancellationPolicy
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /reservations:
    get:
      operationId: listReservations
      description: >-
        Retrieve a list of reservations filtered by date type and a date range via fromDate & toDate. Max duration is 31 days.
        Only confirmed and cancelled reservations are returned.
      parameters:
      - $ref: "#/components/parameters/SmApiId"
      - $ref: "#/components/parameters/SmApiKey"
      - name: dateType
        in: query
        description: >-
          The type of date to filter reservations by.
          - `checkIn`: Filter by the guest's check-in date (arrival date)
          - `checkOut`: Filter by the guest's check-out date (departure date)
          - `bookedOn`: Filter by the date the reservation was created/booked
        required: true
        schema:
          type: string
          enum:
            - checkIn
            - checkOut
            - bookedOn
      - name: fromDate
        in: query
        required: true
        schema:
          type: string
          format: date
          description: The start date of the date range (inclusive). Cannot be more than 365 days in the past.
      - name: toDate
        in: query
        required: true
        schema:
          type: string
          format: date
          description: The end date of the date range (inclusive).
      - name: page
        in: query
        description: The page number of the results to fetch.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: perPage
        in: query
        description: The number of results per page.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 100
          multipleOf: 10
      responses:
        "200":
          description: Successful response. Returns a list of reservations.
          headers:
            x-sm-request-id:
              schema:
                type: string
                description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
                description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
            link:
              schema:
                type: string
              description: |
                When a response is paginated, the response headers will include a link header. If the endpoint does not support pagination, or if all results fit on a single page, the link header will be omitted.
                The link header contains URLs that you can use to fetch additional pages of results. For example, the previous, next, first, and last page of results.
                e.g. '<http://127.0.0.1/reservations?page=1>; rel="first", <http://127.0.0.1/reservations?page=3>; rel="last", <http://127.0.0.1/reservations?page=3>; rel="next", <http://127.0.0.1/reservations?page=1>; rel="prev"'
                The URL for the previous page is followed by rel="prev".
                The URL for the next page is followed by rel="next".
                The URL for the last page is followed by rel="last".
                The URL for the first page is followed by rel="first".
          content:
            application/json:
              schema:
                type: array
                description: List of reservations.
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    bookingReferenceId:
                      type: string
                      description: Unique identifier for the booking.
                    propertyUuid:
                      type: string
                      description: The unique identifier of the property for which the reservation is made.
                    bookedOnDate:
                      type: string
                      format: date
                      description: The date the reservation was made.
                    checkInDate:
                      type: string
                      format: date
                      description: The check-in date for the reservation.
                    checkOutDate:
                      type: string
                      format: date
                      description: The check-out date for the reservation.
                    currencyCode:
                      type: string
                      description: The currency of the reservation amount.
                    paymentTotal:
                      type: number
                      description: The total reservation amount in the reservation currency.
                    status:
                      type: string
                      enum:
                      - Confirmed
                      - Cancelled
                      description: The status of the reservation.
                    channelCommissionAmount:
                      type: number
                      description: The channel commission amount in the reservation currency.
                  required:
                    - bookingReferenceId
                    - propertyUuid
                    - bookedOnDate
                    - checkInDate
                    - checkOutDate
                    - currencyCode
                    - paymentTotal
                    - status
                    - channelCommissionAmount
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /reservations/{bookingReferenceId}:
    patch:
      operationId: modifyReservation
      description: >-
        Modify an existing reservation. This endpoint allows updating guest information
        for the primary guest and individual room guests. Note that this endpoint
        can only modify non-price impacting details of the reservation.
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: bookingReferenceId
          description: The unique identifier of the reservation to be modified
          required: true
          in: path
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                guestTitle:
                  type: string
                  nullable: true
                  description: The title of the primary guest (e.g., Mr., Mrs., Ms., Dr.)
                guestFirstName:
                  type: string
                  nullable: true
                  description: The first name of the primary guest
                guestLastName:
                  type: string
                  nullable: true
                  description: The last name of the primary guest
                guestEmail:
                  type: string
                  nullable: true
                  description: The email address of the primary guest
                guestPhoneNumber:
                  type: string
                  nullable: true
                  description: The phone number of the primary guest
                guestAddress:
                  type: string
                  nullable: true
                  description: The street address of the primary guest
                guestCity:
                  type: string
                  nullable: true
                  description: The city of residence for the primary guest
                guestState:
                  type: string
                  nullable: true
                  description: The state or region of residence for the primary guest
                guestPostcode:
                  type: string
                  nullable: true
                  description: The postal or zip code of the primary guest
                guestCountry:
                  type: string
                  nullable: true
                  description: The country of residence for the primary guest
                guestRemarks:
                  type: string
                  nullable: true
                  description: Any additional remarks or special requests from the primary guest
                rooms:
                  type: array
                  description: An array of rooms in the reservation, allowing individual guest information updates
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      roomUuid:
                        type: string
                        description: The unique identifier of the room in the reservation
                      guestTitle:
                        type: string
                        nullable: true
                        description: The title of the guest for this specific room
                      guestFirstName:
                        type: string
                        nullable: true
                        description: The first name of the guest for this specific room
                      guestLastName:
                        type: string
                        nullable: true
                        description: The last name of the guest for this specific room
                      guestRemarks:
                        type: string
                        nullable: true
                        description: Any additional remarks or special requests for this specific room
                    required:
                      - roomUuid
                  maxItems: 10

      responses:
        "200":
          description: Successful response. The reservation has been modified successfully.
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

    get:
      operationId: showReservation
      description: >-
        Returns information regarding a specific reservation based on the provided booking reference ID.
        Only confirmed and cancelled reservations will return results. Reservations in pending status will return 404.
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: bookingReferenceId
          in: path
          required: true
          description: The unique identifier of the reservation. Only one booking reference ID can be passed per request.
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  bookingReferenceId:
                    type: string
                    description: Unique identifier for the booking.
                  propertyUuid:
                    type: string
                    description: The unique identifier of the property for which the reservation is made.
                  propertyName:
                    type: string
                    description: The name of the property.
                  bookedOnDate:
                    type: string
                    format: date
                    description: The date the reservation was made.
                  checkInDate:
                    type: string
                    format: date
                    description: The check-in date for the reservation.
                  checkOutDate:
                    type: string
                    format: date
                    description: The check-out date for the reservation.
                  currencyCode:
                    type: string
                    description: The booking currency of the reservation.
                  paymentTotal:
                    type: number
                    description: The total amount for the reservation, in the booking currency.
                  totalTaxes:
                    type: number
                    description: The total amount of taxes applied to the reservation, in the booking currency.
                  totalFees:
                    type: number
                    description: The total amount of fees applied to the reservation, in the booking currency.
                  status:
                    type: string
                    enum:
                    - Confirmed
                    - Cancelled
                    description: The status of the reservation.
                  channelCommissionPercentage:
                    type: number
                    description: The channel commission amount for the reservation, in the booking currency.
                  channelCommissionAmount:
                    type: number
                    description: The channel commission amount in the reservation currency.
                  siteminderCommissionAmount:
                    type: number
                    description: The SiteMinder commission amount for the reservation, in the booking currency.
                  cancellationPolicy:
                    $ref: '#/components/schemas/CancelationPolicy'
                    nullable: true
                    description: The cancellation policy applicable to this reservation.
                  nonRefundableDateTime:
                    type: string
                    format: date-time
                    nullable: true
                    description: The datetime when the reservation becomes non-refundable, in the property's timezone.
                required:
                  - bookingReferenceId
                  - propertyUuid
                  - propertyName
                  - bookedOnDate
                  - checkInDate
                  - checkOutDate
                  - currencyCode
                  - paymentTotal
                  - totalTaxes
                  - totalFees
                  - status
                  - channelCommissionPercentage
                  - channelCommissionAmount
                  - siteminderCommissionAmount
                  - cancellationPolicy
                  - nonRefundableDateTime
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"


  /reservations/{bookingReferenceId}/confirmation:
    post:
      operationId: confirmReservation
      description: >-
        Confirm a pending reservation by providing guest details and payment information.
        This endpoint finalizes the booking process, transforming a temporary hold into a confirmed reservation.


        **Payment Methods:**

        - `CreditCard`: Standard credit card payment.

        - `VirtualCreditCard` (VCC): Virtual card issued for the booking. VCC details include activation/deactivation dates, currency, and balance.

        
        **Credit Card Validation:**

        - The card type provided must match one of the property's accepted card types

        - Invalid or expired cards will result in a 400 error


        **Important Notes:**

        - Pending reservations expire after the time specified in `expiresInMinutes` from the pending reservation response

        - Attempting to confirm an expired reservation will result in a 404 error

        - Room availability is re-validated during confirmation to ensure inventory is still available

        - Guest information provided during confirmation cannot be empty for required fields
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: bookingReferenceId
          description: The unique identifier of the pending reservation to be confirmed
          required: true
          in: path
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                paymentMethod:
                  type: string
                  enum:
                    - CreditCard
                    - VirtualCreditCard
                  description: The method of payment for the reservation
                cardNumber:
                  type: integer
                  description: The full number of the credit card or virtual credit card
                cardholderName:
                  type: string
                  description: The name of the cardholder as it appears on the card
                cardExpiry:
                  type: string
                  pattern: '^\d{2}\/\d{4}$'
                  description: The expiry date of the card in MM/YYYY format
                cardType:
                  type: string
                  enum:
                    - AX
                    - DN
                    - DS
                    - JC
                    - MC
                    - CU
                    - VI
                  description: The type of credit card (AX=American Express, DN=Diners, DS=Discover, JC=JCB, MC=Mastercard, CU=China UnionPay, VI=Visa)
                cardCvv:
                  type: string
                  pattern: '^\d{3,4}$'
                  description: The Card Verification Value (CVV) of the credit card
                vccActivationDateTime:
                  type: string
                  format: date-time
                  description: >-
                    VCC activation date/time. Expressed in ISO 8601 extended format.
                    Date Format - YYYY-MM-DDThh:mm:ss<.sss>(+|-)hh:mm where <.sss> is optional and can be 1 to 3 digits.
                  example: 2020-07-04T12:09:56.450-07:00
                vccDeactivationDateTime:
                  type: string
                  format: date-time
                  description: >-
                    VCC deactivation date/time. Expressed in ISO 8601 extended format.
                    Date Format - YYYY-MM-DDThh:mm:ss<.sss>(+|-)hh:mm where <.sss> is optional and can be 1 to 3 digits.
                  example: 2020-07-04T12:09:56.450-07:00
                vccCurrency:
                  type: string
                  description: The currency of the Virtual Credit Card (if applicable)
                vccBalance:
                  type: number
                  description: The balance available on the Virtual Credit Card (if applicable)
                guestTitle:
                  type: string
                  description: The title of the primary guest (e.g., Mr., Mrs., Ms., Dr.)
                guestFirstName:
                  type: string
                  description: The first name of the primary guest
                guestLastName:
                  type: string
                  description: The last name of the primary guest
                guestEmail:
                  type: string
                  description: The email address of the primary guest
                guestPhoneNumber:
                  type: string
                  description: The phone number of the primary guest
                guestAddress:
                  type: string
                  nullable: true
                  description: The street address of the primary guest (optional)
                guestCity:
                  type: string
                  nullable: true
                  description: The city of residence for the primary guest (optional)
                guestState:
                  type: string
                  nullable: true
                  description: The state or region of residence for the primary guest (optional)
                guestPostcode:
                  type: string
                  nullable: true
                  description: The postal or zip code of the primary guest (optional)
                guestCountry:
                  type: string
                  nullable: true
                  description: The country of residence for the primary guest (optional)
                guestRemarks:
                  type: string
                  nullable: true
                  description: Any additional remarks or special requests from the primary guest (optional)
                rooms:
                  type: array
                  description: An array of rooms in the reservation, each with its guest details
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      roomUuid:
                        type: string
                        minLength: 1
                        maxLength: 36
                        description: The unique identifier of the room in the reservation
                      guestTitle:
                        type: string
                        description: The title of the guest for this specific room
                      guestFirstName:
                        type: string
                        description: The first name of the guest for this specific room
                      guestLastName:
                        type: string
                        description: The last name of the guest for this specific room
                      guestRemarks:
                        type: string
                        nullable: true
                        description: Any additional remarks or special requests for this specific room (optional)
                    required:
                      - roomUuid
                      - guestTitle
                      - guestFirstName
                      - guestLastName
                  minItems: 1
                  maxItems: 10

              required:
                - paymentMethod
                - cardNumber
                - cardholderName
                - cardExpiry
                - cardType
                - cardCvv
                - guestTitle
                - guestFirstName
                - guestLastName
                - guestPhoneNumber
                - guestEmail
                - rooms
      responses:
        "200":
          description: Successful response. The reservation has been confirmed successfully.
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

  /reservations/{bookingReferenceId}/cancellation:
    post:
      operationId: cancelReservation
      description: >-
        Cancel an existing confirmed reservation. This endpoint allows you to cancel a confirmed reservation
        that has a free cancellation policy.


        **Important Business Rules:**

        - Only reservations with `policyType: "free-cancellation"` can be cancelled via this endpoint

        - Non-refundable reservations (`policyType: "non-refundable"`) cannot be cancelled and will result in a 400 error

        - Cancellation must be requested within the free cancellation period (before `freeCancellationUntilDays` prior to check-in)

        - Attempts to cancel outside the cancellation period will result in a 400 error

        - Pending reservations (not yet confirmed) will return a 404 error

        - Already cancelled reservations will return a 404 error


        **Cancellation Policy Calculation:**

        The cancellation deadline is calculated in the property's local timezone based on the `freeCancellationUntilDays` value
        from the cancellation policy. For example, if a reservation has a check-in date of 2024-01-15 and
        `freeCancellationUntilDays: 7`, the last day to cancel is 2024-01-08 (in the property's timezone).


        **Successful Cancellation:**

        A 200 response indicates the cancellation was successful. The reservation status will be updated to "Cancelled".
      parameters:
        - $ref: "#/components/parameters/SmApiId"
        - $ref: "#/components/parameters/SmApiKey"
        - name: bookingReferenceId
          description: The unique identifier of the reservation to be cancelled
          required: true
          in: path
          schema:
            type: string
      responses:
        "200":
          description: >-
            Successful response. The reservation has been cancelled successfully.
            Note that a successful cancellation does not necessarily mean a full refund will be issued.
            Refunds are subject to the property's cancellation policy.
          headers:
            x-sm-request-id:
              schema:
                type: string
              description: UUID of the request, useful to provide to SiteMinder when raising issues.
            x-sm-trace-token:
              schema:
                type: string
              description: UUID used for tracing, useful to provide to SiteMinder when raising issues.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"

components:
  parameters:
    SmApiId:
      name: x-sm-api-id
      description: The api id for channel
      required: true
      in: header
      schema:
        type: string
    SmApiKey:
      name: x-sm-api-key
      description: The api key for channel
      required: true
      in: header
      schema:
        type: string

  responses:
    BadRequest:
      description: Invalid request
      headers:
        x-sm-request-id:
          schema:
            type: string
          description: uuid of the request, useful to provide to SiteMinder when raising issues.
        x-sm-trace-token:
          schema:
            type: string
          description: uuid used for tracing, useful to provide to SiteMinder when raising issues.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found
      headers:
        x-sm-request-id:
          schema:
            type: string
          description: uuid of the request, useful to provide to SiteMinder when raising issues.
        x-sm-trace-token:
          schema:
            type: string
          description: uuid used for tracing, useful to provide to SiteMinder when raising issues.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitError:
      description: The number of requests for the last 5 minutes window has reached the limit for the given channel
      headers:
        x-sm-request-id:
          schema:
            type: string
          description: uuid of the request, useful to provide to SiteMinder when raising issues.
        x-sm-trace-token:
          schema:
            type: string
          description: uuid used for tracing, useful to provide to SiteMinder when raising issues.
        ratelimit-policy:
          schema:
            type: string
          description: Shows the number of request allowed per number of seconds window. e.g. '100;w=60' means 100 request in a 60 seconds window.
        ratelimit-limit:
          schema:
            type: integer
          description: The number of requests allowed per window
        ratelimit-remaining:
          schema:
            type: integer
          description: The number of requests left for the time window.
        ratelimit-reset:
          schema:
            type: integer
          description: The number of seconds left for the window to reset
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected error occurred
      headers:
        x-sm-request-id:
          schema:
            type: string
          description: uuid of the request, useful to provide to SiteMinder when raising issues.
        x-sm-trace-token:
          schema:
            type: string
          description: uuid used for tracing, useful to provide to SiteMinder when raising issues.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    StarRatings:
      type: number
      enum:
        - 1
        - 1.5
        - 2
        - 2.5
        - 3
        - 3.5
        - 4
        - 4.5
        - 5
        - 5.5
        - 6
    CancelationPolicy:
      type: object
      additionalProperties: false
      description: >-
        Defines the cancellation policy for a reservation or rate.
        Policies can be either non-refundable or allow free cancellation up to a specified number of days before check-in.
      properties:
        policyType:
          type: string
          enum: ["non-refundable", "free-cancellation"]
          description: >-
            The type of cancellation policy.
            'non-refundable' means no refund will be provided regardless of when cancellation occurs.
            'free-cancellation' allows cancellation without penalty up to the specified number of days before check-in.
        freeCancellationUntilDays:
          type: number
          nullable: true
          description: >-
            Number of days before check-in when free cancellation is allowed.
            Only applicable when policyType is 'free-cancellation'. Null for non-refundable policies.
            For example, a value of 7 means guests can cancel up to 7 days before check-in without penalty.
      required:
        - policyType
    SpecialConditions:
      type: object
      additionalProperties: false
      nullable: true
      description: >-
        Special conditions or exemptions that apply to a property.
        These conditions may affect pricing, taxation, or booking requirements.
      properties:
        taxExemptions:
          type: array
          description: >-
            Array of tax exemptions applicable to this property.
            Tax exemptions affect how taxes are calculated and displayed in the booking flow.
          items:
            type: object
            additionalProperties: false
            properties:
              name:
                type: string
                enum:
                  - is-nz-gst-opt-out
                description: >-
                  The name/type of the tax exemption.
                  'is-nz-gst-opt-out' indicates the property has opted out of New Zealand GST collection.
            required:
              - name
      required:
        - taxExemptions
    Photo:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          description: The photo url
        captions:
          type: string
          description: The photo's captions
      required:
        - url
    TranslationText:
      type: object
      additionalProperties: false
      description: >-
        Represents multilingual text content with language information.
        Used for property descriptions, amenities, room types, and other user-facing content.
      properties:
        text:
          type: string
          description: The translated text content in the specified language.
        language:
          type: string
          description: >-
            ISO 639-1 language code indicating the language of the text.
            Supported languages: de (German), en (English), es (Spanish), fr (French),
            id (Indonesian), it (Italian), pt (Portuguese), th (Thai).
      required:
        - text
        - language
    Error:
      type: object
      required:
        - errors
      properties:
        errors:
          minItems: 1
          type: array
          description: An array of error objects, for most errors, this array would only contain one error object. An errors array must contain at least one error object.
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
              message:
                type: string
              meta:
                type: object
