openapi: 3.2.0
info:
  title: Payments Reservation breakdown API
  description: Retrieve payment and payout details for accommodation reservations, including partner payout information, breakdowns, bank transfer details, and VCC management.
  contact:
    name: Connectivity Team
    url: https://connect.booking.com
    email: connectivity@booking.com
  version: '1.0'
servers:
- url: https://payments-api.booking.com/
  description: Test using live endpoint
tags:
- name: Reservation breakdown
  description: Retrieve detailed breakdown for accommodation reservations with respect to partner payout.
paths:
  /connectivity-payments/reservations/{reservation-id}/breakdown:
    get:
      tags:
      - Reservation breakdown
      summary: Get price breakdown for a reservation
      description: Retrieve a detailed price breakdown for a given reservation, including VAT, applicable taxes, and fees, per each room the guest booked.
      operationId: getPriceBreakdown
      parameters:
      - name: Authorization
        in: header
        description: Bearer token for authentication.
        required: true
        schema:
          type: string
        example: Bearer <your_token>
      - name: reservation-id
        in: path
        description: The unique identifier of the reservation.
        required: true
        schema:
          type: integer
      - name: accept-version
        in: header
        description: API version to use.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved a detailed price breakdown for the reservation, including VAT, applicable taxes, and fees, per each room the guest booked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccommodationReservationPayoutBreakdownResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '401':
          description: Unauthorized. Missing or invalid authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTokenResponse'
        '403':
          description: Access Denied!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedRequestResponse'
        '404':
          description: The reservation data is not found at this moment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationDataNotFoundErrorResponse'
        '410':
          description: Reservation cannot be processed because the checkout date is older than the allowed 18-months window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutDateTooOldErrorResponse'
        '429':
          description: You exceeded the rate limit.
        '500':
          description: The request failed with an internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  schemas:
    Warning:
      type: object
      description: Warning information
      properties:
        message:
          type: string
          description: Warning message
          example: string
    AmountPaid:
      description: Contains information on the total amount the guest paid to Booking.com.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Amount paid by the guest.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    AmountCharges:
      description: Contains information on the total amount of all charges.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total amount of all charges.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    CheckoutDateTooOldErrorResponse:
      type: object
      description: Response when the checkout date is older than the allowed 18-months window
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    Error:
      type: object
      description: Error response containing details about the error
      properties:
        description:
          type: string
          description: Description of the error
        message:
          type: string
          description: Error message
        status_code:
          type: integer
          format: int32
          description: HTTP status code for the error
    UnauthorizedRequestResponse:
      type: object
      description: Response when the token is valid but does not have access to the requested resource.
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    InvalidTokenResponse:
      type: object
      description: Response when the authentication token is missing, invalid, or expired.
      properties:
        meta:
          $ref: '#/components/schemas/DefaultMeta'
        warnings:
          type: array
          description: List of warnings for the response
          maxItems: 0
          items: {}
        errors:
          type: array
          description: List of errors for the response
          items:
            type: object
            properties:
              message:
                type: string
                description: Error message
              code:
                type: string
                description: Error code
              details:
                type:
                - string
                - 'null'
                description: Additional error details
    AccommodationReservationPayoutBreakdownResponse:
      type: object
      description: Response of partner payout information with detailed breakdown for respective accommodation reservation
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          allOf:
          - $ref: '#/components/schemas/BreakdownResponse'
          description: The data
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    AmountPayout:
      description: Contains information on the total amount to be paid out to the partner.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total payout amount.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    InternalServerErrorResponse:
      type: object
      description: Response when the request failed with an internal reason
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    DefaultMeta:
      type: object
      description: Metadata for the response
      properties:
        ruid:
          type: string
          description: Request unique identifier
          example: string
    AmountToCollect:
      description: Contains information on the estimated amount the partner needs to collect from the guest at checkin.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Estimated amount to be collected from the guest at checkin.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
    ReservationDataNotFoundErrorResponse:
      type: object
      description: Response when the reservation data is not found
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    BreakdownResponse:
      type: object
      description: Detailed payout breakdown for a reservation
      properties:
        reservation_id:
          type: string
          description: Accommodation reservation identifier
        property_id:
          type: string
          description: Property identifier
        payout_type:
          type: string
          description: 'Type of payout: GROSS, NET, or UNKNOWN.'
        payment_tags:
          type: array
          description: Payment tags associated with the reservation.
          items:
            type: string
        total_price_of_reservation:
          type: object
          description: Breakdown of the total reservation price
          properties:
            total_amount_paid:
              $ref: '#/components/schemas/AmountPaid'
            total_amount_to_collect_at_property:
              $ref: '#/components/schemas/AmountToCollect'
        partner_payout:
          type: object
          description: Partner payout summary
          properties:
            total_payout:
              $ref: '#/components/schemas/AmountPayout'
            commissionable_price:
              $ref: '#/components/schemas/AmountCommissionable'
            commissions_and_charges:
              $ref: '#/components/schemas/AmountCommissionsAndCharges'
        price_breakdown:
          type: array
          description: Per-room price breakdown
          items:
            type: object
            properties:
              room_reservation_id:
                type: string
                description: Room reservation identifier
              charges:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      description: Charge type (e.g. Tax, COMMISSION)
                    amount:
                      $ref: '#/components/schemas/AmountCharges'
                    is_already_collected_from_guest:
                      type: string
                      description: If set to TRUE, the charged amount has already been collected from the guest and the partner does not need to collect anything. If set to FALSE, the partner has to collect the money at checkin. If set to UNKNOWN, no information is available.
                    is_included_total_partner_payout:
                      type: string
                      description: If set to TRUE, the charged amount is included in the payout and will be transferred to the partner. If set to FALSE, the charged amount is intended for another party, such as the government. If set to UNKNOWN, no information is available.
                    applicable_rate:
                      type:
                      - object
                      - 'null'
                      description: The rate applied to calculate the charge.
                      properties:
                        type:
                          type: string
                          description: How the rate is applied (e.g. PERCENTAGE).
                        value:
                          type: string
                          description: Rate value.
                        decimals:
                          type: integer
                          format: int32
                          description: Number of decimals in the rate value.
                    applicable_type:
                      type:
                      - array
                      - 'null'
                      description: The type of applicable rate.
                      items:
                        type: string
    AmountCommissionsAndCharges:
      description: Contains information on the total amount of commissions and other charges such as fees.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total amount of commissions and other charges.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
        breakdown:
          type: object
          description: Breakdown of commissions and charges.
          properties:
            total_commissions:
              type: object
              description: Total commission amount.
              properties:
                currency:
                  type: string
                  description: Currency of the amount.
                value:
                  type: string
                  description: Total commission amount.
                decimals:
                  type: integer
                  format: int32
                  description: Number of decimals in the amount.
            total_charges:
              type: object
              description: Total charges amount.
              properties:
                currency:
                  type: string
                  description: Currency of the amount.
                value:
                  type: string
                  description: Total charges amount.
                decimals:
                  type: integer
                  format: int32
                  description: Number of decimals in the amount.
    BadRequestErrorResponse:
      type: object
      description: Response when the request doesn't have valid parameters
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
          description: The meta
        data:
          type: object
          description: Data containing required information
        errors:
          type: array
          description: List of errors for the response
          items:
            $ref: '#/components/schemas/Error'
        warnings:
          type: array
          description: List of warnings for the response
          items:
            $ref: '#/components/schemas/Warning'
    AmountCommissionable:
      description: Contains information on the total commissionable price.
      properties:
        currency:
          type: string
          description: Currency of the amount.
        value:
          type: string
          description: Total commissionable price.
        decimals:
          type: integer
          format: int32
          description: Number of decimals in the amount.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for authentication. Use your API credentials to obtain a token.
x-tagGroups:
- name: API Endpoints
  tags:
  - Reservation payout details
  - Reservation breakdown
  - Bank transfer payout
  - VCC payout details, per accommodation reservation
  - VCCs to be charged
  - Refundable VCCs
  - Reservation Status API
- name: Documentation
  tags:
  - About Try it