> ## Documentation Index
> Fetch the complete documentation index at: https://docs-beta.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List refunds

> Fetches a list of refunds for a business. Refunds can be filtered by external ID, status, completion date range, amount range, and payout inclusion. Results will be paginated, see [Pagination](/api-details/pagination) for details.



## OpenAPI

````yaml get /v1/businesses/{businessId}/invoices/refunds
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/invoices/refunds:
    get:
      tags: []
      summary: List refunds
      description: >-
        Fetches a list of refunds for a business. Refunds can be filtered by
        external ID, status, completion date range, amount range, and payout
        inclusion. Results will be paginated, see
        [Pagination](/api-details/pagination) for details.
      operationId: business.invoices.refunds.get
      parameters:
        - name: businessId
          in: path
          description: The UUID of the business to fetch refunds for.
          required: true
          schema:
            type: string
        - name: external_id
          in: query
          description: >-
            Filter refunds by external ID (unique idempotency key). This will
            always yield zero or one result.
          schema:
            type: string
        - name: status
          in: query
          description: Filter refunds by status.
          schema:
            type: string
            enum:
              - SENT
              - PARTIALLY_PAID
              - PAID
        - name: completed_at_start
          in: query
          description: >-
            Filter refunds by completion date. Refunds completed on or after
            this date will be included. ISO 8601 date format.
          schema:
            type: string
            format: date-time
        - name: completed_at_end
          in: query
          description: >-
            Filter refunds by completion date. Refunds completed on or before
            this date will be included. ISO 8601 date format.
          schema:
            type: string
            format: date-time
        - name: is_dedicated
          in: query
          description: Filter refunds by whether they are dedicated to a single target.
          schema:
            type: boolean
        - name: included_in_payout
          in: query
          description: >-
            Filter refunds by whether they are included in a payout. Set to
            `true` to show only refunds that are part of a payout, `false` to
            show only refunds not in any payout.
          schema:
            type: boolean
        - name: min_amount
          in: query
          description: >-
            Filter refunds by minimum amount. Only refunds with amounts greater
            than or equal to this value will be included. Must be a positive
            integer.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: max_amount
          in: query
          description: >-
            Filter refunds by maximum amount. Only refunds with amounts less
            than or equal to this value will be included. Must be a positive
            integer.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: reference_numbers
          in: query
          description: >-
            Comma-separated list of reference numbers to filter refunds by. Only
            refunds with reference numbers matching any value in this list will
            be returned.
          required: false
          schema:
            type: string
        - name: Content-Type
          in: header
          description: Content-Type must be set to application/json
          schema:
            type: string
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiRefund'
        '404':
          description: >-
            Business id is not found. This indicates the business id is invalid
            or the business has been archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: false
components:
  schemas:
    ApiRefund:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the refund.
        external_id:
          type: string
          description: >-
            Unique ID of the refund in your system for linking purposes.
            **Idempotency key**.
          example: '31415926535'
        refunded_amount:
          type: integer
          format: int64
          description: Amount refunded to the customer in cents.
        status:
          type: string
          description: Status of the refund.
          example: PAID
        completed_at:
          type: string
          format: date-time
          description: Time when the refund was completed.
        is_dedicated:
          type: boolean
          description: >-
            Whether this refund is dedicated or not. Dedicated refunds can only
            have one allocation and one payment.
          example: true
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/ApiRefundAllocation'
          description: Allocations associated with this refund.
        payments:
          type: array
          items:
            $ref: '#/components/schemas/ApiRefundPayment'
          description: Payments associated with this refund.
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/ApiPayoutWithoutTransactions'
          description: Payouts associated with this refund.
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the refund (for
            example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the refund. Can be used to filter when listing refunds.
      description: >-
        A refund represents a transaction that returns value to from a business
        to a customer. A specific payment can be refunded or a general refund
        can be applied to an invoice.
    ApiError:
      type: object
      properties: {}
      example: ''
      description: ''
    ApiRefundAllocation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the refund allocation.
        invoice_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the invoice this allocation is associated with.
        amount:
          type: integer
          format: int64
          description: Amount of the allocation in cents.
        account_identifier:
          $ref: '#/components/schemas/AccountIdentifier'
          description: >-
            Identifier of the ledger account for the refund allocation to apply
            to
          nullable: true
        invoice_external_id:
          type: string
          nullable: true
          description: External ID of the invoice this allocation is associated with.
        invoice_line_item_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            ID of the invoice line item this allocation is associated with. If
            specified, must not refer to a different invoice `invoice_external`
            or `invoice_id`.
        invoice_line_item_external_id:
          type: string
          nullable: true
          description: >-
            The external ID of the invoice line item to refund. If specified
            alongside `invoice_line_item_id`, they must refer to the same
            invoice line item.
        invoice_payment_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the invoice payment this allocation is associated with.
        invoice_payment_external_id:
          type: string
          nullable: true
          description: >-
            External ID of the invoice payment this allocation is associated
            with.
        customer:
          $ref: '#/components/schemas/ApiCustomerData'
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the refund
            allocation (for example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the refund allocation.
    ApiRefundPayment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the payment.
        external_id:
          type: string
          description: >-
            Unique ID of the payment in your system for linking purposes.
            **Idempotency key**.
          example: '31415926535'
        refunded_amount:
          type: integer
          format: int64
          description: Amount refunded to the customer in cents.
        fee:
          type: integer
          format: int64
          nullable: true
          description: Fee charged for the refund in cents.
        completed_at:
          type: string
          format: date-time
          description: Time when the payment was completed.
        method:
          type: string
          description: Method of the payment.
          example: CREDIT_CARD
        processor:
          type: string
          nullable: true
          description: Processor used for the payment.
          example: STRIPE
        payment_clearing_account:
          $ref: '#/components/schemas/SingleApiChartAccount'
          description: >-
            The the ledger account to use for the payment (overrides the default
            determined by the payment method), if specified.
        refunded_payment_fees:
          type: array
          description: Refunded payment fees associated with the refund payment
          items:
            $ref: '#/components/schemas/ApiRefundedPaymentFee'
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the refund
            payment (for example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the refund payment. Can be used to filter when listing refund
            payments.
      description: >-
        A payment represents a transaction that moves value from a customer to a
        business. A specific payment can be refunded or a general refund can be
        applied to an invoice.
    ApiPayoutWithoutTransactions:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID for the Payout. **Idempotency key.**
        external_id:
          type: string
          nullable: true
          description: Unique ID of the payout in your system for linking purposes.
          example: payout-1234
        business_id:
          type: string
          format: uuid
          description: ID of the Business that generated the payout.
        paid_out_amount:
          type: integer
          format: int64
          description: The amount of the payout, in cents
        fee:
          type: integer
          format: int64
          description: The platform fee associated with the payout
        processor:
          $ref: '#/components/schemas/PaymentProcessor'
          description: >-
            Processor used to make the payment, if any. Any processor name can
            be provided and will be tracked. 
          example: STRIPE
        imported_at:
          type: string
          format: date-time
          description: Timestamp of when the payout was imported
        completed_at:
          type: string
          format: date-time
          description: Timestamp of when the payout was completed
        match:
          $ref: '#/components/schemas/ApiMatch'
          description: The transaction match associated with the payout
          example:
            id: 6b0a3734-f4ef-4fb0-9fc1-3f59b0c1cf99
            match_type: PAYOUT
            bank_transaction:
              type: Bank_Transaction_Data
              id: a703c8d6-cfe8-453d-a275-b92eacc6fc6e
              business_id: 738ec216-e8e5-48f2-b7f2-cdc89c96b3d4
              source: STRIPE
              source_transaction_id: trxn_1sdOeLQiFAKE2LQBkcvrJw95f
              source_account_id: 738ec216-e154-48f2-1111-cdc89c96b3d4
              imported_at: '2024-03-19T22:09:53.290591Z'
              date: '2024-03-06T06:06:40Z'
              direction: CREDIT
              amount: 87459
              counterparty_name: null
              description: Payout (po_1OqnTHISISFAKEiTVBkCiyAERwm)
              account_name: Layer Banking
              categorization_status: MATCHED
            details:
              type: Payout_Match
              id: d224508b-b05e-41da-89de-0fbd8a573507
              amount: 87459
              date: '2024-03-06T00:00:00Z'
              description: Payout from STRIPE
              adjustment: null
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
          description: A list of tags associated with the payout
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the payout (for
            example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the payout. Can be used to filter when listing payouts.
    ApiTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID for the tag
        key:
          type: string
          description: Key for the tag
          example: ExampleTagKey
        dimension_display_name:
          type: string
          nullable: true
          description: Display name for the tag dimension
        value:
          type: string
          description: Value for the tag
          example: ExampleTagValue
        value_display_name:
          type: string
          nullable: true
          description: Display name for the tag value definition
        dimension_id:
          type: string
          format: uuid
          description: ID of the tag dimension this tag belongs to
        definition_id:
          type: string
          format: uuid
          description: ID of the tag value definition
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: When the tag was archived
      required:
        - id
        - key
        - value
        - dimension_id
        - definition_id
    PlatformDefinedJson:
      type: object
      description: Arbitrary JSON data defined by the caller, with a 1KB size constraint
      additionalProperties: true
      example:
        custom_field: value
        any valid json: below 1kb
        nested:
          meaning of life: 42
          array: []
    AccountIdentifier:
      oneOf:
        - $ref: '#/components/schemas/AccountId'
          description: ID of the account
          title: Account ID
        - $ref: '#/components/schemas/AccountStableName'
          description: Stable name associated with the account
          title: Account Stable Name
    ApiCustomerData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the customer.
        external_id:
          type: string
          description: >-
            Unique ID of the customer in your system for linking purposes.
            **Idempotency key**.
          example: '31415926535'
        individual_name:
          type: string
          nullable: true
          description: >-
            Full name of the individual customer or contact at a corporate
            customer.
        company_name:
          type: string
          nullable: true
          description: Name of the company customer.
        email:
          type: string
          nullable: true
          description: Email address of the customer.
        mobile_phone:
          type: string
          nullable: true
          description: Mobile phone number of the customer.
        office_phone:
          type: string
          nullable: true
          description: Office phone number of the customer.
        address_string:
          type: string
          nullable: true
          description: Address of the customer.
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the customer (for
            example, to display to end users).
        status:
          type: string
          description: 'Status of the customer. Possible values: `ACTIVE`, `ARCHIVED`.'
          example: ACTIVE
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
    SingleApiChartAccount:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AccountIdentifier'
        name:
          type: string
          description: Name of the account
          example: Current Assets
        account_number:
          type: string
          nullable: true
          description: Account number if configured
          example: '4000'
        stable_name:
          $ref: '#/components/schemas/AccountStableName'
        normality:
          $ref: '#/components/schemas/BankTransactionDirection'
        account_type:
          $ref: '#/components/schemas/ApiLedgerAccountType'
        account_subtype:
          $ref: '#/components/schemas/ApiLedgerAccountSubtype'
      description: A single ledger account without nested children
    ApiRefundedPaymentFee:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/AccountIdentifier'
          description: Identifier of the ledger account for the refunded payment fee
        description:
          type: string
          nullable: true
          description: Description of the fee that the refunded payment fee refunds
        fee_amount:
          type: integer
          format: int64
          description: Amount of the fee refund in cents
    PaymentProcessor:
      type: string
      enum:
        - STRIPE
        - PAYPAL
        - SHOPIFY
        - ADYEN
        - RAINFOREST
    ApiMatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Layer's UUID for the match
        match_type:
          $ref: '#/components/schemas/MatchType'
          description: Type of the object to match
        bank_transaction:
          $ref: '#/components/schemas/ApiBankTransactionInterface'
        details:
          $ref: '#/components/schemas/ApiMatchDetails'
    AccountId:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `AccountId`.
          example: AccountId
        id:
          type: string
          format: uuid
          description: ID of the account
    AccountStableName:
      type: object
      properties:
        type:
          type: string
          description: Resource type. Value will be `StableName`.
          example: StableName
        stable_name:
          type: string
          example: CURRENT_ASSETS
          description: Stable name of the account
    BankTransactionDirection:
      type: string
      enum:
        - CREDIT
        - DEBIT
    ApiLedgerAccountType:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/LedgerAccountType'
          description: Type of the account
        display_name:
          type: string
          description: Display name of the account type
          example: Asset
    ApiLedgerAccountSubtype:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/LedgerAccountSubtype'
        display_name:
          type: string
          description: Display name of the account subtype
          example: Current Assets
    MatchType:
      type: string
      enum:
        - TRANSFER
        - INVOICE_PAYMENT
        - PAYOUT
    ApiBankTransactionInterface:
      type: object
      required:
        - id
        - amount
        - date
      properties:
        id:
          type: string
          format: uuid
          description: Layer's UUID for the bank transaction
        business_id:
          type: string
          format: uuid
          description: UUID of the business the transaction is for
        source:
          $ref: '#/components/schemas/TransactionSource'
          description: Source of the bank transaction.
        source_transaction_id:
          type: string
          description: >-
            External transaction ID from the source platform (e.g, Plaid
            transaction ID)
          example: g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko
        source_account_id:
          type: string
          description: External account ID from the source platform (e.g, Plaid account ID)
          example: Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG
        imported_at:
          type: string
          format: date-time
          description: Timestamp when the transaction was imported.
        date:
          type: string
          format: date-time
          description: Timestamp when the transaction was created.
        direction:
          $ref: '#/components/schemas/BankTransactionDirection'
          description: Direction of the transaction.
        amount:
          type: integer
          format: int64
          description: Amount of the transaction, in cents.
        counterparty_name:
          type: string
          nullable: true
          description: Name of the transaction counterparty
          example: WeWork
        description:
          type: string
          nullable: true
          description: Description of the transaction.
          example: WeWork monthly rent payment
        account_name:
          type: string
          nullable: true
          description: Name of the bank account
          example: Plaid Checking
        categorizationStatus:
          $ref: '#/components/schemas/CategorizationStatus'
          description: The status of the transaction’s categorization in Layer’s systems.
        memo:
          type: string
          nullable: true
          description: >-
            Memo for any text you would like to associate with the bank
            transaction (for example, to display to end users).
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
          nullable: true
          description: Arbitrary custom metadata in JSON format with a size limit of 1KB
        reference_number:
          type: string
          nullable: true
          description: >-
            Any (typically user-visible) identifier you would like to associate
            with the bank transaction. Can be used to filter when listing bank
            transactions.
    ApiMatchDetails:
      type: object
      required:
        - id
        - amount
        - date
      properties:
        id:
          type: string
          format: uuid
          description: Layer's ID for the match
        amount:
          type: integer
          format: int64
          description: Monetary amount of the matched transaction, in cents
        date:
          type: string
          format: date-time
          description: Date that the matched transaction occurred
        description:
          type: string
          nullable: true
          description: Description of the match
          example: Transfer from SavingsAccount to CheckingAccount
    LedgerAccountType:
      type: string
      enum:
        - ASSET
        - LIABILITY
        - EQUITY
        - REVENUE
        - COGS
        - EXPENSE
    LedgerAccountSubtype:
      type: string
      enum:
        - BANK_ACCOUNTS
        - ACCOUNTS_RECEIVABLE
        - INVENTORY
        - PAYMENT_PROCESSOR_CLEARING_ACCOUNT
        - FIXED_ASSET
        - ACCUMULATED_DEPRECIATION
        - CASH
        - UNDEPOSITED_FUNDS
        - CURRENT_ASSET
        - NON_CURRENT_ASSET
        - PREPAID_EXPENSES
        - DEVELOPMENT_COSTS
        - LOANS_RECEIVABLE
        - INTANGIBLE_ASSET
        - ACCOUNTS_PAYABLE
        - CREDIT_CARD
        - TAXES_PAYABLE
        - INCOME_TAXES_PAYABLE
        - SALES_TAXES_PAYABLE
        - OTHER_TAXES_PAYABLE
        - PAYROLL_TAXES_PAYABLE
        - UNEARNED_REVENUE
        - PAYROLL_LIABILITY
        - PAYROLL_CLEARING
        - LINE_OF_CREDIT
        - TIPS
        - REFUND_LIABILITIES
        - UNDEPOSITED_OUTFLOWS
        - OUTGOING_PAYMENT_CLEARING_ACCOUNT
        - OTHER_CURRENT_LIABILITY
        - LOANS_PAYABLE
        - NOTES_PAYABLE
        - SHAREHOLDER_LOAN
        - NON_CURRENT_LIABILITY
        - CONTRIBUTIONS
        - DISTRIBUTIONS
        - COMMON_STOCK
        - PREFERRED_STOCK
        - ADDITIONAL_PAID_IN_CAPITAL
        - RETAINED_EARNINGS
        - ACCUMULATED_ADJUSTMENTS
        - OPENING_BALANCE_EQUITY
        - OTHER_EQUITY
        - SALES
        - UNCATEGORIZED_REVENUE
        - RETURNS_ALLOWANCES
        - DIVIDEND_INCOME
        - INTEREST_INCOME
        - OTHER_INCOME
        - COGS
        - OPERATING_EXPENSES
        - PAYROLL
        - TAXES_LICENSES
        - UNCATEGORIZED_EXPENSE
        - CHARITABLE_CONTRIBUTIONS
        - LOAN_EXPENSES
        - FINANCE_COSTS
        - INTEREST_EXPENSES
        - DEPRECIATION
        - AMORTIZATION
        - BAD_DEBT
        - OTHER_EXPENSES
    TransactionSource:
      type: string
      enum:
        - UNIT
        - PLAID
        - API
        - STRIPE
        - CUSTOM
    CategorizationStatus:
      type: string
      enum:
        - PENDING
        - READY_FOR_INPUT
        - CATEGORIZED
        - SPLIT
        - LAYER_REVIEW
        - JOURNALING
        - MATCHED
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````