airbnb Reservations API

openapi: 3.1.0
info:
  title: Airbnb Activities Bookings Reservations API
  description: The Airbnb Activities API allows approved partners to integrate with Airbnb Experiences, the platform's marketplace for hosted activities and tours. It provides endpoints for managing experience listings, handling bookings, and synchronizing availability for activities offered by local hosts. Partners can use the API to build integrations that help experience hosts manage their offerings alongside other tour and activity platforms, enabling centralized management of schedules, pricing, and guest communications.
  version: 2025.03.31
  contact:
    name: Airbnb Developer Support
    url: https://developer.withairbnb.com/
  termsOfService: https://www.airbnb.com/terms
servers:
- url: https://api.airbnb.com/v2
  description: Airbnb Production API Server
security:
- oauth2: []
tags:
- name: Reservations
  description: Operations for managing reservations, including accepting, declining, and retrieving booking details.
paths:
  /reservations:
    get:
      operationId: listReservations
      summary: List Reservations
      description: Retrieves a paginated list of reservations for listings managed by the authenticated partner. Supports filtering by status, listing, and date range.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: Filter reservations by their current status.
        schema:
          type: string
          enum:
          - pending
          - accepted
          - denied
          - cancelled
          - checked_in
          - checked_out
      - name: listing_id
        in: query
        description: Filter reservations by listing identifier.
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter reservations with check-in dates on or after this date.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Filter reservations with check-in dates on or before this date.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A paginated list of reservations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reservations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reservation'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
  /reservations/{reservation_id}:
    get:
      operationId: getReservation
      summary: Get a Reservation
      description: Retrieves the full details of a specific reservation including guest information, dates, pricing breakdown, and current status.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      responses:
        '200':
          description: The reservation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
  /reservations/{reservation_id}/accept:
    post:
      operationId: acceptReservation
      summary: Accept a Reservation
      description: Accepts a pending reservation request. Once accepted, the reservation is confirmed and the calendar dates are blocked.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      responses:
        '200':
          description: The reservation was successfully accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation is not in a pending state.
  /reservations/{reservation_id}/deny:
    post:
      operationId: denyReservation
      summary: Deny a Reservation
      description: Denies a pending reservation request. A reason for denial may be provided to inform the guest.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: The reason for denying the reservation request.
      responses:
        '200':
          description: The reservation was successfully denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation is not in a pending state.
  /reservations/{reservation_id}/cancel:
    post:
      operationId: cancelReservation
      summary: Cancel a Reservation
      description: Cancels an accepted reservation. Cancellation policies and fees may apply depending on the listing configuration and timing.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: The reason for cancelling the reservation.
      responses:
        '200':
          description: The reservation was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation cannot be cancelled in its current state.
components:
  parameters:
    limitParam:
      name: limit
      in: query
      description: The maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    offsetParam:
      name: offset
      in: query
      description: The number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    reservationIdParam:
      name: reservation_id
      in: path
      required: true
      description: The unique identifier of the reservation.
      schema:
        type: string
  schemas:
    Guest:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the guest.
        first_name:
          type: string
          description: The first name of the guest.
        last_name:
          type: string
          description: The last name of the guest.
        phone:
          type: string
          description: The phone number of the guest, available after booking is confirmed.
        profile_picture_url:
          type: string
          format: uri
          description: The URL of the guest profile picture.
        verified:
          type: boolean
          description: Whether the guest has completed identity verification.
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: The total number of results available.
        limit:
          type: integer
          description: The number of results returned per page.
        offset:
          type: integer
          description: The current offset in the result set.
        has_more:
          type: boolean
          description: Whether more results are available beyond this page.
    Reservation:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the reservation.
        confirmation_code:
          type: string
          description: The human-readable confirmation code for the reservation.
        status:
          type: string
          description: The current status of the reservation.
          enum:
          - pending
          - accepted
          - denied
          - cancelled
          - checked_in
          - checked_out
        listing_id:
          type: string
          description: The identifier of the listing that was booked.
        guest:
          $ref: '#/components/schemas/Guest'
        check_in:
          type: string
          format: date
          description: The guest check-in date.
        check_out:
          type: string
          format: date
          description: The guest check-out date.
        nights:
          type: integer
          description: The total number of nights in the reservation.
          minimum: 1
        guests_count:
          type: integer
          description: The number of guests included in the reservation.
          minimum: 1
        total_price:
          type: number
          format: double
          description: The total price of the reservation in the listing currency.
        currency:
          type: string
          description: The ISO 4217 currency code for the reservation pricing.
          pattern: ^[A-Z]{3}$
        host_payout:
          type: number
          format: double
          description: The amount to be paid out to the host after fees.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the reservation was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the reservation was last updated.
  securitySchemes:
    oauth2:
      type: oauth2
      description: Airbnb uses OAuth 2.0 for authentication. Partners must register their application to receive a client ID and secret, then obtain access tokens through the authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://www.airbnb.com/oauth2/auth
          tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
          scopes:
            experiences:read: Read experience information
            experiences:write: Create and update experiences
            bookings:read: Read booking information
            bookings:write: Confirm and cancel bookings
            messages:read: Read booking messages
            messages:write: Send messages to guests
externalDocs:
  description: Airbnb Developer Documentation
  url: https://developer.withairbnb.com/