Booking.com Reconciliation reports API

openapi: 3.2.0
info:
  title: Reconciliation reports API
  description: Generate and download financial reconciliation reports for your properties. Use the Reconciliation API to request payout reports for a specified date range and set of properties, check the report generation status, and retrieve the available filter and configuration options.
  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: Reconciliation reports
  description: Generate financial reconciliation reports for one or more properties.
paths:
  /connectivity-payments/recon-reports:
    post:
      tags:
      - Reconciliation reports
      summary: Generate a reconciliation report
      description: 'Initiates the asynchronous generation of a financial reconciliation report for one or more properties within a specified date range.


        The report is generated asynchronously. The response returns a `request_id` that you use to poll the report status endpoint until the `status` is `READY`, `EMPTY`, or `ERROR`. When ready, a pre-signed `download_url` and `filename` are returned for downloading the report. The `download_url` is valid for approximately 15 minutes (see `download_url_expires_at`). To obtain a new download URL after expiry, call this endpoint again to generate a new report. If `status` is `EMPTY` or `ERROR`, stop polling; no report is available for download.


        Use the report filters endpoint to retrieve the available `report_configurations` and `report_filters` values before generating a report.


        **Connection type**: Reservations connection type is required to access this endpoint.


        This endpoint is rate-limited to 10 requests per minute.'
      operationId: generateReconReport
      parameters:
      - name: Authorization
        in: header
        description: Bearer token for authentication.
        required: true
        schema:
          type: string
        example: Bearer <your_token>
      - name: accept-version
        in: header
        description: API version to use.
        required: false
        schema:
          type: string
          default: '1.0'
        example: '1.0'
      requestBody:
        description: Parameters for the reconciliation report to generate, including target properties, date range, output format, and optional filters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconReportRequest'
        required: true
      responses:
        '202':
          description: Report generation request accepted. Use the returned `request_id` with the report status endpoint to check progress and retrieve the download URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconReportGenerationResponse'
        '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'
        '429':
          description: Too many requests. Rate limiting is enforced.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying.
              schema:
                type: integer
                format: int32
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '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
    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'
        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'
    RateLimitErrorResponse:
      type: object
      description: Response when the rate limit has been exceeded
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
        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
        debug_message:
          type: string
          description: Detailed debug message for the error
    PropertySelection:
      type: object
      description: A legal entity and its associated property IDs to include in the reconciliation report.
      required:
      - legal_entity_id
      - property_ids
      properties:
        legal_entity_id:
          type: string
          description: The legal entity identifier.
          example: '1234567'
        property_ids:
          type: array
          description: List of property IDs belonging to the legal entity to include in the report.
          items:
            type: string
          example:
          - '123456'
    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
    InternalServerErrorResponse:
      type: object
      description: Response when the request failed with an internal reason
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
        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
    ReportFilterInput:
      type: object
      description: A single report filter with one or more selected values. Use the [report filters endpoint](#tag/Report-filters) to retrieve available `filter_key` and `filter_values` options.
      required:
      - filter_key
      - filter_values
      properties:
        filter_key:
          type: string
          description: 'The filter key. Possible values: `bank_accounts`, `payout_type`, `statement_descriptor`.'
          example: bank_accounts
        filter_values:
          type: array
          description: The selected filter values for the given `filter_key`.
          items:
            type: string
          example:
          - DE123456789
    ReportConfigurationInput:
      type: object
      description: A single report configuration key-value pair. Use the [report filters endpoint](#tag/Report-filters) to retrieve available `config_key` and `config_value` options.
      required:
      - config_key
      - config_value
      properties:
        config_key:
          type: string
          description: 'The configuration key. Possible values: `format_type`, `locale`.'
          example: format_type
        config_value:
          type: string
          description: The selected configuration value for the given `config_key`. For example, `CSV`, `XLS`, or `JSON` for `format_type`.
          example: CSV
    ReconReportGenerationResponse:
      type: object
      description: Response returned when a reconciliation report generation request is accepted.
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
        data:
          allOf:
          - $ref: '#/components/schemas/ReconReportGenerationData'
        errors:
          type: array
          maxItems: 0
          items: {}
        warnings:
          type: array
          maxItems: 0
          items: {}
    ReconReportGenerationData:
      type: object
      description: Data returned when a reconciliation report generation request is accepted.
      properties:
        request_id:
          type: string
          description: Unique identifier for the report generation request. Use this value to poll the report status endpoint.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        report_status:
          type: string
          description: 'Current status of the report generation. Possible values: `GENERATING`.'
          example: GENERATING
    ReconReportRequest:
      type: object
      description: Request body for generating a reconciliation report.
      required:
      - properties
      - from_date
      - to_date
      properties:
        properties:
          type: array
          description: List of legal entities and their associated property IDs to include in the report.
          items:
            $ref: '#/components/schemas/PropertySelection'
        from_date:
          type: string
          format: date
          description: Start date of the reporting period (inclusive), in `YYYY-MM-DD` format.
          example: '2025-04-01'
        to_date:
          type: string
          format: date
          description: End date of the reporting period (inclusive), in `YYYY-MM-DD` format.
          example: '2025-08-01'
        report_configurations:
          type: array
          description: Optional list of report configuration options, such as output format and locale. Use the [report filters endpoint](#tag/Report-filters) to retrieve available options.
          items:
            $ref: '#/components/schemas/ReportConfigurationInput'
        report_filters:
          type: array
          description: Optional list of filters to narrow down the report data, such as specific bank accounts or payout types. Use the [report filters endpoint](#tag/Report-filters) to retrieve available options.
          items:
            $ref: '#/components/schemas/ReportFilterInput'
    BadRequestErrorResponse:
      type: object
      description: Response when the request doesn't have valid parameters
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/DefaultMeta'
        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'
  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:
  - Reconciliation reports
  - Report status
  - Report filters
- name: Documentation
  tags:
  - About Try it