openapi: 3.0.1
info:
  title: Modern Treasury AccountCapability LedgerEntry API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: LedgerEntry
paths:
  /api/ledger_entries:
    get:
      summary: list ledger_entries
      tags:
      - LedgerEntry
      operationId: listLedgerEntries
      description: Get a list of all ledger entries.
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type: string
          nullable: true
        required: false
      - name: per_page
        in: query
        schema:
          type: integer
        required: false
      - $ref: '#/components/parameters/bulk_id'
      - name: ledger_account_id
        in: query
        schema:
          type: string
        required: false
      - name: ledger_transaction_id
        in: query
        schema:
          type: string
        required: false
      - name: ledger_account_payout_id
        in: query
        schema:
          type: string
        required: false
      - name: ledger_account_settlement_id
        in: query
        schema:
          type: string
        required: false
      - name: effective_date
        in: query
        schema:
          type: object
          additionalProperties:
            type: string
            format: date
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the transaction's effective date. Format YYYY-MM-DD
        explode: true
      - name: effective_at
        in: query
        schema:
          type: object
          additionalProperties:
            type: string
            format: date-time
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the transaction's effective time. Format ISO8601
        explode: true
      - name: updated_at
        in: query
        schema:
          type: object
          additionalProperties:
            type: string
            format: date-time
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the posted at timestamp. For example, for all times after Jan 1 2000 12:00 UTC, use updated_at%5Bgt%5D=2000-01-01T12:00:00Z.
        explode: true
      - name: as_of_lock_version
        in: query
        schema:
          type: integer
        required: false
        description: Shows all ledger entries that were present on a ledger account at a particular `lock_version`. You must also specify `ledger_account_id`.
      - name: ledger_account_lock_version
        in: query
        schema:
          type: object
          additionalProperties:
            type: integer
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by the lock_version of a ledger account. For example, for all entries created at or before before lock_version 1000 of a ledger account, use `ledger_account_lock_version%5Blte%5D=1000`.
        explode: true
      - name: ledger_account_category_id
        in: query
        schema:
          type: string
        required: false
        description: Get all ledger entries that match the direction specified. One of `credit`, `debit`.
      - name: ledger_account_statement_id
        in: query
        schema:
          type: string
        required: false
        description: Get all ledger entries that are included in the ledger account statement.
      - name: show_deleted
        in: query
        required: false
        description: If true, response will include ledger entries that were deleted. When you update a ledger transaction to specify a new set of entries, the previous entries are deleted.
        schema:
          type: boolean
      - name: direction
        in: query
        schema:
          type: string
          enum:
          - credit
          - debit
          _x-stainless-modelDefPath: $shared.transaction_direction
        required: false
        description: If true, response will include ledger entries that were deleted. When you update a ledger transaction to specify a new set of entries, the previous entries are deleted.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - posted
          - archived
        required: false
        description: Get all ledger entries that match the status specified. One of `pending`, `posted`, or `archived`. For multiple statuses, use `status[]=pending&status[]=posted`.
      - name: status[]
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - posted
            - archived
        required: false
        description: Get all ledger entries that match the status specified. One of `pending`, `posted`, or `archived`. For multiple statuses, use `status[]=pending&status[]=posted`.
        explode: true
      - name: order_by
        in: query
        schema:
          type: object
          properties:
            created_at:
              type: string
              enum:
              - asc
              - desc
            effective_at:
              type: string
              enum:
              - asc
              - desc
          additionalProperties: false
        style: deepObject
        required: false
        description: Order by `created_at` or `effective_at` in `asc` or `desc` order. For example, to order by `effective_at asc`, use `order_by%5Beffective_at%5D=asc`. Ordering by only one field at a time is supported.
        explode: true
      - name: amount
        in: query
        schema:
          type: object
          properties:
            gte:
              type: integer
            lte:
              type: integer
            gt:
              type: integer
            lt:
              type: integer
            eq:
              type: integer
        style: deepObject
        required: false
        description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to filter by amount.
        explode: true
      - name: show_balances
        in: query
        required: false
        description: If true, response will include the balances attached to the ledger entry. If there is no balance available, null will be returned instead.
        schema:
          type: boolean
      - $ref: '#/components/parameters/metadata_query'
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type: string
                nullable: true
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type: integer
                nullable: true
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ledger_entry'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/ledger_entries/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: id
      required: true
    patch:
      summary: update ledger_entry
      tags:
      - LedgerEntry
      operationId: updateLedgerEntry
      description: Update the details of a ledger entry.
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_entry'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ledger_entry_update_request'
    get:
      summary: get ledger_entry
      tags:
      - LedgerEntry
      operationId: getLedgerEntry
      description: Get details on a single ledger entry.
      security:
      - basic_auth: []
      parameters:
      - name: show_balances
        in: query
        required: false
        description: If true, response will include the balances attached to the ledger entry. If there is no balance available, null will be returned instead.
        schema:
          type: boolean
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_entry'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  parameters:
    bulk_id:
      name: id[]
      in: query
      style: form
      explode: true
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      required: false
      description: If you have specific IDs to retrieve in bulk, you can pass them as query parameters delimited with `id[]=`, for example `?id[]=123&id[]=abc`.
    metadata_query:
      name: metadata
      in: query
      schema:
        type: object
        additionalProperties:
          type: string
      style: deepObject
      explode: true
      required: false
      description: For example, if you want to query for records with metadata key `Type` and value `Loan`, the query would be `metadata%5BType%5D=Loan`. This encodes the query parameters.
  schemas:
    ledger_entry_update_request:
      type: object
      properties:
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
    error_message:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              enum:
              - parameter_invalid
              - parameter_missing
              - resource_not_found
              - not_found
              - forbidden
              - invalid_ip
              - invalid_key
              - header_invalid
              - expired_key
              - conflict
              - too_many_requests
            message:
              type: string
            parameter:
              type: string
      required:
      - errors
    ledger_balance:
      type: object
      properties:
        credits:
          type: integer
        debits:
          type: integer
        amount:
          type: integer
        currency:
          type: string
          description: The currency of the ledger account.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
      additionalProperties: false
      minProperties: 5
      required:
      - credits
      - debits
      - amount
      - currency
      - currency_exponent
    ledger_entry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000. Can be any integer up to 36 digits.
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `credit`, `debit`. Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that wire, rtp, and check payments will always be `credit`.
          _x-stainless-modelDefPath: $shared.transaction_direction
        status:
          type: string
          enum:
          - archived
          - pending
          - posted
          description: Equal to the state of the ledger transaction when the ledger entry was created. One of `pending`, `posted`, or `archived`.
        ledger_account_id:
          type: string
          format: uuid
          description: The ledger account that this ledger entry is associated with.
        ledger_account_lock_version:
          type: integer
          description: Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See our post about Designing the Ledgers API with Optimistic Locking for more details.
          nullable: true
        ledger_account_currency:
          type: string
          description: The currency of the ledger account.
        ledger_account_currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
        ledger_transaction_id:
          type: string
          description: The ledger transaction that this ledger entry is associated with.
        resulting_ledger_account_balances:
          $ref: '#/components/schemas/ledger_balances'
          description: The pending, posted, and available balances for this ledger entry's ledger account. The posted balance is the sum of all posted entries on the account. The pending balance is the sum of all pending and posted entries on the account. The available balance is the posted incoming entries minus the sum of the pending and posted outgoing amounts. Please see https://docs.moderntreasury.com/docs/transaction-status-and-balances for more details.
          nullable: true
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
      additionalProperties: false
      minProperties: 17
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - amount
      - effective_at
      - direction
      - status
      - ledger_account_id
      - ledger_account_lock_version
      - ledger_account_currency
      - ledger_account_currency_exponent
      - ledger_transaction_id
      - resulting_ledger_account_balances
      - metadata
    ledger_balances:
      type: object
      properties:
        pending_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The pending_balance is the sum of all pending and posted entries.
        posted_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The posted_balance is the sum of all posted entries.
        available_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The available_balance is the sum of all posted inbound entries and pending outbound entries. For credit normal, available_amount = posted_credits - pending_debits; for debit normal, available_amount = posted_debits - pending_credits.
      additionalProperties: false
      minProperties: 3
      required:
      - pending_balance
      - posted_balance
      - available_balance
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic