---
title: "List invoice payable details"
method: GET
path: "/v1/invoice-payables"
tags: ["v1 - Invoice Payables"]
---

# List invoice payable details

`GET /v1/invoice-payables`

## Request

- Base URL: `https://light.inc` (the document declares no server; this is the origin it was published from)
- URL: `https://light.inc/v1/invoice-payables`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Returns a paginated list of invoice payables. Defaults to `createdAt:desc` when `sort` is omitted. `updatedAt`, `approverUserId`, `userId` and `hasWithholding` can be filtered on but are not returned in the response, and `updatedAt` cannot be sorted by. Resolve `vendorId` against `GET /v1/vendors/{vendorId}` for the vendor's details beyond `vendorName`. Filter on `documentStatus:in:POSTED|PARTIALLY_CLEARED` to list the bills that still owe money; a `state` filter cannot express that, because the scheduled and payment-pending bills owe money too. There is no partial-match operator, so a filter on a text field such as `vendorName`, `description` or `invoiceNumber` matches the stored value exactly and returns an empty page when nothing matches.

## Query parameters

- `sort` string: Sort string in the format `field:direction`. To provide multiple sort fields, separate them with commas. Available directions: `asc`, `desc`. Available fields: `amount`, `canceledAt`, `createdAt`, `description`, `dueDate`, `invoiceNumber`, `issuedDate`, `ocrCompletedAt`, `paymentAt`, `senderEmail`, `state`, `vendorName`.
- `filter` string: Filter string in the format `field:operator:value`. To provide multiple filters, separate them with commas. Available operators: `eq`, `ne`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`. - For `in` and `not_in` operators, provide multiple values separated by the pipe character (`|`). Available fields: `amount`, `approverUserId`, `companyEntityId`, `createdAt`, `description`, `documentStatus`, `dueDate`, `hasWithholding`, `id`, `invoiceNumber`, `issuedDate`, `paymentAt`, `senderBankAccountId`, `state`, `type`, `updatedAt`, `userId`, `vendorId`, `vendorName`. These fields accept only a subset of the operators: `hasWithholding` (`eq`, `ne`).
- `limit` integer
- `cursor` string

## Response `default`

default response

- ExternalCursorPaginatedResponseV1ModelExternalInvoicePayableListItemV1Model
  - `records` ExternalInvoicePayableListItemV1Model[]: List of records for the current page
    - `id` string, uuid: External ID of the invoice payable object.
    - `type` 'REIMBURSEMENT' | 'SELF_BILLED' | 'VENDOR_INVOICE': Type of the invoice payable (e.g. vendor invoice or reimbursement). ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `metadata` ExternalInvoicePayableMetadataV1Model: Metadata specific to the invoice payable type (e.g. reimbursement- or vendor-specific fields).
      - `type` 'SELF_BILLED_METADATA' | 'VENDOR_INVOICE_METADATA' | 'REIMBURSEMENT_METADATA': Type of metadata attached to the invoice payable, depending on its kind (vendor invoice or reimbursement). ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `state` 'INIT' | 'CREATED' | 'IN_DRAFT' | 'APPROVAL_REQUESTED' | 'APPROVAL_PENDING' | 'APPROVED_ACCOUNTING_ENTRY_PENDING' | 'DECLINED' | 'READY_FOR_PAYMENT_RELEASE' | 'PENDING_PAYMENT_APPROVAL' | 'PAYMENT_PAUSED' | 'SCHEDULED' | 'PAYMENT_PENDING' | 'PARTIALLY_PAID' | 'UNPAID' | 'PAID' | 'COMPLETED' | 'RESET_PENDING' | 'CANCELLATION_PENDING' | 'CANCELLED' | 'DUPLICATED' | 'IMPORT_PENDING': Current state of the invoice payable in its lifecycle (from ingestion to payment/completion). ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `documentStatus` 'DRAFT' | 'APPROVAL_PENDING' | 'APPROVED' | 'POSTED' | 'PARTIALLY_CLEARED' | 'CLEARED' | 'ARCHIVED': Status of the accounting document the invoice payable is booked as. Filter on `documentStatus:in:POSTED|PARTIALLY_CLEARED` to list the bills that still owe money. ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `companyId` string, uuid: ID of the company this invoice payable belongs to.
    - `companyEntityId` string, uuid, nullable: ID of the company entity this invoice payable is booked under.
    - `vendorId` string, uuid, nullable: ID of the vendor entity this invoice payable is linked to, if any.
    - `vendorName` string, nullable: Name of the vendor the invoice payable is for, as stored on the vendor record. Resolve `vendorId` against `GET /v1/vendors/{vendorId}` for the vendor's other details.
    - `invoiceNumber` string, nullable: Invoice number provided on the vendor invoice.
    - `documentName` string, nullable: Name of the original document file associated with this invoice payable.
    - `description` string, nullable: Description or memo for the invoice payable.
    - `amount` integer, nullable: Total invoice amount in cents, expressed in the invoice currency.
    - `netAmount` integer, nullable: Net amount in cents, excluding tax. Unlike `amount`, this is not a header value: it is derived by summing this invoice payable's persisted line items (debit-positive, credit-negative), so it is null when the bill has no coded lines even though `amount` is set, and it is not guaranteed to sum to `amount`.
    - `outstandingBalance` integer, nullable: Outstanding invoice balance to be paid in cents, expressed in the invoice currency. `0` means the bill is settled. `null` means Light derived no balance for it — for instance the bill has no amount yet, its state is `CANCELLED`, `DECLINED` or `DUPLICATED`, or the company does not keep its ledger in Light — so do not read `null` as fully paid.
    - `amountPaid` integer, nullable: Amount paid against the invoice in cents, expressed in the invoice currency. Credit notes and reversed payments are not counted. `null` means Light derived no balance for the bill, as for `outstandingBalance`.
    - `currency` string, nullable
    - `issuedDate` string, date, nullable: Issue date of the original vendor invoice.
    - `postingDate` string, date: Date the invoice payable is posted to the ledger, which sets its accounting period.
    - `dueDate` string, date, nullable: Payment due date of the invoice payable.
    - `paymentAt` string, date-time, nullable: Date/time when payment is scheduled or was executed for this invoice payable.
    - `invoiceCreatedAt` string, date-time: Timestamp when the invoice payable record was created.
    - `updatedAt` string, date-time: Timestamp when the invoice payable record was last updated.
    - `ocrCompletedAt` string, date-time, nullable: Timestamp when OCR processing for this invoice payable was completed.
    - `canceledAt` string, date-time, nullable: Timestamp when this invoice payable was cancelled.
    - `cancellationReason` string, nullable: Reason why the invoice payable was cancelled, if applicable.
    - `approvalNote` string, nullable: Approval note associated with the invoice payable (e.g. approver comments).
    - `failureReason` 'EMAIL_NOT_ALLOWED' | 'ERP_ENTRY_FAILED' | 'OCR_FAILED' | 'DOCUMENT_PROCESSING_FAILED' | 'PAYMENT_APPROVAL_DECLINED' | 'PAYMENT_FAILED' | 'RESETTING_INVOICE_FAILED' | 'CANCELLING_INVOICE_FAILED' | 'APPROVAL_SUBMISSION_FAILED' | 'PAYMENT_VALIDATION_FAILED' | 'USER_INPUT_VALIDATION_FAILED' | 'DUPLICATE_INVOICE' | 'PAYMENT_REJECTED' | 'PAYMENT_REVERSED', nullable: High-level reason why processing the invoice payable failed, if any. ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `failureContext` ExternalUiClientExceptionV1Model, nullable: Failure context when vendor onboarding fails.
      - `name` string: The error name
      - `type` 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT': The error type ⚠️ This enum is not exhaustive; new values may be added in the future.
      - `errors` ExternalUiClientExceptionErrorV1Model[]: List of errors providing details about what went wrong
        - `type` string: A string code identifying the error type
        - `message` string: A human-readable message providing more details about the error
        - `path` string[], nullable: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
        - `context` object, nullable: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error
    - `warningContext` ExternalUiClientExceptionV1Model, nullable: Failure context when vendor onboarding fails.
      - `name` string: The error name
      - `type` 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT': The error type ⚠️ This enum is not exhaustive; new values may be added in the future.
      - `errors` ExternalUiClientExceptionErrorV1Model[]: List of errors providing details about what went wrong
        - `type` string: A string code identifying the error type
        - `message` string: A human-readable message providing more details about the error
        - `path` string[], nullable: Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object
        - `context` object, nullable: Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error
    - `fiNumber` string, nullable: FI (Finnish reference) number associated with this invoice payable, if applicable.
    - `senderEmail` string, nullable: Email address from which the invoice payable was received, if known.
    - `senderBankAccountId` string, uuid, nullable: ID of the sender bank account from which this invoice payable will be paid.
    - `paymentPausedBy` string, uuid, nullable: ID of the user who paused payment for this invoice payable, if payment is paused.
    - `paymentPausedAt` string, date-time, nullable: Timestamp when payment for this invoice payable was paused, if applicable.
    - `payeeName` string, nullable: Name of the payee for this invoice payable.
    - `payeeIban` string, nullable: Payee IBAN used for payment of this invoice payable.
    - `payeeBban` string, nullable: Payee BBAN (Basic Bank Account Number) used for local payments.
    - `payeeBic` string, nullable: Payee bank BIC/SWIFT code.
    - `payeeBankCode` string, nullable: Payee bank/branch code used for local payments.
    - `payeeBankName` string, nullable: Name of the payee's bank.
    - `payeeBankCountry` 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BU' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CP' | 'CR' | 'CS' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DG' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EA' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'EU' | 'EZ' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'FX' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'IC' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NT' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SF' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SU' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TP' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UK' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XI' | 'XU' | 'XK' | 'YE' | 'YT' | 'YU' | 'ZA' | 'ZM' | 'ZR' | 'ZW', nullable: Country of the payee's bank. ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `payeeBankAddress` string, nullable: Street address of the payee's bank.
    - `payeeBankCity` string, nullable: City of the payee's bank.
    - `payeeBankZipcode` string, nullable: ZIP/postal code of the payee's bank.
    - `payeeCountry` 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BU' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CP' | 'CR' | 'CS' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DG' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EA' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'EU' | 'EZ' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'FX' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'IC' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NT' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SF' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SU' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TP' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UK' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XI' | 'XU' | 'XK' | 'YE' | 'YT' | 'YU' | 'ZA' | 'ZM' | 'ZR' | 'ZW', nullable: Country of the payee. ⚠️ This enum is not exhaustive; new values may be added in the future.
    - `payeeAddress` string, nullable: Street address of the payee.
    - `payeeCity` string, nullable: City of the payee.
    - `payeeZipcode` string, nullable: ZIP/postal code of the payee.
  - `hasMore` boolean: Boolean flag indicating if there are more records available
  - `nextCursor` string, nullable: Cursor for fetching the next page
  - `prevCursor` string, nullable: Cursor for fetching the previous page

---

[API](https://skmtc.dev/light/apis/light-api.md) - [All operations](https://skmtc.dev/light/apis/light-api/llms.txt) - [OpenAPI document](https://skmtc.dev/light/apis/light-api/revisions/84f51306f648?raw)