openapi: 3.0.3
info:
  title: Affiliate Apartment Availabilities API
  version: 1.1.0
servers:
- url: https://external-api.holidu.com
tags:
- name: Availabilities
paths:
  /availabilities:
    post:
      operationId: availabilities
      summary: Get information about the availability of given offers
      description: Retrieve real-time prices and availability for specified properties on given dates.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                propertyIds:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 80
                  minItems: 1
                  maxItems: 200
                  description: List of property IDs
                checkin:
                  type: string
                  format: date
                  description: Check-in date in ISO format YYYY-MM-DD
                checkout:
                  type: string
                  format: date
                  description: Check-out date in ISO format YYYY-MM-DD
                adults:
                  type: integer
                  minimum: 1
                  maximum: 50
                  description: Number of adult guests
                children:
                  type: integer
                  minimum: 0
                  maximum: 50
                  description: Number of child guests
                childrenAges:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                  maxItems: 50
                  description: Ages of child guests
                currency:
                  type: string
                  pattern: ^[A-Z]{3}$
                  description: Currency code in ISO 4217 format, e.g. "USD"
                salesChannelId:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: Only for special cases, consult Holidu
                locale:
                  type: string
                  pattern: ^[a-z]{2}-[A-Z]{2}$
                  description: Locale code in format ISO 639-1 + ISO 3166-1 alpha-2, e.g. "en-US"
                country:
                  type: string
                  pattern: ^[A-Z]{2}$
                  description: Country code in ISO 3166-1 alpha-2 format
                domainId:
                  type: integer
                  description: Only for special cases, consult Holidu
                brand:
                  type: string
                  description: Only for special cases, consult Holidu
                deviceType:
                  type: string
                  enum:
                  - DESKTOP
                  - MOBILE
                  description: Device type, either "DESKTOP" or "MOBILE"
              required:
              - propertyIds
              - checkin
              - checkout
              - adults
              - children
              - currency
              - locale
              - country
              additionalProperties: false
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        propertyId:
                          type: string
                          minLength: 1
                        isAvailable:
                          type: boolean
                        price:
                          type: object
                          properties:
                            currency:
                              type: string
                              description: Currency code in ISO 4217 format, e.g. "USD"
                            daily:
                              type: number
                            total:
                              type: number
                            nights:
                              type: integer
                            discountAmount:
                              type: number
                              minimum: 0
                              nullable: true
                              description: Absolute discount amount in given currency
                            discountPercentage:
                              type: number
                              nullable: true
                            totalBeforeDiscount:
                              type: number
                              nullable: true
                            dailyBeforeDiscount:
                              type: number
                              nullable: true
                          required:
                          - currency
                          - daily
                          - total
                          - nights
                          - discountAmount
                          - discountPercentage
                          - totalBeforeDiscount
                          - dailyBeforeDiscount
                          additionalProperties: false
                          description: Price for the given dates. Null if property is not available for the given dates.
                          nullable: true
                        cancellationPolicy:
                          type: object
                          properties:
                            cancellationFees:
                              type: array
                              items:
                                type: object
                                properties:
                                  daysBeforeArrival:
                                    type: integer
                                    nullable: true
                                    description: Number of days before arrival from which this fee applies
                                  free:
                                    type: boolean
                                    description: Whether cancellation is free under this fee rule
                                  percentage:
                                    type: number
                                    nullable: true
                                    description: Percentage of the total price charged as a cancellation fee
                                  amount:
                                    type: number
                                    nullable: true
                                    description: Fixed amount charged as a cancellation fee
                                  currency:
                                    type: string
                                    nullable: true
                                    description: Currency code for the fixed cancellation fee amount
                                required:
                                - free
                                additionalProperties: false
                          required:
                          - cancellationFees
                          additionalProperties: false
                          nullable: true
                          description: Cancellation policy for the property. Null if not available.
                      required:
                      - propertyId
                      - isAvailable
                      - price
                      - cancellationPolicy
                      additionalProperties: false
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Property ID for which the error occurred
                        errorType:
                          type: string
                          description: Type of error that occurred
                      required:
                      - id
                      - errorType
                      additionalProperties: false
                    description: List of errors for properties that could not be fetched
                required:
                - items
                additionalProperties: false
        default:
          $ref: '#/components/responses/error'
      tags:
      - Availabilities
components:
  responses:
    error:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              issues:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                  required:
                  - message
                  additionalProperties: false
            required:
            - message
            - code
            additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Holidu authenticates to the affiliate using an OAuth 2.0 Bearer Token ([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)). Token exchange details are agreed upon during onboarding.