airbnb Calendar API

openapi: 3.2.0
info:
  title: Airbnb Homes Calendar API
  description: The Airbnb Homes API provides approved connectivity partners with programmatic access to manage vacation rental listings on the Airbnb platform.
  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: Calendar
  description: Operations for managing listing availability, pricing, and calendar synchronization across platforms.
paths:
  /listings/{listing_id}/calendar:
    get:
      operationId: getListingCalendar
      summary: Get Listing Calendar
      description: Retrieves the availability calendar for a specific listing over a date range. Returns day-by-day availability status, nightly pricing, minimum stay requirements, and any blocked dates.
      tags:
      - Calendar
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      - name: start_date
        in: query
        required: true
        description: The start date for the calendar range in ISO 8601 format.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        required: true
        description: The end date for the calendar range in ISO 8601 format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: The calendar data for the specified date range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  calendar_days:
                    type: array
                    items:
                      $ref: '#/components/schemas/CalendarDay'
        '400':
          description: The date range is invalid or missing.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
    put:
      operationId: updateListingCalendar
      summary: Update Listing Calendar
      description: Updates the availability, pricing, and minimum stay settings for specific dates on a listing calendar. Use this endpoint to block or unblock dates, adjust nightly pricing, and set minimum stay requirements.
      tags:
      - Calendar
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - calendar_operations
              properties:
                calendar_operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/CalendarOperation'
      responses:
        '200':
          description: The calendar was successfully updated.
        '400':
          description: The request body contains invalid operations.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
components:
  schemas:
    CalendarOperation:
      type: object
      required:
      - start_date
      - end_date
      properties:
        start_date:
          type: string
          format: date
          description: The start date of the range to update.
        end_date:
          type: string
          format: date
          description: The end date of the range to update.
        available:
          type: boolean
          description: Whether the dates should be available or blocked.
        price:
          type: number
          format: double
          description: The nightly price to set for this date range.
          minimum: 0
        minimum_nights:
          type: integer
          description: The minimum number of nights required for stays in this range.
          minimum: 1
        maximum_nights:
          type: integer
          description: The maximum number of nights allowed for stays in this range.
    CalendarDay:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date for this calendar entry.
        available:
          type: boolean
          description: Whether the listing is available for booking on this date.
        price:
          type: number
          format: double
          description: The nightly price for this date in the listing currency.
        minimum_nights:
          type: integer
          description: The minimum number of nights required for a stay starting on this date.
          minimum: 1
        maximum_nights:
          type: integer
          description: The maximum number of nights allowed for a stay starting on this date.
        reservation_id:
          type: string
          description: The reservation identifier if this date is booked.
  parameters:
    listingIdParam:
      name: listing_id
      in: path
      required: true
      description: The unique identifier of the listing.
      schema:
        type: string
  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. Access tokens expire after 24 hours and must be refreshed.
      flows:
        authorizationCode:
          authorizationUrl: https://www.airbnb.com/oauth2/auth
          tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
          scopes:
            listings:read: Read listing information
            listings:write: Create and update listings
            reservations:read: Read reservation information
            reservations:write: Accept, deny, and cancel reservations
            messages:read: Read reservation messages
            messages:write: Send messages to guests
            reviews:read: Read reviews
            calendar:read: Read calendar availability
            calendar:write: Update calendar availability and pricing
externalDocs:
  description: Airbnb Developer Documentation
  url: https://developer.withairbnb.com/