Rillet Reports API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Reports API
  version: v4.0
servers:
- url: https://api.rillet.com
  description: Production server url
- url: https://sandbox.api.rillet.com
  description: Test server url
security:
- bearerAuth: []
tags:
- name: Reports
paths:
  /reports/arr-waterfall:
    get:
      tags:
      - Reports
      operationId: retrieve-waterfall-report
      summary: Retrieves ARR waterfall report
      description: 'Returns the ARR waterfall dataset for the requested month with optional breakdown dimensions, subsidiary filters, and pagination cursors for large tenants.

        Finance teams use this to explain beginning ARR, new business, expansion, contraction, and churn between periods.

        '
      parameters:
      - $ref: '#/components/parameters/month'
      - $ref: '#/components/parameters/status'
      - $ref: '#/components/parameters/breakdown'
      - $ref: '#/components/parameters/subsidiary_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevenueWaterfall'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/trial-balance:
    get:
      tags:
      - Reports
      operationId: retrieve-trial-balance-report
      summary: Retrieves trial balance report
      description: 'Returns a trial balance report for the specified date range.

        Required parameters: from_date and to_date (ISO-8601 format YYYY-MM-DD). Both must be provided or the call will fail.

        Example: from_date=2024-01-01, to_date=2024-12-31.

        '
      parameters:
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/toDate'
      - $ref: '#/components/parameters/subsidiary_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialBalanceReport'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/balance-sheet:
    get:
      tags:
      - Reports
      operationId: retrieve-balance-sheet-report
      summary: Retrieves balance sheet report
      description: 'Returns a balance sheet report as of the specified date.

        Required parameter: as_of_date (ISO-8601 format YYYY-MM-DD). Must be provided or the call will fail.

        Example: as_of_date=2024-12-31.

        '
      parameters:
      - $ref: '#/components/parameters/asOfDate'
      - $ref: '#/components/parameters/subsidiary_id'
      - $ref: '#/components/parameters/breakdownBy'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSheetReport'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/income-statement:
    get:
      tags:
      - Reports
      operationId: retrieve-income-statement-report
      summary: Retrieves income statement report
      description: Returns an income statement (profit and loss) report for the specified date range.
      parameters:
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/toDate'
      - $ref: '#/components/parameters/subsidiary_id'
      - $ref: '#/components/parameters/breakdownBy'
      - $ref: '#/components/parameters/customFieldId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeStatementReport'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/cash-flow-statement:
    get:
      tags:
      - Reports
      operationId: retrieve-cash-flow-statement-report
      summary: Retrieves cash flow statement report
      description: Returns a cash flow statement report for the specified date range.
      parameters:
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/toDate'
      - $ref: '#/components/parameters/subsidiary_id'
      - $ref: '#/components/parameters/breakdownBy'
      - $ref: '#/components/parameters/customFieldId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashFlowStatementReport'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/executive-pl:
    get:
      tags:
      - Reports
      operationId: retrieve-executive-pl-report
      summary: Retrieves executive P&L report
      description: Returns an executive profit and loss report with margins for the specified date range.
      parameters:
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/toDate'
      - $ref: '#/components/parameters/subsidiary_id'
      - $ref: '#/components/parameters/breakdownBy'
      - $ref: '#/components/parameters/customFieldId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutivePLReport'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reports/journal-entries:
    get:
      tags:
      - Reports
      operationId: list-reports-journal-entries
      summary: Lists journal entries with reporting currency amounts
      description: Returns journal entries with line item amounts converted to the reporting currency.
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/subsidiary_id'
      - name: updated.gt
        in: query
        required: false
        description: Filter journal entries updated after this timestamp
        schema:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
      - name: date.gte
        in: query
        required: false
        description: Filter journal entries with a posting date on or after this date (inclusive)
        schema:
          type: string
          format: date
          example: '2023-12-01'
      - name: date.lte
        in: query
        required: false
        description: Filter journal entries with a posting date on or before this date (inclusive)
        schema:
          type: string
          format: date
          example: '2023-12-31'
      - name: account_ids
        in: query
        required: false
        description: Filter journal entries that have at least one line item posting to any of these account ids (comma-separated)
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: false
        example:
        - 11111111-1111-1111-1111-111111111111
        - 22222222-2222-2222-2222-222222222222
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - updated
          default: created
        description: the field the journal entries should be sorted by descending (either created or updated)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - journal_entries
                type: object
                properties:
                  journal_entries:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportingJournalEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Revenue:
      type: object
      required:
      - year_month
      - amount
      properties:
        year_month:
          type: string
          description: Year and month for the requested report for this revenue total
          format: yearMonth
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
    Breakdown:
      type: string
      enum:
      - ARR
      - MRR
    FieldAssignments:
      type: array
      items:
        type: object
        required:
        - field_id
        - field_value_id
        properties:
          field_id:
            type: string
            format: uuid
          field_value_id:
            type: string
            format: uuid
    CashFlowItem:
      type: object
      required:
      - name
      - amounts
      properties:
        name:
          type: string
          example: Net Income
        amounts:
          type: array
          description: Amounts, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
    ExecutivePLItem:
      type: object
      required:
      - name
      - code
      - amounts
      properties:
        name:
          type: string
          example: Product Revenue
        code:
          type: string
          example: '4210'
        amounts:
          type: array
          description: Item amounts, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
    AccountCode:
      type: string
      description: The account code found in the Chart of Accounts
      example: '11112'
    ReportBreakdown:
      type: object
      description: Describes a breakdown column in the report (subsidiary or custom field)
      required:
      - type
      - name
      properties:
        type:
          type: string
          enum:
          - SUBSIDIARY
          - CUSTOM_FIELD
          - PERIOD
          description: The type of breakdown
        name:
          type: string
          description: Display name for this breakdown column
          example: Acme Corp US
        id:
          type: string
          format: uuid
          description: The ID of the subsidiary or custom field value (if applicable)
    RevenueWaterfall:
      type: object
      required:
      - customers
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/CustomerRevenue'
        pagination:
          $ref: '#/components/schemas/Pagination'
    NamedCashFlowSection:
      type: object
      description: A named cash flow section containing line items with totals per breakdown
      required:
      - name
      - totals
      - items
      properties:
        name:
          type: string
          description: The name of this section
          example: Operating Cash Flow
        totals:
          type: array
          description: Section totals, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        items:
          type: array
          items:
            $ref: '#/components/schemas/CashFlowItem'
    ReportingJournalEntryItem:
      type: object
      required:
      - id
      - local_amount
      - reporting_amount
      - account_id
      - account_code
      - side
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        local_amount:
          $ref: '#/components/schemas/MonetaryAmount'
        reporting_amount:
          $ref: '#/components/schemas/MonetaryAmount'
        original_transaction_amount:
          allOf:
          - $ref: '#/components/schemas/MonetaryAmount'
          nullable: true
          description: The line amount in its original transaction currency, when the line was booked in a currency other than the entry currency. Null otherwise.
        exchange_rate:
          type: string
          description: The exchange rate used to convert the amount to reporting currency
        account_id:
          type: string
          format: uuid
          description: Immutable account identifier.
        account_code:
          $ref: '#/components/schemas/AccountCode'
        side:
          type: string
          enum:
          - DEBIT
          - CREDIT
        fields:
          $ref: '#/components/schemas/FieldAssignments'
    ExecutivePLReport:
      type: object
      required:
      - period
      - currency
      - breakdowns
      - sections
      - summaries
      properties:
        period:
          $ref: '#/components/schemas/ReportPeriod'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        breakdowns:
          type: array
          description: The breakdown columns for this report. When no breakdown_by is specified, this contains a single PERIOD entry representing the total.
          items:
            $ref: '#/components/schemas/ReportBreakdown'
        sections:
          type: array
          description: The sections of the executive P&L (e.g., Revenue, Cost of Goods Sold, Operating Expenses, Non-Operating)
          items:
            $ref: '#/components/schemas/NamedExecutivePLSection'
        summaries:
          type: array
          description: Summary line items with optional margins (e.g., Gross Profit, Net Income)
          items:
            $ref: '#/components/schemas/ReportSummaryLine'
    NamedReportSection:
      type: object
      description: A named section containing account groups with a total
      required:
      - name
      - totals
      - groups
      properties:
        name:
          type: string
          description: The name of this section
          example: Assets
        totals:
          type: array
          description: Section totals, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountGroup'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountEntry'
    ReportBreakdownBy:
      type: string
      description: How to break down the report columns. If not specified, returns a single total column.
      enum:
      - SUBSIDIARY
      - CUSTOM_FIELD
    ReportPeriod:
      type: object
      required:
      - from_date
      - to_date
      properties:
        from_date:
          type: string
          format: date
          description: Start date of the report period
          example: '2024-01-01'
        to_date:
          type: string
          format: date
          description: End date of the report period
          example: '2024-01-31'
    ReportSummaryLine:
      type: object
      description: A named summary line item (e.g., gross profit, net income)
      required:
      - name
      - amounts
      properties:
        name:
          type: string
          description: The name of this summary line
          example: Gross Profit
        amounts:
          type: array
          description: Summary amounts, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        margins:
          type: array
          description: Optional margins as percentages (0.0 to 1.0), one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownMargin'
    CustomerRevenue:
      type: object
      required:
      - id
      - name
      - totals
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        total:
          $ref: '#/components/schemas/Revenue'
    ReportAccountGroupNested:
      type: object
      required:
      - name
      - totals
      - accounts
      properties:
        name:
          type: string
          example: Current Assets
        totals:
          type: array
          description: Group totals, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountEntry'
    ReportingJournalEntry:
      type: object
      required:
      - id
      - date
      - name
      - items
      - subsidiary_id
      properties:
        id:
          type: string
          format: uuid
        subsidiary_id:
          type: string
          format: uuid
        name:
          type: string
        related_entity:
          $ref: '#/components/schemas/JournalEntryRelatedEntity'
        items:
          type: array
          minItems: 2
          items:
            $ref: '#/components/schemas/ReportingJournalEntryItem'
        date:
          type: string
          format: date
        reversal_date:
          type: string
          format: date
        attachmentUrl:
          type: string
          format: uri
    Error:
      type: object
      required:
      - type
      - title
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the error type.
          example: https://rillet.io/forbidden
        title:
          type: string
          description: Summary of the problem.
          example: Forbidden
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the error.
          example: 403
        detail:
          type: string
          description: Explanation specific to this occurrence of the error.
          example: User does not have rights to perform this operation.
    MonetaryAmount:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          description: Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.)
          example: '1.01'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
    ReportAccountBalance:
      type: object
      required:
      - id
      - code
      - name
      - beginning_balance
      - debit_total
      - credit_total
      - ending_balance
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          example: '1000'
        name:
          type: string
          example: Cash
        beginning_balance:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        debit_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        credit_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        debit_fx_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
          description: Foreign exchange adjustment for debits
        credit_fx_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
          description: Foreign exchange adjustment for credits
        ending_balance:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
    BalanceSheetReport:
      type: object
      required:
      - as_of_date
      - currency
      - sections
      properties:
        as_of_date:
          type: string
          format: date
          description: The date of the balance sheet
          example: '2024-01-31'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        breakdowns:
          type: array
          description: The breakdown columns for this report. When no breakdown_by is specified, this contains a single PERIOD entry representing the total.
          items:
            $ref: '#/components/schemas/ReportBreakdown'
        sections:
          type: array
          description: The sections of the balance sheet (e.g., Assets, Liabilities, Equity)
          items:
            $ref: '#/components/schemas/NamedReportSection'
    PageCursor:
      type: string
      description: If defined, a cursor to retrieve the next page.
      example: iLQvkEj3sh3UiweC
    PageLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    ReportTotals:
      type: object
      required:
      - beginning_balance
      - debit_total
      - credit_total
      - ending_balance
      properties:
        beginning_balance:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        debit_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        credit_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        debit_fx_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
          description: Foreign exchange adjustment for debits
        credit_fx_total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
          description: Foreign exchange adjustment for credits
        ending_balance:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
    IncomeStatementReport:
      type: object
      required:
      - period
      - currency
      - breakdowns
      - sections
      - summaries
      properties:
        period:
          $ref: '#/components/schemas/ReportPeriod'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        breakdowns:
          type: array
          description: The breakdown columns for this report. When no breakdown_by is specified, this contains a single PERIOD entry representing the total.
          items:
            $ref: '#/components/schemas/ReportBreakdown'
        sections:
          type: array
          description: The sections of the income statement (e.g., Revenue, Cost of Goods Sold, Operating Expenses, Non-Operating)
          items:
            $ref: '#/components/schemas/NamedReportSection'
        summaries:
          type: array
          description: Summary line items (e.g., Gross Profit, Net Income)
          items:
            $ref: '#/components/schemas/ReportSummaryLine'
    Status:
      type: string
      enum:
      - ACTIVE
      - COMMITTED
    RoundedMonetaryAmount:
      type: object
      description: A monetary amount that must be rounded to the currency's default decimal places (e.g., 2 decimal places for USD).
      x-class-extra-annotation: '@io.rillet.common.infra.validators.IsRoundedAmount'
      required:
      - amount
      - currency
      properties:
        amount:
          type: string
          description: Monetary amount in decimal format, using a period (.) as the decimal separator. Must be rounded to the currency's default decimal places (e.g. '1.01' in USD represents 1 dollar and 1 cent).
          example: '1.01'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
    BreakdownBalance:
      type: object
      required:
      - breakdown_id
      - amount
      properties:
        breakdown_id:
          type: string
          format: uuid
          description: The ID of the breakdown this balance belongs to
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
    CurrencyCode:
      type: string
      description: Currency code following ISO-4217
      example: USD
    CashFlowStatementReport:
      type: object
      required:
      - period
      - currency
      - breakdowns
      - sections
      - summaries
      properties:
        period:
          $ref: '#/components/schemas/ReportPeriod'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        breakdowns:
          type: array
          description: The breakdown columns for this report. When no breakdown_by is specified, this contains a single PERIOD entry representing the total.
          items:
            $ref: '#/components/schemas/ReportBreakdown'
        sections:
          type: array
          description: The sections of the cash flow statement (e.g., Operating Cash Flow, Investing Cash Flow, Financing Cash Flow)
          items:
            $ref: '#/components/schemas/NamedCashFlowSection'
        summaries:
          type: array
          description: Summary line items (e.g., Net Change in Cash, Opening Balance, Closing Balance, FX Effect on Cash)
          items:
            $ref: '#/components/schemas/CashFlowItem'
    ReportAccountGroup:
      type: object
      required:
      - name
      - totals
      - accounts
      properties:
        name:
          type: string
          example: Current Assets
        totals:
          type: array
          description: Group totals, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountEntry'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountGroupNested'
    JournalEntryRelatedEntity:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - CUSTOMER
          - VENDOR
    TrialBalanceReport:
      type: object
      required:
      - period
      - currency
      - accounts
      - totals
      properties:
        period:
          $ref: '#/components/schemas/ReportPeriod'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/ReportAccountBalance'
        totals:
          $ref: '#/components/schemas/ReportTotals'
    NamedExecutivePLSection:
      type: object
      description: A named executive P&L section containing line items with totals per breakdown
      required:
      - name
      - totals
      - items
      properties:
        name:
          type: string
          description: The name of this section
          example: Revenue
        totals:
          type: array
          description: Section totals, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExecutivePLItem'
    ReportAccountEntry:
      type: object
      required:
      - id
      - code
      - name
      - balances
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          example: '1000'
        name:
          type: string
          example: Cash
        balances:
          type: array
          description: Account balances, one per breakdown column.
          items:
            $ref: '#/components/schemas/BreakdownBalance'
    Pagination:
      type: object
      properties:
        next_cursor:
          $ref: '#/components/schemas/PageCursor'
    BreakdownMargin:
      type: object
      required:
      - breakdown_id
      - value
      properties:
        breakdown_id:
          type: string
          format: uuid
          description: The ID of the breakdown this margin belongs to
        value:
          type: number
          format: double
          description: Margin as a percentage (0.0 to 1.0)
  parameters:
    breakdown:
      name: breakdown
      in: query
      required: true
      description: whether annual or monthly breakdowns
      schema:
        $ref: '#/components/schemas/Breakdown'
    breakdownBy:
      name: breakdown_by
      in: query
      required: false
      description: How to break down the report columns. If not specified, returns a single total column.
      schema:
        $ref: '#/components/schemas/ReportBreakdownBy'
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of rows to return in the page.
      schema:
        $ref: '#/components/schemas/PageLimit'
    fromDate:
      name: from_date
      in: query
      required: true
      description: Start date for the report period. Uses ISO-8601 format (YYYY-MM-DD).
      schema:
        type: string
        format: date
      example: '2024-01-01'
    customFieldId:
      name: custom_field_id
      in: query
      required: false
      description: The ID of the custom field to break down by. Required when breakdown_by is CUSTOM_FIELD.
      schema:
        type: string
        format: uuid
    status:
      name: status
      in: query
      required: true
      description: whether to include committed or active entries
      schema:
        $ref: '#/components/schemas/Status'
    subsidiary_id:
      name: subsidiary_id
      in: query
      required: false
      description: Subsidiary to be used when filtering data
      schema:
        type: string
        format: uuid
    asOfDate:
      name: as_of_date
      in: query
      required: true
      description: The date for the point-in-time report. Uses ISO-8601 format (YYYY-MM-DD).
      schema:
        type: string
        format: date
      example: '2024-01-31'
    month:
      name: month
      in: query
      required: true
      description: The month and year to export. Uses ISO-8061 format (YYYY-MM).
      schema:
        type: string
        format: yearMonth
    cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor to navigate through the full response.
      schema:
        $ref: '#/components/schemas/PageCursor'
    toDate:
      name: to_date
      in: query
      required: true
      description: End date for the report period. Uses ISO-8601 format (YYYY-MM-DD).
      schema:
        type: string
        format: date
      example: '2024-01-31'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-mcp-ready: true
x-readme:
  headers:
  - key: X-Rillet-API-Version
    value: '4'