Rillet Reimbursements API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Reimbursements 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: Reimbursements
paths:
  /reimbursements:
    post:
      tags:
      - Reimbursements
      operationId: create-a-reimbursement
      summary: Create a reimbursement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReimbursementRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reimbursement'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters: []
    get:
      tags:
      - Reimbursements
      operationId: list-all-reimbursements
      summary: Lists all reimbursements
      description: 'Surfaces reimbursement requests created from approved charges or manual submissions, including subsidiary and freshness filters for payroll sync.

        Use pagination cursors for large populations and pair with retrieve-a-reimbursement when a row needs detailed audit context.

        '
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/subsidiary_id'
      - name: updated.gt
        in: query
        required: false
        description: Filter reimbursements updated after this timestamp
        schema:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - reimbursements
                - pagination
                properties:
                  reimbursements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reimbursement'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /reimbursements/{reimbursement_id}:
    get:
      tags:
      - Reimbursements
      operationId: retrieve-a-reimbursement
      summary: Retrieves a reimbursement
      description: 'Returns the full reimbursement packet with employee linkage, funding instructions, and approval history for a single id.

        Helpful when validating totals before releasing ACH batches or answering employee support tickets.

        '
      parameters:
      - name: reimbursement_id
        in: path
        description: UUID of the reimbursement to be used in this operation.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reimbursement'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Reimbursements
      operationId: delete-a-reimbursement
      summary: Deletes a reimbursement
      description: 'Removes a reimbursement that was created prematurely or duplicated during intake so it no longer blocks payroll totals.

        Confirm no outbound payments or GL accruals were posted against the reimbursement before deleting it.

        '
      parameters:
      - name: reimbursement_id
        in: path
        description: UUID of the reimbursement 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:
    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
    CreateReimbursementRequest:
      type: object
      required:
      - vendor_id
      - items
      - reimbursement_date
      - payable_account_code
      properties:
        vendor_id:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreateReimbursementItemRequest'
        reimbursement_date:
          type: string
          format: date
        payable_account_code:
          $ref: '#/components/schemas/AccountCode'
        impact_date:
          type: string
          format: date
          description: GL impact date. Defaults to reimbursement_date if omitted.
        subsidiary_id:
          type: string
          format: uuid
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    ReimbursementItemRequest:
      type: object
      required:
      - account_code
      - amount
      properties:
        description:
          type: string
          example: API Reimbursement
        account_code:
          $ref: '#/components/schemas/AccountCode'
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        tax_rate:
          $ref: '#/components/schemas/ExpenseTaxRate'
        service_period:
          $ref: '#/components/schemas/CalendarPeriod'
        fields:
          $ref: '#/components/schemas/FieldAssignments'
    ReimbursementItem:
      allOf:
      - $ref: '#/components/schemas/ReimbursementItemRequest'
      - type: object
        required:
        - id
        properties:
          id:
            type: string
            format: uuid
    AccountCode:
      type: string
      description: The account code found in the Chart of Accounts
      example: '11112'
    ExternalReference:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          example: xyzSystemId
        id:
          type: string
          example: '234'
        url:
          type: string
          format: uri
          example: https://xyzsystempage.com/ids/234
      description: For requests, only pre-defined custom IDs are accepted. In responses, an object imported through an integration (e.g. Stripe) would return the provider's object ID.
    ReimbursementRequest:
      type: object
      required:
      - vendor_id
      - items
      - bill_date
      properties:
        vendor_id:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ReimbursementItemRequest'
        reimbursement_date:
          type: string
          format: date
        impact_date:
          type: string
          format: date
        subsidiary_id:
          type: string
          format: uuid
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        exchange_rate:
          $ref: '#/components/schemas/ExchangeRate'
    TaxRate:
      allOf:
      - $ref: '#/components/schemas/TaxRateWithOptionalAmount'
      required:
      - tax_amount
    Reimbursement:
      allOf:
      - $ref: '#/components/schemas/ReimbursementRequest'
      - type: object
        required:
        - id
        - status
        - updated_at
        properties:
          id:
            type: string
            format: uuid
          status:
            $ref: '#/components/schemas/ReimbursementStatus'
          updated_at:
            type: string
            format: date-time
            description: Timestamp when the reimbursement was last modified
          items:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/ReimbursementItem'
    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.
    PageCursor:
      type: string
      description: If defined, a cursor to retrieve the next page.
      example: iLQvkEj3sh3UiweC
    PageLimit:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    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'
    ReimbursementStatus:
      type: string
      enum:
      - UNPAID
      - PAID
      - PARTIALLY_PAID
    CountryCode:
      type: string
      description: Two-letter country code (ISO 3166-1 alpha-2).
      example: US
    CurrencyCode:
      type: string
      description: Currency code following ISO-4217
      example: USD
    CalendarPeriod:
      type: object
      required:
      - end
      - start
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
    ExpenseTaxRate:
      allOf:
      - $ref: '#/components/schemas/TaxRate'
      - type: object
        required:
        - coverage
        properties:
          tax_code:
            type: string
            description: Code of a predefined tax rate. When provided, the rate's percentage, country, and description are used instead of the inline values.
          coverage:
            type: string
            enum:
            - INCLUSIVE
            - EXCLUSIVE
    CreateReimbursementItemRequest:
      type: object
      required:
      - account_code
      - amount
      properties:
        description:
          type: string
          example: Travel reimbursement
        account_code:
          $ref: '#/components/schemas/AccountCode'
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        tax_rate:
          $ref: '#/components/schemas/ExpenseTaxRate'
        service_period:
          $ref: '#/components/schemas/CalendarPeriod'
        fields:
          $ref: '#/components/schemas/FieldAssignments'
    TaxRateWithOptionalAmount:
      type: object
      required:
      - country
      - description
      - percentage
      - type
      properties:
        percentage:
          type: number
          minimum: 0
          maximum: 100
          example: 0
        tax_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        country:
          $ref: '#/components/schemas/CountryCode'
        type:
          type: string
          enum:
          - VAT
          - SALES_TAX
        description:
          type: string
    Pagination:
      type: object
      properties:
        next_cursor:
          $ref: '#/components/schemas/PageCursor'
  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'