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

# Filter Invoices

> Authenticates the request and retrieves invoice data for the company associated with the
signature, applying filters and pagination from the query string.

**Behavior change:** the default response now includes `DRAFT`, `FINALIZED`, and `VOIDED`
invoices. Previously only `FINALIZED` invoices were returned. Pass
`lifecycleStatuses=FINALIZED` to restore the old behavior.




## OpenAPI

````yaml GET /external/invoices
openapi: 3.1.0
info:
  title: OpenAPI Valyx API
  description: To demonstrate features in the Valyx
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.valyx.com
security:
  - bearerAuth:
      - demo-api
tags:
  - name: billing
    description: External Billing APIs
  - name: external
    description: External APIs for customers
  - name: invoice
    description: Invoice APIs
  - name: creditNote
    description: Credit Note APIs
paths:
  /external/invoices:
    get:
      tags:
        - external
      summary: Handles GET requests for the /invoices route
      description: >
        Authenticates the request and retrieves invoice data for the company
        associated with the

        signature, applying filters and pagination from the query string.


        **Behavior change:** the default response now includes `DRAFT`,
        `FINALIZED`, and `VOIDED`

        invoices. Previously only `FINALIZED` invoices were returned. Pass

        `lifecycleStatuses=FINALIZED` to restore the old behavior.
      operationId: get_invoice_routes
      parameters:
        - name: invoiceStatus
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            enum:
              - OVERDUE
              - DUE
              - NO_DUES
              - VOID
          description: list of invoice statuses to filter by
        - name: paymentStatus
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            enum:
              - PAID
              - UNPAID
              - PARTIALLY_PAID
          description: list of payment statuses to filter by
        - name: invoiceAcceptanceStatus
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            enum:
              - PENDING
              - ACCEPTED
              - REJECTED
          description: list of invoice acceptance statuses to filter by
        - name: tag
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: list of tag key-value pair to filter by
        - name: customerIds
          in: query
          schema:
            type: string
          description: List of customer IDs
        - name: ownerIds
          in: query
          schema:
            type: string
          description: List of owner IDs
        - name: buyerIds
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: List of buyer IDs
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - invoiceDate
              - '-invoiceDate'
          description: >-
            Invoices support sorting by invoice date. Passing 'invoiceDate'
            sorts ascending. To reverse the order, prefix with a hyphen.
        - name: amountType
          in: query
          schema:
            type: string
            enum:
              - TOTAL
              - OUTSTANDING
              - PAID
              - ADJUSTED
          description: Amount type filter
        - name: amountMin
          in: query
          schema:
            type: number
          description: Minimum amount of the invoice amount type
        - name: amountMax
          in: query
          schema:
            type: number
          description: Maximum amount of the invoice amount type
        - name: dateType
          in: query
          schema:
            type: string
            enum:
              - INVOICE_DATE
              - DUE_DATE
              - PROMISE_TO_PAY_DATE
              - CREATED_AT
              - UPDATED_AT
          description: >
            Field that `startDate` / `endDate` apply to.

            `CREATED_AT` filters by when the invoice was created in Valyx,
            `UPDATED_AT` by when it was last modified.

            For `CREATED_AT` / `UPDATED_AT` the end-date comparison is performed
            on `DATE(column)`, so the full

            end day is included; the other date types compare against the date
            column directly.
        - name: startDate
          in: query
          schema:
            type: string
          description: Start date for the selected `dateType`. Pass as `YYYY-MM-DD`.
        - name: endDate
          in: query
          schema:
            type: string
          description: End date for the selected `dateType`. Pass as `YYYY-MM-DD`.
        - name: originSource
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - ZOHO
                - IRECKONER
                - BOLTIC
                - VALYX
                - OTHER
          description: >
            Filter invoices by where they originated. Repeat the param to pass
            multiple values

            (e.g. `?originSource=VALYX&originSource=ZOHO`). Matches the
            `invoiceOriginSource` value

            stored on the invoice-extra row.
        - name: lifecycleStatuses
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - DRAFT
                - FINALIZED
                - VOIDED
                - DELETED
          description: >
            Filter invoices by lifecycle status. Repeat the param to pass
            multiple values

            (e.g. `?lifecycleStatuses=FINALIZED&lifecycleStatuses=DRAFT`).


            **Default behavior change:** by default the response now includes
            `DRAFT`, `FINALIZED`, and

            `VOIDED` invoices (previously `DRAFT` and `VOIDED` were excluded).
            Callers that need only

            finalized invoices must pass `lifecycleStatuses=FINALIZED`
            explicitly.


            `DELETED` is accepted by the parser but yields no results — deleted
            invoices are always

            excluded from this endpoint.
        - name: page
          in: query
          required: true
          schema:
            type: integer
          description: page number of result to be fetched
        - name: pageSize
          in: query
          required: true
          schema:
            type: integer
          description: number of entries per page
        - name: onlyFetchNonZero
          in: query
          schema:
            type: boolean
          description: should return invoices that have non zero amount type
        - name: invoiceNumber
          in: query
          schema:
            type: string
          description: invoice number
        - name: internalInvoiceIds
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: invoice ids
        - name: hasAttachment
          in: query
          schema:
            type: string
          description: should return invoices that have attachments (true/false)
        - name: attachmentPurpose
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            enum:
              - INVOICE_FOR_BUYER
              - INVOICE_SUPPORTING
              - PURCHASE_ORDER
              - SALES_ORDER
              - DELIVERY_DOCUMENT
              - PAYMENT_PROOF
              - DISPUTE
              - DISPUTE_RESOLUTION
              - ENQUIRY
              - ENQUIRY_RESOLUTION
              - TAX_DOCUMENT
              - COMMERCIAL_AGREEMENT
              - COMMERCIAL_AGREEMENT_SUPPORTING
              - LEGAL
              - GENERAL
              - CREDITNOTE_FOR_BUYER
              - CREDITNOTE_SUPPORTING
              - TICKET
              - USAGE_ESTIMATE
              - MAIL_ATTACHMENT
          description: attachment purpose to search by (based on hasAttachment)
        - name: currencies
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Currencies
        - name: X-Valyx-Signature
          in: header
          required: true
          description: Auth key for fetching ledger entries
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceExternalApiResponseResponseModel'
components:
  schemas:
    InvoiceExternalApiResponseResponseModel:
      type: object
      properties:
        error:
          type: string
          nullable: true
        message:
          type: string
        data:
          $ref: '#/components/schemas/InvoiceExternalApiPaginatedResponse'
    InvoiceExternalApiPaginatedResponse:
      type: object
      properties:
        totalDocs:
          type: integer
        docs:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceExternalApiResponseDoc'
        hasNext:
          type: boolean
        hasPrev:
          type: boolean
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer
        prevPageNumber:
          type: integer
          nullable: true
        nextPageNumber:
          type: integer
          nullable: true
    InvoiceExternalApiResponseDoc:
      type: object
      description: One invoice document returned by `GET /external/invoices`.
      properties:
        id:
          type: string
          description: Internal Valyx invoice ID (UUID).
        invoiceId:
          type: string
          description: >-
            Caller-supplied invoice identifier (the value passed in `invoiceId`
            on upsert).
        invoiceNumber:
          type: string
        invoiceStatus:
          type: string
          enum:
            - OVERDUE
            - DUE
            - NO_DUES
            - VOID
        paymentStatus:
          type: string
          enum:
            - PAID
            - UNPAID
            - PARTIALLY_PAID
        invoiceDate:
          type: string
          format: date
        invoiceDueDate:
          type: string
          format: date
        promiseToPayDate:
          type: string
          format: date
        invoiceSubtotal:
          type: number
        invoiceTotal:
          type: number
        invoicePaidAmount:
          type: number
        invoiceAdjustedAmount:
          type: number
        invoiceOutstandingAmount:
          type: number
        writtenOffAmount:
          type: number
        roundOffAmount:
          type: number
        creditNoteAdjustedAmount:
          type: number
        invoiceTax:
          type: object
          description: Tax breakdown for the invoice.
        discount:
          type: object
          description: Discount details for the invoice.
        buyerId:
          type: string
          description: Caller-supplied buyer identifier.
        customerName:
          type: string
        lineItems:
          type: array
          description: Line items on the invoice.
          items:
            type: object
        referenceType:
          type: string
        referenceId:
          type: string
        referenceText:
          type: string
        createdAt:
          type: string
          description: >
            When the invoice was created in Valyx. Formatted as `YYYY-MM-DD
            HH:MM:SS` (UTC).

            Example: `2026-03-23 14:05:11`.
          example: '2026-03-23 14:05:11'
        updatedAt:
          type: string
          description: >
            When the invoice was last modified in Valyx. Formatted as
            `YYYY-MM-DD HH:MM:SS` (UTC).
          example: '2026-03-24 09:17:02'
        lifecycleStatus:
          type: string
          nullable: true
          enum:
            - DRAFT
            - FINALIZED
            - VOIDED
          description: >
            Lifecycle state of the invoice. `DELETED` invoices are never
            returned by this endpoint

            even when filtered for explicitly.
        invoiceOriginSource:
          type: string
          nullable: true
          enum:
            - ZOHO
            - IRECKONER
            - BOLTIC
            - VALYX
            - OTHER
          description: >
            Where the invoice originated. `null` is returned for legacy invoices
            that have no

            invoice-extra row.
        createdBy:
          type: object
          nullable: true
          description: >
            Creator attribution for the invoice. `null` for legacy invoices that
            pre-date the

            `created_by` column.
          properties:
            userId:
              type: string
              description: ID of the user who created the invoice in Valyx.
            userName:
              type: string
              nullable: true
              description: >
                Display name built from `firstName + lastName`. Can be `null`
                when the creator's

                user record could not be resolved (e.g. system-created
                invoices); treat `null` as

                "name unavailable" rather than an error.
        invoiceAmountAdjustments:
          type: array
          nullable: true
          items:
            type: object
        irnNumber:
          type: string
          nullable: true
        placeOfSupply:
          type: string
          nullable: true
        invoiceCurrency:
          type: string
          nullable: true
        erpId:
          type: string
          nullable: true
        invoiceTds:
          type: object
          nullable: true
        invoiceBillingAddress:
          type: object
          nullable: true
          description: Billing address captured on the invoice-extra row.
        invoiceShippingAddress:
          type: object
          nullable: true
          description: Shipping address captured on the invoice-extra row.
        invoiceGeneralTerms:
          type: string
          nullable: true
        invoicePaymentTerms:
          type: string
          nullable: true
        invoiceSellerDetails:
          type: object
          nullable: true
          description: >
            Seller details (GSTIN, address, bank account).
            `bankAccountDetails.bankAccountId` is

            stripped before being returned to external callers.
        billingPeriod:
          type: object
          nullable: true
          properties:
            startDate:
              type: string
              format: date
            endDate:
              type: string
              format: date
        einvoiceAcknowledgementNumber:
          type: integer
          nullable: true
        einvoiceAcknowledgedAt:
          type: string
          nullable: true
          description: ISO datetime when the e-invoice was acknowledged.
        buyerGstin:
          type: string
          nullable: true
          description: GSTIN of the buyer, sourced from the customer record at read time.

````