Swagger

openapi: 3.0.0
info:
  version: 0.0.1
  title: channels-plus-channel-api

paths:
  /properties:
    get:
      operationId: listProperties
      description: >-
        Find properties that match given search criteria. The response is an array of properties sorted by distance
        (nearest to furthest) unless otherwise specified. Each property includes a recommended package of the best
        available non-deal room rate. If deal codes are included, the best available deal room rate for each supported
        deal code will also be provided.
      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
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 20
            multipleOf: 10
        - name: latitude
          description: Specify a longitude (as well as a latitude and radius) to do searches around a specific location.
          required: true
          in: query
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: longitude
          description: Specify a longitude (as well as a latitude and radius) to do searches around a specific location.
          required: true
          in: query
          schema:
            type: number
            minimum: -180
            maximum: 180
        - name: radius
          description: The radius in Km to search around the specified latitude and longitude. The minimum value (and the default) is 15 and the maximum is 100.
          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: Use the rooms list specify exact occupants in each room. 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
                children:
                  type: integer
                  minimum: 0
                  maximum: 65535
              required:
                - adults
                - children
        - name: totalAdults
          description: Specify the total number of adults, must also specify totalRooms field. Do not use this if searching with occupants rooms list.
          in: query
          schema:
            type: integer
            minimum: 0
        - name: totalChildren
          description: Specify the total number of children, must also specify totalRooms field. Do not use this if searching with occupants rooms list.
          in: query
          schema:
            type: integer
            minimum: 0
        - name: totalRooms
          description: Specify the total number of rooms, must also specify totalAdults and/or totalChildren fields. Do not use this if searching with occupants rooms list.
          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: Limit search criteria to properties of a specific type.
          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 rate for properties that participates in the given deal
          in: query
          schema:
            type: array
            items:
              type: string
        - name: dealOnly
          description: exclude properties that are not on the deal with the given dealCode
          in: query
          schema:
            type: boolean
        - name: language
          description: used to specify is preferred language to return and fallback to property's default language
          in: query
          schema:
            type: string
            enum:
              - de
              - en
              - es
              - fr
              - id
              - it
              - pt
              - th

      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: accepted credit card types at this property
                      items:
                        type: string
                        enum:
                          - AX
                          - DN
                          - DS
                          - JC
                          - MC
                          - CU
                          - VI
                      minItems: 1
                    totalCommissionPercentage:
                      type: number
                      description: The total commission percentage for this property.
                    siteminderCommissionPercentage:
                      type: number
                      description: SiteMinder's portion of the commission percentage.
                    channelCommissionPercentage:
                      type: number
                      description: The channel partner's portion of the 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.
                          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 that are available for this room type
                            items:
                              $ref: '#/components/schemas/TranslationText'
                          bedConfigurations:
                            type: array
                            description: Bed configurations for this room type
                            items:
                              type: object
                              additionalProperties: false
                              properties:
                                bedCode:
                                  $ref: '#/components/schemas/TranslationText'
                                  description: The type of bed with language information.
                                quantity:
                                  type: number
                                  minimum: 1
                                  description: The number of beds of this type.
                          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
                          lowInventory:
                            type: boolean
                            description: Indicates whether this room type has low inventory available.
                        required:
                          - roomRateUuid
                          - roomTypeName
                          - ratePlanName
                          - breakfastIncluded
                          - adults
                          - children
                          - cancellationPolicy
                          - prices
                          - lowInventory
                    specialConditions:
                      $ref: '#/components/schemas/SpecialConditions'
                      description: Special conditions that apply to this property.
                  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:
                        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
                              ratePlanName:
                                type: string
                                description: Name of the rate plan
                              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
                              lowInventory:
                                type: boolean
                                description: Indicates if this room type has low inventory available
                            required:
                              - uuid
                              - ratePlanName
                              - breakfastIncluded
                              - totalPrice
                              - taxes
                              - fees
                              - adults
                              - children
                              - cancellationPolicy
                              - totalCommissionPercentage
                              - siteminderCommissionPercentage
                              - channelCommissionPercentage
                              - lowInventory
                      required:
                        - 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.
      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.
                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: