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

# List invoices

> List the workspace's invoices, newest issue date first, 30 per page by default and up to 100. Deleted invoices are left out.

> [!NOTE]
>
> Replace `{your-subdomain}` with your workspace's subdomain. \
> Learn how to find your subdomain in [Workspace subdomain](/api/workspace-subdomain.md).


## OpenAPI

````yaml bundled/invoices.yaml GET /invoices
openapi: 3.0.3
info:
  title: NeetoInvoice APIs
  version: 2.0.0
servers:
  - description: NeetoInvoice APIs
    url: https://{your-subdomain}.neetoinvoice.com/api/external/v2
    variables:
      your-subdomain:
        default: spinkart
        description: >-
          Replace **spinkart** with your [workspace's
          subdomain](/api/workspace-subdomain).
security: []
paths:
  /invoices:
    get:
      tags:
        - Invoices
      summary: List invoices
      description: >-
        List the workspace's invoices, newest issue date first, 30 per page by
        default and up to 100. Deleted invoices are left out.
      parameters:
        - $ref: '#/components/parameters/api_key_header'
        - in: query
          name: client_id
          description: >-
            Only this client's invoices. Accepts the client's identifier or ID.
            Refer to [Getting the Client ID](/api/getting-client-id) section for
            detailed instructions.
          required: false
          schema:
            type: string
          example: a8b90a464cad12b48e45
        - in: query
          name: status
          description: Only invoices with this status.
          required: false
          schema:
            type: string
            enum:
              - generating
              - generated
              - paid
              - written_off
              - failed
              - pending_payment
          example: generated
        - in: query
          name: overdue
          description: >-
            Set to `true` to list only unpaid invoices whose due date is before
            today.
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          example: 'true'
        - in: query
          name: start_date
          description: Only invoices issued on or after this date in `YYYY-MM-DD` format
          required: false
          schema:
            type: string
            format: date
          example: '2026-10-01'
        - in: query
          name: end_date
          description: Only invoices issued on or before this date in `YYYY-MM-DD` format
          required: false
          schema:
            type: string
            format: date
          example: '2026-10-31'
        - $ref: '#/components/parameters/page_param'
        - $ref: '#/components/parameters/page_size_param'
      responses:
        '200':
          description: OK - Request succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invoice_list_response'
        '404':
          description: Not Found - The client does not exist
        '422':
          description: Unprocessable Entity - Invalid date, date range or status
components:
  parameters:
    api_key_header:
      in: header
      name: X-Api-Key
      description: >-
        Use the X-Api-Key header to provide your workspace API key. Refer to
        [Authentication](/api/authentication) for more information.
      required: true
      schema:
        type: string
        default: your-api-key
    page_param:
      in: query
      name: page
      description: >-
        Page of results to retrieve, starting from 1. Defaults to 1 when
        omitted.
      required: false
      schema:
        type: integer
      example: 1
    page_size_param:
      in: query
      name: page_size
      description: Number of results per page. Defaults to 30 when omitted.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
  schemas:
    invoice_list_response:
      allOf:
        - $ref: '#/components/schemas/list_pagination_fields'
        - type: object
          properties:
            invoices:
              type: array
              items:
                $ref: '#/components/schemas/invoice_list_item'
    list_pagination_fields:
      type: object
      properties:
        total_count:
          type: integer
          description: Total number of records across all pages.
          example: 1
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of records per page.
          example: 30
        total_pages:
          type: integer
          description: Total number of pages.
          example: 1
        next_page:
          type: integer
          nullable: true
          description: Next page number, or null on the last page.
          example: null
        prev_page:
          type: integer
          nullable: true
          description: Previous page number, or null on the first page.
          example: null
    invoice_list_item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        identifier:
          type: string
          nullable: true
          example: a1b2c3
        number:
          type: string
          example: INV-2026-030
        status:
          type: string
          enum:
            - generating
            - generated
            - paid
            - written_off
            - failed
            - pending_payment
          example: generated
        client_id:
          type: string
          format: uuid
        client_name:
          type: string
          example: Acme
        currency:
          type: string
          example: USD
        issue_date:
          type: string
          format: date
          example: '2026-08-20'
        due_date:
          type: string
          format: date
          nullable: true
          example: '2026-09-04'
        sent_date:
          type: string
          format: date
          nullable: true
          example: '2026-08-20'
        total:
          type: number
          format: float
          description: Total before tax.
          example: 2400
        grand_total:
          type: number
          format: float
          description: Amount billed after discount and tax.
          example: 2400
        amount_paid:
          type: number
          format: float
          description: Payments recorded against the invoice.
          example: 0
        amount_due:
          type: number
          format: float
          description: Amount still owed. 0 once the invoice is paid or written off.
          example: 2400
        days_overdue:
          type: integer
          description: >-
            Days past the due date while the invoice is unpaid. 0 when not
            overdue.
          example: 41

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.