openapi: 3.0.3
info:
  title: ESY Travel Agent API Elements - OpenAPI 3.1
  description: |-
  version: 1.0.11
servers:
  - url: https://api.esytravel.net/api/api/agentapi
security:
  - BasicAuth: []
paths:
  /Availability:
    post:
      summary: Availability
      description: >-
        This API request is to confirm whether a trip on selected date time with
        selected prices and price units is available to book.
      operationId: Availability
      parameters:
        - name: operator_id
          in: query
          description: Required. Operator ID obtained from API portal or the operator.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: booking_type
          in: query
          description: Optional. (Default) = 1 is for new booking check (this will check new booking deadline); = 2 is edit existing booking check (this will check change booking deadline)
          required: true
          explode: true
          schema:
            type: string
            default: 1
        - name: bookingarr
          in: query
          description: Required. Object array contains elements of trip date and time etc. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                item_id:
                  type: string
                  description: Required. 'item_id' element of bookingarr. Operator's product code.
                date:
                  type: string
                  description: Required. 'date' element of bookingarr. Trip date in yyyy-mm-dd format
                time:
                  type: string
                  description: Optional. 'time' element of bookingarr. Trip time in H:i format. If product to book has only trip date, time is not required.
        - name: pricearr
          in: query
          description: Required. Object array contains elements of booking price details. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                price_id_agent:
                  type: string
                  description: Required. 'price_id_agent' element of pricearr. Agent's price code matched to operator's price code.
                unit:
                  type: integer
                  description: Required. 'unit' element of pricearr. Unit to be booked for the price.
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
        '400':
          description: Request is not valid
  /Reservation:
    post:
      summary: Reservation
      description: >-
        This API request is to temporary reserve a booking for a trip on
        selected date and time. The booking is unconfirmed and will last no more
        than 20 minutes before it get cancelled by the system.
      operationId: Reservation
      parameters:
        - name: operator_id
          in: query
          description: Required. Operator ID obtained from API portal or the operator.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: bookingarr
          in: query
          description: Required. Object array contains elements of trip date and time etc. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            example:
              - item_id: '1005'
                date: '2022-02-27'
                time: '12:00'
                ag_booking_ref: '1'
                agent_note: Booking Request
                pickup_location: The Station Building
            items:
              type: object
              properties:
                item_id:
                  type: string
                  description: Required. 'item_id' element of bookingarr. Operator's product code
                date:
                  type: string
                  description: Required. 'date' element of bookingarr. Trip date in yyyy-mm-dd format
                time:
                  type: string
                  description: Optional. 'time' element of bookingarr. Trip time in H:i format. If product to book has only trip date, time is not required.
                ag_booking_ref:
                  type: string
                  description: Optional. 'ag_booking_ref' element of bookingarr. Agent's booking ref set by the agent.
                agent_note:
                  type: string
                  description: Optional. 'agent_note' element of bookingarr. Note set by the agent to be passed on to the operator.
                pickup_location:
                  type: string
                  description: Optional. 'pickup_location' element of bookingarr. Pickup location name for activity booking only.
        - name: pricearr
          in: query
          description: Required. Object array contains booking price details. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                price_id_agent:
                  type: string
                  description: Required. 'price_id_agent' element of pricearr. Agent's price code linked to operator's price code
                unit:
                  type: integer
                  description: Required. 'unit' element of pricearr. Unit to be booked for the price
                price:
                  type: number
                  description: Number value with maximum 2 decimals. Optional. 'price' element of pricearr. Gross sale price including commission and tax. Required only when operator allows price override.
        - name: contactarr
          in: query
          description: Required. Object array contains booking guest contact details. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                givenname:
                  type: string
                  description: Required. 'givenname' element of contactarr. Booking contact give name or first name.
                familyname:
                  type: string
                  description: Required. 'familyname' element of contactarr. Booking contact family name or last name
                phone_no:
                  type: string
                  description: Required. 'phone_no' element of contactarr. Booking contact resident home phone no
                emailaddress:
                  type: string
                  description: Required. 'emailaddress' element of contactarr. Booking contact email. This will be used to send guest booking voucher.
                businessname:
                  type: string
                  description: Optional. 'businessname' element of contactarr. Booking contact business name.
                    only
                phone_country_code:
                  type: string
                  description: Optional. 'phone_country_code' element of contactarr. Used to determine the country of the guest.
                phone_no2:
                  type: string
                  description: Optional. 'phone_no2' element of contactarr. Guest's travel phone no at destination.
                iso_country_code:
                  type: string
                  description: Optional. 'iso_country_code' element of contactarr. Guest's resident country in ISO numeric code
                country_name:
                  type: string
                  description: Optional. 'country_name' element of contactarr. Guest's country name.
                region_name:
                  type: string
                  description: Optional. 'region_name' element of contactarr. Guest's resident region of the country.

        - name: guestarr
          in: query
          description: Required. Object array contains individual booking guest details. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                givenname:
                  type: string
                  description: Required. 'givenname' element of guestarr. Guest give name or first name.
                familyname:
                  type: string
                  description: Required. 'familyname' element of guestarr. Guest family name or last name.
                skill_level:
                  type: string
                  description: Optional. 'skill_level' element of guestarr. =1 Beginner; =2 Intermediate; =3 Advanced.
                gender:
                  type: string
                  description: Optional. 'gender' element of guestarr. =1 Adult Male; =2 Adult Female; =3 Boy Child; =4 Girl Child; =5 Infant; =6 Golden Age Male; =7 Golden Age Female; =8 Other.
                weight:
                  type: string
                  description: Optional. 'weight' element of guestarr. guest's weight in the number of kilometers (kg) only.
                    only
                height:
                  type: string
                  description: Optional. 'height' element of guestarr. guest's height in the number of centimeters (cm) only.
                    only
                birthdate:
                  type: string
                  description: Optional. 'birthdate' element of guestarr. guest's birth date in the format of of 'Y-m-d'
                health:
                  type: string
                  description: Optional. 'health' element of guestarr. guest's special medical conditions, eg. food requirements.
                region:
                  type: string
                  description: Optional. 'region' element of guestarr. guest's residential region.
                note:
                  type: string
                  description: Optional. 'note' element of guestarr. Extra note for the guest.
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldBooking'
        '400':
          description: Request is NOT valid
  /CancelBooking:
    get:
      summary: CancelBooking
      description: >-
        This API request is to cancel a booking either it is unconfirmed or
        confirmed. This cancellation will cancel the booking and restore the
        places for others to book. If the booking is a confirmed booking, it
        will be verified by the booking change deadline condition set by the
        individual operator (usually the deadline is a number of days or hours
        before the scheduled trip date time).
      operationId: CancelBooking
      parameters:
        - name: operator_id
          in: query
          description: Required. Operator ID obtained from API portal or the operator.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: op_booking_id
          in: query
          description: Required. Operator's booking ID of the temporary reserved booking to be cancelled.
          required: true
          explode: true
          schema:
            type: string
        - name: ag_booking_ref
          in: query
          description: Optional. Integrator / booking agent's booking ref for its own use.
          required: false
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBooking'
        '400':
          description: Request is NOT valid
  /ConfirmBooking:
    get:
      summary: ConfirmBooking
      description: >-
        This API request is to change an unconfirmed booking into a confirmed
        (active) booking. An unconfirmed booking is a temporary booking that it
        has reserved places for the guests before making booking payment or
        before confirming the booking. The unconfirmed booking will last 20
        minutes. If this booking is not confirmed within the 20 minutes time
        frame, it will be cancelled by the system.
      operationId: ConfirmBooking
      parameters:
        - name: operator_id
          in: query
          description: Operator ID provided by the platform
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: op_booking_id
          in: query
          description: Required. Operator's booking ID of the temporary reserved booking.
          required: true
          explode: true
          schema:
            type: string
        - name: ag_booking_ref
          in: query
          description: Optional. Integrator / booking agent's booking ref for its own use only.
          required: false
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmBooking'
        '400':
          description: Request is NOT valid
  /BookingStatus:
    get:
      summary: BookingStatus
      description: >-
        This API request is to fetch booking details including scheduled trip
        date time, status of the booking and others. 
        Booking can be a specified booking or all bookings within selected date 
        ranges (by scheduled trip date and or booking created date). 
        If op_booking_id parameter in the request is specified, it fetches one 
        booking only regardless the value of date parameters in the request. 
        If op_booking_id parameter in the request is not specified (empty or not
        provided), it fetches all bookings made by the agent within the selected 
        date ranges.
        The date ranges can be either booking created date (between 
        date_created_start and date_created_end) or booking trip scheduled date 
        (between date_start and date_end) or both if both dates are set. 
        There is an optional search date 'date_lastchanged'. If this is set, 
        search for bookings with last changed date on or later than the selected 
        date.
        At least one of the above three date ranges is required. The maximum number
        of days (date length in between start and end date) can be no more than 
        31 days. The oldest date can go back is 180 days before operator today unless
        optional parameter date_lastchanged is provided which can only allow fetching bookings 
        back to 31 days from today.
        All dates in the request and response shall be the local date in 
        operator's timezone.
      operationId: BookingStatus
      parameters:
        - name: operator_id
          in: query
          description: Required. Operator ID obtained from API portal or the operator.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: op_booking_id
          in: query
          description: Optional. Operator's booking ID of the booking to be checked. If not empty, fetch only this booking.
          explode: true
          schema:
            type: string
        - name: date_created_start
          in: query
          description: Optional. If this is set, it will search bookings for booking created date between date_created_start and date_created_end
          explode: true
          schema:
            type: string
        - name: date_created_end
          in: query
          description: Optional. If this is set, it will search bookings for booking created date between date_created_start and date_created_end
          explode: true
          schema:
            type: string
        - name: date_start
          in: query
          description: Optional. If this is set, it will search bookings for booking trip departure date between date_start and date_end.
          explode: true
          schema:
            type: string
        - name: date_end
          in: query
          description: Optional. If this is set, it will search bookings for booking trip departure date between date_start and date_end.
          explode: true
          schema:
            type: string
        - name: date_lastchanged
          in: query
          description: Optional. If this is set, it will search bookings with last changed date on or after the selected date.
          explode: true
          schema:
            type: string
        - name: language_id
          in: query
          description: Optional. Used in response for product and price name. (Default) =1 English; =2 Chinese.
          explode: true
          schema:
            type: string
            default: 1
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingStatus'
        '400':
          description: Request is NOT valid
  /EditBooking:
    post:
      summary: EditBooking
      description: >-
        This API request is to change an existing active booking or a pending
        reservation in shopping cart with new trip on same or new date and same
        or new time and/or new guest details. New trip info must include all
        required booking info even they are not changed.
      operationId: EditBooking
      parameters:
        - name: operator_id
          in: query
          description: Required. Operator ID obtained from API portal or the operator.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: bookingarr
          in: query
          description: Required. Object array contains elements of trip date and time etc. See developer page for more details.
          style: form
          required: true
          explode: true
          schema:
            type: array
            example:
              - op_booking_id: '10337'
                item_id: '500'
                date: '2022-03-01'
                time: '11:00'
                ag_booking_ref: '156895'
                agent_note: Edit Booking Request
                pickup_location: The Station Building
            items:
              type: object
              properties:
                op_booking_id:
                  type: string
                  description: Required. 'op_booking_id' element of bookingarr. Operator's booking id.
                item_id:
                  type: string
                  description: Required. 'item_id' element of bookingarr. Operator's product code.
                date:
                  type: string
                  description: BRequired. 'date' element of bookingarr. Booking scheduled date in Y-m-d format in operator time zone.
                time:
                  type: string
                  description: Optional. 'time' element of bookingarr. Booking trip time in H:i format. It maybe empty if trip has trip date only.
                ag_booking_ref:
                  type: string
                  description: Optional. 'ag_booking_ref' element of bookingarr. Agent's booking ref set by the agent.
                agent_note:
                  type: string
                  description: Optional. 'agent_note' element of bookingarr. Note set by the agent to be passed on as booking note.
                pickup_location:
                  type: string
                  description: Optional. 'pickup_location' element of bookingarr. For activity only. Activity pickup location name (not address).
        - name: pricearr
          in: query
          description: Required. Object array contains booking price details. Can be multiple prices.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                price_id_agent:
                  type: string
                  description: Required. 'price_id_agent' element of pricearr. Agent's price code to match operator's price code
                unit:
                  type: integer
                  description: Required. 'unit' element of pricearr. Unit to be booked for the price
                price:
                  type: number
                  description: Number value in maximum 2 decimals. Optional. 'price' element of pricearr. Gross sale price including commission and tax. Required only when the API allows price override.
        - name: contactarr
          in: query
          description: Required. Object array contains booking guest contact details. One contact per booking.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                givenname:
                  type: string
                  description: Required. 'givenname' element of contactarr. Booking contact given name or first name.
                familyname:
                  type: string
                  description: Required. 'familyname' element of contactarr. Booking contact family name or last name.
                phone_no:
                  type: string
                  description: Required. 'phone_no' element of contactarr. Booking contact resident home phone no
                emailaddress:
                  type: string
                  description: Required. 'emailaddress' element of contactarr. Booking contact email. This will be used to send guest booking voucher.
                businessname:
                  type: string
                  description: Optional. 'businessname' element of contactarr. Booking contact business name.
                phone_no2:
                  type: string
                  description: Optional. 'phone_no2' element of contactarr. Guest travel phone no at destination
                phone_country_code:
                  type: string
                  description: Optional. 'phone_country_code' element of contactarr. Used to determine the country of the guest.
                iso_country_code:
                  type: string
                  description: Optional. 'iso_country_code' element of contactarr. Used to determine the country of the guest.
                country_name:
                  type: string
                  description: Optional. 'country_name' element of contactarr in English. Used to determine the country of the guest.
                region_name:
                  type: string
                  description: Optional. 'region_name' element of contactarr in English. Used to determine the region of the guest.
        - name: guestarr
          in: query
          description: Required. Object array contains individual booking guest details. Can be multiple guests.
          style: form
          required: true
          explode: true
          schema:
            type: array
            items:
              type: object
              properties:
                givenname:
                  type: string
                  description: Required. 'givenname' element of guestarr. Guest given name or first name
                familyname:
                  type: string
                  description: Required. 'familyname' element of guestarr. Guest family name or last name
                note:
                  type: string
                  description: Optional. 'note' element of guestarr. Extra note for the guest.
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditBooking'
        '400':
          description: Request is NOT valid
  /Timetable:
    get:
      summary: Timetable
      description: >-
        This API request is to fetch all trip departure dates (date), departure
        time (time) and remaining place number (place). Search are based on a
        selected date for a number of days up to 31 days of a selected product
        of a selected operator. Response is in json format.The selected date
        must be on or later than operator's current local date.If the number of
        days is smaller than 1, it will be treated as 1. If it is bigger than 31
        days, it returns error with a response code.Only date and time with
        available place will be included in the response. Some products may have
        no departure time but departure date only. For those products, "time"
        value in timetable parameter in the response will be empty.
        When "Price over API" is enabled, 'prices' array will be available 
        which it supplies prices on each date and time. If this option is enabled, 
        use GET 'Timetable' to fetch prices instead of GET 'Prices'.
        When this options is enabled and "Tiered Prices" is also enabled, 
        'tiered_prices' array will be available.
      operationId: Timetable
      parameters:
        - name: booking_type
          in: query
          description: >-
            1 is for new booking check (this will check booking closed
            deadline); = 2 is edit existing booking check (this will check
            booking change deadline).
          required: true
          explode: true
          schema:
            type: string
        - name: date
          in: query
          description: >-
            The first trip date on the timetable in Y-m-d format (eg.
            2021-10-20).
          required: true
          explode: true
          schema:
            type: string
        - name: days
          in: query
          description: >-
            Number of days to be checked. Day number is between 1 to 31. If it
            is not set, default to 1.
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: operator_id
          in: query
          description: Operator ID provided by the platform
          required: true
          explode: true
          schema:
            type: string
        - name: item_id
          in: query
          description: Operator's product code.
          explode: true
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timetable'
        '400':
          description: Request is NOT valid
  /Prices:
    get:
      summary: Prices
      description: >-
        This API query is to fetch all prices available to the agent for selected product. 
        Each agent price code is mapped to one operator price only when use this query.
        If 'Price over API' option is enabled by the operator, use GET 'Timetable' to fetch prices on each time spot instead of GET 'Prices'.
      operationId: Prices
      parameters:
        - name: operator_id
          in: query
          description: Operator ID provided by the platform
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Booking agent (Integrator) own reference for its own use.
          required: false
          explode: true
          schema:
            type: string
        - name: item_id
          in: query
          description: Operator's product code
          required: true
          explode: true
          schema:
            type: string
        - name: language_id
          in: query
          description: >-
            Optional. Default as 1 (English). =1 English; =2 Chinese. Used as
            selected language for price name and description in the response.
          explode: true
          required: false
          schema:
            type: string
            default: 1
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prices'
        '400':
          description: Request is NOT valid
  /Product:
    get:
      summary: Product
      description: >-
        This API request is to fetch details of a selected activity or tour
        product of a selected operator.
      operationId: Product
      parameters:
        - name: operator_id
          in: query
          description: Operator ID provided by the platform
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Agent's booking reference.
          required: false
          explode: true
          schema:
            type: string
        - name: item_id
          in: query
          description: Operator's product code
          required: true
          explode: true
          schema:
            type: string
        - name: language_id
          in: query
          description: >-
            Optional. Default as 1 (English). =1 English; =2 Chinese. Used as
            selected language for price name and description in the response.
          explode: true
          required: false
          schema:
            type: string
            default: 1
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Request is NOT valid
  /ProductList:
    get:
      summary: ProductList
      description: >-
        This API request is to fetch a list of all available activity or tour
        products of a selected operator and the details of each product
      operationId: ProductList
      parameters:
        - name: operator_id
          in: query
          description: Operator ID provided by the platform
          required: true
          explode: true
          schema:
            type: string
        - name: integrator_ref
          in: query
          description: Optional. Agent's booking reference.
          required: false
          explode: true
          schema:
            type: string
        - name: language_id
          in: query
          description: >-
            Optional. Default as 1 (English). =1 English; =2 Chinese. Used as
            selected language for price name and description in the response.
          explode: true
          required: false
          schema:
            type: string
            default: 1
      responses:
        '200':
          description: Request Succeed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '400':
          description: Request is NOT valid
components:
  schemas:
    Availability:
      type: object
      properties:
        operator_id:
          type: string
          example:
            - '1001'
          description: Operator ID of the operator
        integrator_ref:
          type: string
          example: []
          description: Booking agent (Integrator) own reference for its own use.
        item_id:
          type: integer
          example:
            - '6'
          description: Operator product code matched to agent product code
        date:
          type: string
          example:
            - '2026-01-23'
          description: Trip departure date in Y-m-d (eg. 2026-01-23) format in operator's time zone.
        time:
          type: string
          example:
            - '12:00'
          description: Trip departure time in H:i format (eg. 12:00)
        place:
          type: integer
          example:
            - 1
          description: Remaining place on selected date time
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Place available). See other values on error code table.
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        message:
          type: string
          example:
            - Request succeed
          description: Response message related to error code
        prices:
          type: array
          items:
            type: object
            description: Operator prices array matched to each agent price code.
            properties:
              price_id_agent:
                type: string
                example: 'Adult'
                description: Agent price code
              price:
                type: number
                example: 149
                description: Number value with max 2 decimals. Retail price before commission.
              price_net:
                type: number
                example: 134.1
                description: Number value with max 2 decimals. Net price after commission.
              unit:
                type: integer
                example: 1
                description: Number of price units
              commission_rate:
                type: number
                example: 10
                description: Number value with max 2 decimals. Agent commission rate. 10 means 10%.

    HoldBooking:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Reservation is successful). See other values on error code table.
        operator_id:
          type: string
          example:
            - '1001'
          description: Operator ID of the operator
        ag_booking_ref:
          type: string
          example:
            - '12505'
          description: Integrator agent's booking ref passed from the API request for its own use only.
        integrator_ref:
          type: string
          example:
            - booking reservation
          description: Integrator's ref passed from the API request.
        op_booking_id:
          type: string
          example:
            - '10337'
          description: If 'response_code' = 200, 'op_booking_id' will be set in the response.
        expiry_datetime:
          type: string
          example:
            - '2023-10-26T11:41:15+13:00'
          description: Booking expiry date and time in ISO 8601 format with timezone offset
        message:
          type: string
          example:
            - Reservation Successful
          description: Response message related to error code
    CancelBooking:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Cancellation is successful). See other values on error code table.
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        op_booking_id:
          type: string
          example:
            - '10245'
          description: perator booking ID cancelled or to be cancelled
        ag_booking_ref:
          type: string
          example:
            - '10545122'
          description: Integrator agent's booking ref passed from the API request.
        integrator_ref:
          type: string
          example:
            - Cancel booking
          description: Integrator's ref passed from the API request.
        message:
          type: string
          example:
            - Reservation is cancelled successful
          description: Response message related to error code
    ConfirmBooking:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Booking is successful). See other values on error code table.
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        op_booking_id:
          type: string
          example:
            - '10337'
          description: Operator's booking ID of the reserved booking (change the reservation into active booking)
        ag_booking_ref:
          type: string
          example:
            - '10545122'
          description: Integrator agent's booking ref passed from the API request.
        integrator_ref:
          type: string
          example:
            - Confirm booking
          description: Integrator's ref passed from the API request.
        message:
          type: string
          example:
            - Booking Successful
          description: Response message related to error code
    BookingStatus:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: Value = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: Value = 710 Request succeed (Bookings are found). See other values on error code table.
        message:
          type: string
          example:
            - Bookings are found
          description: Response message related to error code
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        op_booking_id:
          type: string
          example: '10878'
          description: Operator's booking ID
        integrator_ref:
          type: string
          example:
            - booking status
          description: Integrator's ref passed from the API request.
        language_id:
          type: string
          example:
            - 1
          description: Used in response for product and price name. (Default) =1 English; =2 Chinese.
        bookingarr:
          type: array
          items:
            type: object
            description: Operator booking details array.
            properties:
              op_booking_id:
                type: string
                example: '10878'
                description: Operator's booking ID. Part of bookingarr array.
              status:
                type: string
                example: cancelled
                description: Operator's booking status. Part of bookingarr array. Value = active, completed, cancelled, closed or pending.
              item_id:
                type: string
                example: 1005
                description: Operator's booking product code. Part of bookingarr array.
              product_name:
                type: string
                example: Test name
                description: Product name in selected language. Part of bookingarr array.
              bookingnote:
                type: string
                example: Booking notes
                description: Product booking note in selected language. Part of bookingarr array.
              date:
                type: string
                example: '2022-10-31'
                description: Booking scheduled trip date in operator time zone in the format of Y-m-d. Part of bookingarr array.
              time:
                type: string
                example: '12:00'
                description: Booking scheduled trip time. Part of bookingarr array.
              date_created:
                type: string
                example: '2022-10-15'
                description: Booking created date in operator time zone in the format of Y-m-d. Part of bookingarr array.
              date_cancelled:
                type: string
                example: '2022-10-15'
                description: Booking cancelled date in operator time zone in the format of Y-m-d. Part of bookingarr array.
              date_checkedin:
                type: string
                example: null
                description: Booking checked-in date in operator time zone in the format of Y-m-d. Part of bookingarr array.
              date_lastchanged:
                type: string
                example: '2022-10-15 19:53:09'
                description: Booking last changed date in operator time zone in the format of Y-m-d. Part of bookingarr array.
              given_name:
                type: string
                example: guestgivenname
                description: Booking guest contact given (first) name. Part of bookingarr array.
              family_name:
                type: string
                example: guestfamilyname
                description: Booking guest contact family (last) name. Part of bookingarr array.
              phone:
                type: string
                example: '021'
                description: Booking guest contact phone number. Part of bookingarr array.
              emailaddress:
                type: string
                example: sales@esytravel.com
                description: Booking guest contact email address. Part of bookingarr array.
              prices:
                type: array
                description: Booking price array. Part of bookingarr array.
                items:
                  type: object
                  properties:
                    price_id:
                      type: string
                      example: '1132'
                      description: Operator's price ID. Part of bookingarr array.
                    price:
                      type: string
                      example: '150.00'
                      description: Number with 2 decimals. Operator's booking price before agent commission. Part of bookingarr array.
                    price_net:
                      type: string
                      example: '135.00'
                      description: Number with 2 decimals. Operator's booking net price after agent commission. Part of bookingarr array.
                    unit:
                      type: integer
                      example: 1
                      description: Operator's booking price unit. Part of bookingarr array.
                    commission_rate:
                      type: string
                      example: '10.00'
                      description: Number in maximum 2 decimal. Operator's booking price's agent commission rate. Part of bookingarr array.
                    name:
                      type: string
                      example: Adult
                      description: Operator's price name in selected language. Part of bookingarr array.
              guestarr:
                type: array
                description: Booking guests array. Part of bookingarr array.
                items:
                  type: object
                  properties:
                    given_name:
                      type: string
                      example: guestgivenname
                      description: Booking guest's given (first) name. Part of bookingarr array.
                    family_name:
                      type: string
                      example: guestfamilyname
                      description: Booking guest's family (last) name. Part of bookingarr array.
              location_arr:
                type: array
                description: Booking pickup locations array. Part of bookingarr array.
                items:
                  type: object
                  properties:
                    pickup_location:
                      type: string
                      example: The Station Building
                      description:  Booking pickup location name in selected language. Part of bookingarr array.
                    pickup_address:
                      type: string
                      example: Inside Station Building
                      description:  Booking pickup location address in selected language. Part of bookingarr array.
    EditBooking:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: Value = 710 Request succeed (Booking is changed successfully). See other values on error code table.
        operator_id:
          type: string
          example:
            - '1001'
          description: Operator ID of the operator
        op_booking_id:
          type: string
          example:
            - '10337'
          description: Operator booking id
        integrator_ref:
          type: string
          example:
            - edit booking
          description: Integrator's ref passed from the API request.
        message:
          type: string
          example:
            - Booking is changed successfully
          description: Description message about the error code
    Timetable:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: String. = 200 Request succeed. 400 Request is NOT valid.
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Place is available). See other values on error code table.
        message:
          type: string
          example:
            - Request succeed
          description: Response message related to error code 
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        integrator_ref:
          type: string
          example:
            - timetable
          description: Integrator's ref passed from the API request.
        item_id:
          type: string
          example:
            - 6
          description: Passed from API request. Integrator or booking agent's product code matched to operator's product ID.
        product_type:
          type: string
          example:
            - 'INDIVIDUAL_TIME_ACTIVITY'
          description: Value shall be 'INDIVIDUAL_TIME_ACTIVITY', 'TIME_PERIOD_ACTIVITY' or 'MULTI_DAYS_TOUR'.
        timetable:
          type: array
          description: Trip timetable array with optional prices array.
          items:
            type: object
            properties:
              date:
                type: string
                example: '2022-02-22'
                description: Trip date in the format of Y-m-d.
              time:
                type: string
                example: '09:00'
                description: Trip time in the format of H:i. Only when product_type is INDIVIDUAL_TIME_ACTIVITY, this time parameter will be available. Otherwise it will be empty.
              place:
                type: integer
                example: 10
                description: Available place number.
              business_hours:
                type: array
                description: only when product_type value is 'TIME_PERIOD_ACTIVITY', this business_hour parameter will be available in the response
                items:
                  type: object
                  properties:
                    from_time:
                      type: string
                      example: '10:00'
                      description: From time in the format of H:i
                    to_time:
                      type: string
                      example: '17:00'
                      description: To time in the format of H:i
              currency:
                type: string
                example: 'NZD'
                description: Currency name of prices. Only available when 'Price over API' is enabled by the operator/supplier.
              prices:
                type: array
                description: The non-tiered prices at the date time. Only available when 'Price over API' is enabled by the operator/supplier.
                items:
                  type: object
                  properties:
                    price_id_agent:
                      type: string
                      example: 'Adult'
                      description: Agent's price code mapped to an operator's price_id.
                    place_count:
                      type: integer
                      example: 1
                      description: Number of places counted for each price unit booked.
                    price:
                      type: number
                      example: 160.00
                      description: Number value with maximum 2 decimals. Retail price before agent commission.
                    price_net:
                      type: number
                      example: 144.00
                      description: Number value with maximum 2 decimals. Net price after agent commission.
                    commission_rate:
                      type: number
                      example: 10
                      description: Number value with maximum 2 decimals. Agent commission rate without %. For example, 10 means 10%.
                    name:
                      type: string
                      example: 'Adult'
                      description: Price name.
                    description:
                      type: string
                      example: 'Price for all agents'
                      description: Price description. It can be used to explain how and why to book the price.
                    min_unit:
                      type: integer
                      example: 1
                      description: Minimum number of price units required to book. When it is 0, it has no effect.
                    max_unit:
                      type: integer
                      example: 0
                      description: Maximum number of price units can be booked. When it is 0, it has no effect.
              tiered_prices:
                type: array
                description: The tiered prices and conditions at the date time. Only available when 'Price over API' is enabled by the operator/supplier.
                items:
                  type: object
                  properties:
                    price_id_agent:
                      type: string
                      example: 'Adult'
                      description: Agent's price code mapped to an operator's price_id.
                    place_count:
                      type: integer
                      example: 1
                      description: Number of places will be reduced for each price unit booked.
                    price:
                      type: number
                      example: 160.00
                      description: Default price value with maximum 2 decimals before agent commission. When none of the tiered conditions are met, this price will be used.
                    price_net:
                      type: number
                      example: 144.00
                      description: Default net price value with maximum 2 decimals after agent commission. When none of the tiered conditions are met, this price will be used.
                    commission_rate:
                      type: number
                      example: 10
                      description: Agent commission rate without % with maximum 2 decimals. For example, 10 means 10%.
                    name:
                      type: string
                      example: 'Adult'
                      description: Price name.
                    description:
                      type: string
                      example: 'Price for all agents'
                      description: Price description. It can be used to explain how and why to book the price.
                    min_unit:
                      type: integer
                      example: 1
                      description: Minimum unit of the prices required to book. When it is 0, it has no effect.
                    max_unit:
                      type: integer
                      example: 0
                      description: Maximum unit of the prices can be booked. When it is 0, it has no effect.
                    tiered:
                      type: array
                      description: The tiered conditions to set prices.
                      items:
                        type: object
                        properties:
                          price:
                            type: number
                            example: 149
                            description: Retail price value with maximum 2 decimals before agent commission.
                          price_net:
                            type: number
                            example: 149
                            description: Net price value with maximum 2 decimals after agent commission.
                          low_unit:
                            type: integer
                            example: 10
                            description: The lower end of the price unit tier range. For example, 10 of the price unit tier 10 to 20. When the booked price unit is 15, use this price.
                          top_unit:
                            type: integer
                            example: 20
                            description: The higher end of the price unit tier range. For example, 20 of the price unit tier 10 to 20. When the booked price unit is 15, use this price.
    Prices:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Price is available). See other values on error code table.
        message:
          type: string
          example:
            - Request succeed
          description:  Response message for error code.
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        integrator_ref:
          type: string
          example:
            - prices
          description: Integrator's ref passed from the API request.
        item_id:
          type: integer
          example:
            - 500
          description: Operator's product code
        language_id:
          type: string
          example:
            - '1'
          description: Language ID for price name (1 English; 2 Chinese).
        prices:
          type: array
          description: Array of prices
          items:
            type: object
            properties:
              price_id_agent:
                type: string
                example: 'Adult'
                description: Agent's price code mapped to operator's price_id.
              place_count:
                type: integer
                example: 1
                description: Place number booked for each price unit.
              price:
                type: number
                example: 150.00
                description: Number value with maximum 2 decimals. Retail price before agent commission.
              price_net:
                type: number
                example: 135.00
                description: Number value with maximum 2 decimals. Net price after agent commission.
              commission_rate:
                type: number
                example: 10
                description: Number value with maximum 2 decimals. Agent commission rate without %. For example 10 means 10%.
              name:
                type: string
                example: 'Adult'
                description: Price name in selected language.
              description:
                type: string
                example: 'Adult Price'
                description: Price description in selected language
              min_unit:
                type: integer
                example: 1
                description: Minimum price unit required. = 0 this option has no effect. 
              max_unit:
                type: integer
                example: 0
                description: Maximum price unit allowed. = 0 this option has no effect.  
    Product:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description: = 710 Request succeed (Product is found and fetched). See other values on error code table.
        message:
          type: string
          example:
            - Product is found
          description: Response message related to error code
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        integrator_ref:
          type: string
          example:
            - product_details
          description: Optional. Integrator's ref passed from the API request.
        language_id:
          type: string
          example:
            - '1'
          description: Language ID for product name and description (1 = English; 2 = Chinese)
        product_arr:
          type: array
          description: product array
          items:
            type: object
            properties:
              item_id:
                type: string
                example: '500'
                description: Operator's product code of product array.
              product_type:
                type: string
                example: INDIVIDUAL_TIME_ACTIVITY
                description: Product type is either INDIVIDUAL_TIME_ACTIVITY,
                  TIME_PERIOD_ACTIVITY or MULTI_DAYS_TOUR.
              minimum_no:
                type: integer
                example: 1
                description: Minimum guest number required in the booking. Part of the product array.
              product_name:
                type: string
                example: Motocycle Activity
                description: Product name in selected language. Part of the product array.
              short_product_name:
                type: string
                example: Motocycle Activity
                description: Short product name in selected language. Part of the product array.
              description:
                type: string
                example: '----This is html contents-------'
                description: Product description in selected language. Part of the product array.
              bookingnote:
                type: string
                example: '----This is html contents-------'
                description: Product booking notes in selected language. Part of the product array.
              location_arr:
                type: array
                description:  Pickup location array. For 'activity' product only. Part of the product array.
                items:
                  type: object
                  properties:
                    pickup_location:
                      type: string
                      example: The Station Building
                      description: Pickup location name in selected language. For 'activity' product only. Part of the location_arr array.
                    pickup_address:
                      type: string
                      example: Corner Camp Street
                      description: Pickup location address in selected language. For 'activity' product only. Part of the location_arr array.
              guide_language:
                type: string
                example: '1'
                description: Tour guide language ID (=1 English; = 2 Chinese). For 'tour' product only. Part of the product array
              tourcity_arr:
                type: array
                description: Cities to be visited. For 'tour' product only. Part of the product array.
                items:
                  type: object
                  properties:
                    city_name:
                      type: string
                      example: Auckland
                      description: Tour city name in selected language. For 'tour' product only. Part of the tourcity_arr array.
                    no_of_nights:
                      type: string
                      example: '1'
                      description: Number of nights stayed in a tour city. For 'tour' product only. Part of the tourcity_arr array.
    ProductList:
      type: object
      properties:
        response_code:
          type: string
          example:
            - '200'
          description: = 200 Request succeed. 400 Request is NOT valid
        error_code:
          type: string
          example:
            - '710'
          description:  = 710 Request succeed (Product is found and fetched). See other values on error code table.
        message:
          type: string
          example:
            - Product is found
          description: Response message related to error code
        operator_id:
          type: string
          example:
            - sample_op_id
          description: Operator ID of the operator
        integrator_ref:
          type: string
          example:
            - product_details
          description: Optional. Integrator's ref passed from the API request.
        language_id:
          type: string
          example:
            - '1'
          description:  Language ID for product name and description (1 = English; 2 = Chinese)
        product_arr:
          type: array
          items:
            type: object
            description: Product details.
            properties:
              item_id:
                type: string
                example: '5'
                description: Operator's product code of product array.
              product_type:
                type: string
                example: INDIVIDUAL_TIME_ACTIVITY
                description: Product type is either INDIVIDUAL_TIME_ACTIVITY,
                  TIME_PERIOD_ACTIVITY or MULTI_DAYS_TOUR.
              minimum_no:
                type: integer
                example: 1
                description: Minimum guest number required in the booking. Part of the product array.
              product_name:
                type: string
                example: Motocycle Activity
                description: Product name in selected language. Part of the product array.
              short_product_name:
                type: string
                example: Motocycle Activity
                description: Short product name in selected language. Part of the product array.
              description:
                type: string
                example: '----This is html contents-------'
                description: Product description in selected language. Part of the product array.
              bookingnote:
                type: string
                example: '----This is html contents-------'
                description: Product booking notes in selected language. Part of the product array.
              location_arr:
                type: array
                description: Pickup location array. For 'activity' product only. Part of the product array.
                items:
                  type: object
                  properties:
                    pickup_location:
                      type: string
                      example: The Station Building
                      description: Pickup location name in selected language. For 'activity' product only. Part of the location_arr array.
                    pickup_address:
                      type: string
                      example: Corner Camp Street
                      description: Pickup location address in selected language. For 'activity' product only. Part of the location_arr array.
              guide_language:
                type: string
                example: '1'
                description: Tour guide language ID (=1 English; = 2 Chinese). For 'tour' product only. Part of the product array.
              tourcity_arr:
                type: array
                description: Cities to be visited. For 'tour' product only. Part of the product array.
                items:
                  type: object
                  properties:
                    city_name:
                      type: string
                      example: Auckland
                      description: Tour city name in selected language. For 'tour' product only. Part of the tourcity_arr array.
                    no_of_nights:
                      type: string
                      example: '1'
                      description: Number of nights stayed in a tour city. For 'tour' product only. Part of the tourcity_arr array.
                      
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

