Rillet Journal Entries API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Journal Entries 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: Journal Entries
paths:
  /journal-entries:
    post:
      tags:
      - Journal Entries
      operationId: create-a-journal-entry
      summary: Creates a journal entry
      description: 'Posts a balanced manual journal entry with explicit debit and credit lines, posting date, and subsidiary scope for GL corrections.

        Prefer dedicated AR or AP APIs when the business event already exists; reserve this for adjustments your automation cannot model yet.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJournalEntryRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JournalEntry'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters: []
    get:
      tags:
      - Journal Entries
      operationId: list-all-journal-entries
      summary: Lists all journal entries
      description: 'Returns GL journal entries with rich filtering (subsidiary, account, date range, reconciliation state).

        Use entry ids with retrieve-a-journal-entry before attempting updates or deletes.

        '
      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/JournalEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /journal-entries/{journal_entry_id}:
    get:
      tags:
      - Journal Entries
      operationId: retrieve-a-journal-entry
      summary: Retrieves a journal entry
      description: 'Retrieves a journal entry with every line, account reference, and reconciliation flag needed for close review or downstream edits.

        Call before update-a-journal-entry so you can merge new edits with existing lines without accidentally dropping balances.

        '
      parameters:
      - name: journal_entry_id
        in: path
        description: UUID of the journal entry to be used in this operation.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JournalEntry'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Journal Entries
      operationId: update-a-journal-entry
      summary: Updates a journal entry
      description: 'Replaces the lines and header metadata on an existing manual journal entry, subject to the same balancing rules as creation.

        Always include the complete line list retrieved beforehand because partial payloads can clear fields the API treats as optional.

        '
      parameters:
      - name: journal_entry_id
        in: path
        description: UUID of the journal entry to be used in this operation.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateJournalEntryRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JournalEntry'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Journal Entries
      operationId: delete-a-journal-entry
      summary: Deletes a journal entry
      description: 'Deletes a manual journal entry that should be excluded from the ledger, typically prior to period lock while corrections remain allowed.

        Verify dependent reconciliations or downstream consolidations no longer rely on the entry before removal.

        '
      parameters:
      - name: journal_entry_id
        in: path
        description: UUID of the journal entry to be used in this operation.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    JournalEntryItem:
      type: object
      required:
      - id
      - amount
      - account_id
      - account_code
      - side
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        original_transaction_amount:
          allOf:
          - $ref: '#/components/schemas/RoundedMonetaryAmount'
          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.
        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'
    Pagination:
      type: object
      properties:
        next_cursor:
          $ref: '#/components/schemas/PageCursor'
    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.
    JournalEntryRelatedEntity:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - CUSTOMER
          - VENDOR
    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
    ExchangeRate:
      type: object
      required:
      - base
      - date
      - rate
      - target
      properties:
        base:
          $ref: '#/components/schemas/CurrencyCode'
        target:
          $ref: '#/components/schemas/CurrencyCode'
        rate:
          type: string
        date:
          type: string
          format: date
    PageLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    PageCursor:
      type: string
      description: If defined, a cursor to retrieve the next page.
      example: iLQvkEj3sh3UiweC
    JournalEntry:
      type: object
      required:
      - id
      - date
      - name
      - currency
      - items
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        subsidiary_id:
          type: string
          format: uuid
        name:
          type: string
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        related_entity:
          $ref: '#/components/schemas/JournalEntryRelatedEntity'
        items:
          type: array
          minItems: 2
          items:
            $ref: '#/components/schemas/JournalEntryItem'
        date:
          type: string
          format: date
          description: The date this journal entry was posted to the general ledger.
        reversal_date:
          type: string
          format: date
        attachmentUrl:
          type: string
          format: uri
        exchange_rate:
          $ref: '#/components/schemas/ExchangeRate'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp in UTC timezone (must end with 'Z')
    AccountCode:
      type: string
      description: The account code found in the Chart of Accounts
      example: '11112'
    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'
    JournalEntryItemRequest:
      type: object
      required:
      - amount
      - account_code
      - side
      properties:
        description:
          type: string
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        account_code:
          $ref: '#/components/schemas/AccountCode'
        side:
          type: string
          enum:
          - DEBIT
          - CREDIT
        fields:
          $ref: '#/components/schemas/FieldAssignments'
        vat_code:
          type: string
          description: Code or description of an existing VAT rate for the journal entry subsidiary's country. When provided, vat_type is required. VAT is always treated as inclusive.
        vat_type:
          type: string
          description: VAT reporting type for this journal entry line. Required when vat_code is provided. Accepts Revenue, Revenues, Expense, or Expenses case-insensitively.
    CreateJournalEntryRequest:
      allOf:
      - $ref: '#/components/schemas/UpdateJournalEntryRequest'
      - type: object
        required:
        - date
        - name
        - currency
        - items
        properties:
          subsidiary_id:
            type: string
            format: uuid
          related_entity:
            $ref: '#/components/schemas/JournalEntryRelatedEntity'
    UpdateJournalEntryRequest:
      type: object
      required:
      - date
      - name
      - currency
      - items
      properties:
        name:
          type: string
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        items:
          type: array
          minItems: 2
          items:
            $ref: '#/components/schemas/JournalEntryItemRequest'
        date:
          type: string
          format: date
        reversal_date:
          type: string
          format: date
        attachmentUrl:
          type: string
          format: uri
        exchange_rate:
          $ref: '#/components/schemas/ExchangeRate'
    CurrencyCode:
      type: string
      description: Currency code following ISO-4217
      example: USD
  parameters:
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of rows to return in the page.
      schema:
        $ref: '#/components/schemas/PageLimit'
    subsidiary_id:
      name: subsidiary_id
      in: query
      required: false
      description: Subsidiary to be used when filtering data
      schema:
        type: string
        format: uuid
    cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor to navigate through the full response.
      schema:
        $ref: '#/components/schemas/PageCursor'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-mcp-ready: true
x-readme:
  headers:
  - key: X-Rillet-API-Version
    value: '4'