Rillet Credit Memos API

openapi: 3.1.0
info:
  title: Rillet Accounting API Key Credit Memos 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: Credit Memos
paths:
  /credit-memos:
    get:
      tags:
      - Credit Memos
      operationId: list-all-credit-memos
      summary: Lists all credit memos
      description: 'Returns customer credit memos with pagination and filters for application state, customer, and subsidiaries.

        Use credit memo ids with retrieve-a-credit-memo before updates or when applying credits to invoices.

        '
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/subsidiary_id'
      - name: updated.gt
        in: query
        required: false
        description: Filter credit memos updated after this timestamp
        schema:
          type: string
          format: date-time
          example: '2023-01-01T00:00:00Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - credit_memos
                type: object
                properties:
                  credit_memos:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditMemo'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Credit Memos
      operationId: create-a-credit-memo
      summary: Creates a credit memo
      description: 'Opens a customer credit memo that reduces receivable exposure before you allocate it to specific invoices.

        Capture subsidiary, customer, line-level reasons, and tax treatment so finance can audit why the balance changed.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreditMemoRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters: []
  /credit-memos/{credit_memo_id}:
    get:
      tags:
      - Credit Memos
      operationId: retrieve-a-credit-memo
      summary: Retrieves a credit memo
      description: 'Loads the full credit memo payload, including remaining balance, applications, and tax metadata you must echo on PUT updates.

        Always retrieve before editing because update-a-credit-memo replaces the entire resource when fields are omitted.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo to be used in this operation.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Credit Memos
      operationId: delete-a-credit-memo
      summary: Deletes a credit memo
      description: 'Removes a credit memo that should no longer affect AR balances, typically while it is still draft or unused.

        Confirm no invoice applications or downstream revenue adjustments depend on this memo before calling delete.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo 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'
    put:
      tags:
      - Credit Memos
      operationId: update-a-credit-memo
      summary: Updates a credit memo
      description: 'IMPORTANT: This is a full-replace operation (PUT semantics). All fields must be

        included in the request body — omitting any field will set it to null, wiping

        existing data. Always call retrieve-a-credit-memo first to fetch the current record,

        then include ALL existing fields in your update request along with your changes.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo to be used in this operation.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCreditMemoRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credit-memos/{credit_memo_id}/taxes:
    post:
      tags:
      - Credit Memos
      operationId: update-taxes-for-a-credit-memo
      summary: Updates credit memo taxes
      description: 'Refreshes tax quotes on an existing credit memo using the same structured payload as invoice tax updates, stamped with taxesCalculatedAt for auditability.

        Use after line items change or when your tax engine recomputes jurisdiction-specific amounts before issuing the credit to the customer.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo to be used in this operation.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaxesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /credit-memos/{credit_memo_id}/applications:
    delete:
      tags:
      - Credit Memos
      operationId: delete-credit-memo-applications
      x-skip-mcp: true
      summary: Unapplies all credit memo applications
      description: 'Removes every application from this credit memo, reverting all invoice allocations.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo to be used in this operation.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Credit Memos
      operationId: apply-credit-memo
      x-skip-mcp: true
      summary: Reconciles credit memo applications
      description: 'Full reconcile of credit memo applications. The request body represents the desired set: missing applications are removed, new applications inserted, and existing applications updated when amount or application_date differ.

        '
      parameters:
      - name: credit_memo_id
        in: path
        description: UUID of the credit memo to be used in this operation.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyCreditMemoRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditMemo'
        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
    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.
    ApplyCreditMemoRequest:
      type: object
      required:
      - applications
      properties:
        applications:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreditMemoApplicationRequest'
    CreditMemo:
      type: object
      required:
      - address
      - applications
      - applied_amount
      - customer_id
      - id
      - credit_memo_date
      - credit_memo_number
      - items
      - net_amount
      - remaining_amount
      - status
      - subsidiary_id
      - taxed_amount
      - total
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        subsidiary_id:
          type: string
          format: uuid
        credit_memo_number:
          type: string
          example: CM01
        customer_id:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreditMemoItem'
        credit_memo_date:
          type: string
          format: date
        address:
          $ref: '#/components/schemas/Address'
        status:
          enum:
          - UNAPPLIED
          - PARTIALLY_APPLIED
          - APPLIED
          - REFUNDED
        net_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        total:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        applied_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        remaining_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/CreditMemoApplication'
        exchange_rate:
          $ref: '#/components/schemas/ExchangeRate'
        taxed_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp in UTC timezone (must end with 'Z')
    CreditMemoItem:
      type: object
      required:
      - description
      - net_amount
      - id
      - quantity
      - revenue
      - total_amount
      - product_id
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
          example: Description
        revenue:
          $ref: '#/components/schemas/ItemRevenue'
        total_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        taxed_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        net_amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        quantity:
          type: number
          example: 1
        product_id:
          type: string
          format: uuid
        fields:
          $ref: '#/components/schemas/FieldAssignments'
    TaxRate:
      allOf:
      - $ref: '#/components/schemas/TaxRateWithOptionalAmount'
      required:
      - tax_amount
    CreditMemoItemPriceRequest:
      type: object
      required:
      - product_id
      - quantity
      - amount_per_unit
      properties:
        product_id:
          type: string
          format: uuid
        quantity:
          type: number
          minimum: 0
        amount_per_unit:
          $ref: '#/components/schemas/MonetaryAmount'
          description: This amount shows up a *rate* on the credit memo, after applying the discount.
    Address:
      type: object
      required:
      - city
      - country
      - line1
      - state
      - zip_code
      properties:
        line1:
          type: string
          example: 123 Main St
        line2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: Nashville
        state:
          type: string
          example: TN
          description: State or province code (e.g. 'TN', 'CA' for US; 'ON' for Canada). Required when address is provided.
        zip_code:
          type: string
          example: '37201'
        country:
          $ref: '#/components/schemas/CountryCode'
    UpdateItemTaxesRequest:
      type: object
      required:
      - id
      - tax_rate
      properties:
        id:
          type: string
          format: uuid
        tax_rates:
          type: array
          items:
            $ref: '#/components/schemas/TaxRate'
    ItemRevenue:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/CalendarPeriod'
          description: Represents the period in which the service was rendered. This period is used for revenue recognition – the revenue is spread over this period. If not provided, the period starts and ends on the invoice date.
        pattern:
          $ref: '#/components/schemas/RevenuePattern'
          description: If not provided, the one from the product will be used.
        account_code:
          $ref: '#/components/schemas/AccountCode'
          description: If not provided, the one from the product will be used.
    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'
    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
    CreditMemoApplicationRequest:
      type: object
      required:
      - invoice_id
      - amount
      - application_date
      properties:
        invoice_id:
          type: string
          format: uuid
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        application_date:
          type: string
          format: date
    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'
    CreditMemoApplication:
      type: object
      required:
      - id
      - credit_memo_id
      - invoice_id
      - amount
      - application_date
      properties:
        id:
          type: string
          format: uuid
        credit_memo_id:
          type: string
          format: uuid
        invoice_id:
          type: string
          format: uuid
        invoice_number:
          type: string
        amount:
          $ref: '#/components/schemas/RoundedMonetaryAmount'
        application_date:
          type: string
          format: date
    CreateCreditMemoItemRequest:
      type: object
      required:
      - description
      - price
      properties:
        description:
          type: string
        price:
          $ref: '#/components/schemas/CreditMemoItemPriceRequest'
        revenue:
          $ref: '#/components/schemas/ItemRevenue'
        tax_rate:
          $ref: '#/components/schemas/TaxRateWithOptionalAmount'
        fields:
          $ref: '#/components/schemas/FieldAssignments'
    CountryCode:
      type: string
      description: Two-letter country code (ISO 3166-1 alpha-2).
      example: US
    CalendarPeriod:
      type: object
      required:
      - end
      - start
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
    CurrencyCode:
      type: string
      description: Currency code following ISO-4217
      example: USD
    UpdateTaxesRequest:
      type: object
      required:
      - taxes_calculated_at
      - items
      properties:
        taxes_calculated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp in UTC timezone (must end with 'Z')
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/UpdateItemTaxesRequest'
    RevenuePattern:
      type: string
      enum:
      - DAILY
      - EVEN_PERIOD
      description: DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
    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
    UpdateCreditMemoRequest:
      type: object
      required:
      - credit_memo_date
      - items
      properties:
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreateCreditMemoItemRequest'
        credit_memo_date:
          type: string
          format: date
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
    CreateCreditMemoRequest:
      type: object
      required:
      - credit_memo_date
      - items
      - customer_id
      properties:
        credit_memo_number:
          type: string
          pattern: \S+
        customer_id:
          type: string
          format: uuid
        subsidiary_id:
          type: string
          format: uuid
        credit_memo_date:
          type: string
          format: date
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreateCreditMemoItemRequest'
        external_references:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        exchange_rate:
          $ref: '#/components/schemas/ExchangeRate'
    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'