New Introducing the Light partner portalPartner portal Join the movement

API/Reference/Invoice Payables

List invoice payable details

GET 
https://api.light.inc/v1/invoice-payables

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.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

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 · int32

    Maximum number of items to return. Default is 50, maximum is 200.

  • cursor string

    The cursor position to start returning results from. To opt-in into cursor-based pagination, provide 0 for the initial request. For subsequent requests, use nextCursor and prevCursor from the previous response to navigate. Cursor values are opaque and should not be constructed manually.

Response

  • records array of object

    List of records for the current page

    • id string · uuid

      External ID of the invoice payable object.

    • type string

      Type of the invoice payable (e.g. vendor invoice or reimbursement).

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of REIMBURSEMENT SELF_BILLED VENDOR_INVOICE

    • metadata object

      Metadata specific to the invoice payable type (e.g. reimbursement- or vendor-specific fields).

      • type string

        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.

        One of SELF_BILLED_METADATA VENDOR_INVOICE_METADATA REIMBURSEMENT_METADATA

    • state string

      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.

      One of 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

    • documentStatus string

      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.

      One of DRAFT APPROVAL_PENDING APPROVED POSTED PARTIALLY_CLEARED CLEARED ARCHIVED

    • companyId string · uuid

      ID of the company this invoice payable belongs to.

    • companyEntityId string · uuid

      ID of the company entity this invoice payable is booked under.

    • vendorId string · uuid

      ID of the vendor entity this invoice payable is linked to, if any.

    • vendorName string

      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

      Invoice number provided on the vendor invoice.

    • documentName string

      Name of the original document file associated with this invoice payable.

    • description string

      Description or memo for the invoice payable.

    • amount integer · int64

      Total invoice amount in cents, expressed in the invoice currency.

    • netAmount integer · int64

      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 · int64

      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 · int64

      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

    • issuedDate string · date

      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

      Payment due date of the invoice payable.

    • paymentAt string · date-time

      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

      Timestamp when OCR processing for this invoice payable was completed.

    • canceledAt string · date-time

      Timestamp when this invoice payable was cancelled.

    • cancellationReason string

      Reason why the invoice payable was cancelled, if applicable.

    • approvalNote string

      Approval note associated with the invoice payable (e.g. approver comments).

    • failureReason string

      High-level reason why processing the invoice payable failed, if any.

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of 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

    • failureContext object

      Failure context when vendor onboarding fails.

      • name string

        The error name

      • type string

        The error type

        ⚠️ This enum is not exhaustive; new values may be added in the future.

        One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

      • errors array of object

        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 array of string

          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

          Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error

    • warningContext object

      Failure context when vendor onboarding fails.

      • name string

        The error name

      • type string

        The error type

        ⚠️ This enum is not exhaustive; new values may be added in the future.

        One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

      • errors array of object

        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 array of string

          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

          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

      FI (Finnish reference) number associated with this invoice payable, if applicable.

    • senderEmail string

      Email address from which the invoice payable was received, if known.

    • senderBankAccountId string · uuid

      ID of the sender bank account from which this invoice payable will be paid.

    • paymentPausedBy string · uuid

      ID of the user who paused payment for this invoice payable, if payment is paused.

    • paymentPausedAt string · date-time

      Timestamp when payment for this invoice payable was paused, if applicable.

    • payeeName string

      Name of the payee for this invoice payable.

    • payeeIban string

      Payee IBAN used for payment of this invoice payable.

    • payeeBban string

      Payee BBAN (Basic Bank Account Number) used for local payments.

    • payeeBic string

      Payee bank BIC/SWIFT code.

    • payeeBankCode string

      Payee bank/branch code used for local payments.

    • payeeBankName string

      Name of the payee's bank.

    • payeeBankCountry string

      Country of the payee's bank.

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of 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

    • payeeBankAddress string

      Street address of the payee's bank.

    • payeeBankCity string

      City of the payee's bank.

    • payeeBankZipcode string

      ZIP/postal code of the payee's bank.

    • payeeCountry string

      Country of the payee.

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of 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

    • payeeAddress string

      Street address of the payee.

    • payeeCity string

      City of the payee.

    • payeeZipcode string

      ZIP/postal code of the payee.

  • hasMore boolean

    Boolean flag indicating if there are more records available

  • nextCursor string

    Cursor for fetching the next page

  • prevCursor string

    Cursor for fetching the previous page