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

# Lists the service provider's invoices, filtered and sorted.

> Every filter is optional and combining two narrows to invoices that satisfy both. Each id
filter is a comma-separated list and an invoice matches if its id is any of them; a value
that is not an id is rejected with 400. A well-formed value that matches nothing is an empty
page, not a 404. Deleted invoices are never listed.

`SubTotal` is the line-item total before discount and tax; `Total` is
`SubTotal - TotalDiscount + TotalTax`. `AmountPaid` is computed live from recorded
payments, and `AmountDue` is `Total - AmountPaid`, floored at 0.

`InvoiceDate` and `DueDate` are calendar dates. `InvoiceDateSince`/`Before`
and `DueDateSince`/`Before` bound them the same way every other date filter on this
surface does: the lower bound includes the day it names and the upper bound excludes it.

`SortBy` is one of `createdOn` (default), `updatedOn`, `date` (InvoiceDate),
`dueDate` or `totalAmount`; `SortOrder` is `asc` or `desc` (default).




## OpenAPI

````yaml /api-reference/openapi.json get /v1/invoices
openapi: 3.0.4
info:
  title: Public API
  description: Gorelo Public API documentation.
  version: 1.0.0
servers:
  - url: https://api.usw.gorelo.io
    description: US
  - url: https://api.aue.gorelo.io
    description: Australia
security:
  - ApiKeyAuth: []
tags:
  - name: Attachments
    description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
  - name: Alerts
    description: Alerts management operations
  - name: Assets
    description: Assets management operations
  - name: Billing
    description: Billing management operations
  - name: Tickets
    description: Tickets management operations
  - name: Clients
    description: Clients management operations
  - name: Contacts
    description: Contacts management operations
  - name: Deletions
    description: Deletions management operations
  - name: Documents
    description: Documents management operations
  - name: Forms
    description: Forms management operations
  - name: Organization
    description: Organization management operations
  - name: Projects
    description: Projects management operations
paths:
  /v1/invoices:
    get:
      tags:
        - Billing
      summary: Lists the service provider's invoices, filtered and sorted.
      description: "Every filter is optional and combining two narrows to invoices that satisfy both. Each id\r\nfilter is a comma-separated list and an invoice matches if its id is any of them; a value\r\nthat is not an id is rejected with 400. A well-formed value that matches nothing is an empty\r\npage, not a 404. Deleted invoices are never listed.\r\n\n`SubTotal` is the line-item total before discount and tax; `Total` is\r\n`SubTotal - TotalDiscount + TotalTax`. `AmountPaid` is computed live from recorded\r\npayments, and `AmountDue` is `Total - AmountPaid`, floored at 0.\r\n\n`InvoiceDate` and `DueDate` are calendar dates. `InvoiceDateSince`/`Before`\r\nand `DueDateSince`/`Before` bound them the same way every other date filter on this\r\nsurface does: the lower bound includes the day it names and the upper bound excludes it.\r\n\n`SortBy` is one of `createdOn` (default), `updatedOn`, `date` (InvoiceDate),\r\n`dueDate` or `totalAmount`; `SortOrder` is `asc` or `desc` (default).\r\n"
      operationId: get_v1_invoices
      parameters:
        - name: Cursor
          in: query
          description: >-
            Opaque pagination cursor from a previous page; omit for the first
            page. Only valid against the same filters and sort that produced it.
          schema:
            type: string
        - name: PageSize
          in: query
          description: >-
            Number of items per page. 1-200 (default 50); out of range is a 400,
            never clamped.
          schema:
            type: integer
            format: int32
            default: 50
        - name: ClientIds
          in: query
          description: >-
            Comma-separated client ids; keeps only invoices billed to any of
            them.
          schema:
            type: string
        - name: StatusIds
          in: query
          description: >-
            Comma-separated status ids: 1 Draft, 2 Submitted, 3 Paid, 4 Void, 5
            Approved. Any other id is a 400. Omitted returns every status;
            deleted invoices are never listed.
          schema:
            type: string
        - name: ContractIds
          in: query
          description: >-
            Comma-separated contract ids; keeps only invoices raised from any of
            them.
          schema:
            type: string
        - name: Number
          in: query
          description: >-
            Exact match on the invoice's bare sequential number (the wire's
            `Number`, not `DisplayNumber`). A value that does not parse as a
            whole number is a 400.
          schema:
            type: string
        - name: InvoiceDateSince
          in: query
          description: Keeps only invoices dated at or after this date.
          schema:
            type: string
            format: date-time
        - name: InvoiceDateBefore
          in: query
          description: Keeps only invoices dated strictly before this date.
          schema:
            type: string
            format: date-time
        - name: DueDateSince
          in: query
          description: Keeps only invoices due at or after this date.
          schema:
            type: string
            format: date-time
        - name: DueDateBefore
          in: query
          description: Keeps only invoices due strictly before this date.
          schema:
            type: string
            format: date-time
        - name: IsEmailSent
          in: query
          description: >-
            Keeps only invoices that have (true) or have not (false) been
            emailed to the client.
          schema:
            type: boolean
        - name: CreatedSince
          in: query
          description: Keeps only invoices created at or after this instant.
          schema:
            type: string
            format: date-time
        - name: CreatedBefore
          in: query
          description: Keeps only invoices created at or before this instant.
          schema:
            type: string
            format: date-time
        - name: UpdatedSince
          in: query
          description: Keeps only invoices last updated at or after this instant.
          schema:
            type: string
            format: date-time
        - name: UpdatedBefore
          in: query
          description: Keeps only invoices last updated at or before this instant.
          schema:
            type: string
            format: date-time
        - name: Query
          in: query
          description: Free-text search against the invoice number, reference and name.
          schema:
            type: string
        - name: SortBy
          in: query
          description: >-
            Sort field: createdOn (default), updatedOn, date, dueDate or
            totalAmount.
          schema:
            type: string
            default: createdOn
        - name: SortOrder
          in: query
          description: 'Sort direction: asc or desc (default).'
          schema:
            type: string
            default: desc
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InvoiceModelListBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceModelListBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/InvoiceModelListBaseResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
components:
  schemas:
    InvoiceModelListBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceModel'
          nullable: true
        DataContext:
          $ref: '#/components/schemas/PaginationDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ObjectBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          nullable: true
        DataContext:
          $ref: '#/components/schemas/ErrorDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    HttpStatusCode:
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 421
        - 422
        - 423
        - 424
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
      type: integer
      format: int32
    InvoiceModel:
      type: object
      properties:
        Id:
          type: string
          description: Identifier of the invoice.
          format: uuid
          example: 3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44
        Number:
          type: integer
          description: The bare sequential invoice number, prefix and suffix stripped.
          format: int64
          nullable: true
          example: 1042
        DisplayNumber:
          type: string
          description: >-
            Human-readable invoice number, including the service provider's
            configured prefix/suffix.
          example: INV-1042
        ClientId:
          type: integer
          description: Client the invoice is billed to.
          format: int64
          example: 88
        ContractId:
          type: integer
          description: "Contract this invoice was raised from, or null. A manual invoice created through\r\n`POST /v1/invoices` always has no contract — `ContractId` is accepted only on\r\ncontract-generated invoices, which this surface does not create."
          format: int64
          nullable: true
          example: 4021
        Status:
          $ref: '#/components/schemas/CodeModel'
        InvoiceDate:
          type: string
          description: >-
            Date the invoice was raised, a calendar date in the service
            provider's terms.
          format: date
          example: '2026-09-01'
        DueDate:
          type: string
          description: >-
            Date payment is due, a calendar date. Never earlier than
            InvoiceDate.
          format: date
          nullable: true
          example: '2026-10-01'
        SubTotal:
          type: number
          description: Sum of the invoice's line items before discount and tax.
          format: double
          example: 1200
        TotalDiscount:
          type: number
          description: Total discount amount across the invoice's line items.
          format: double
          example: 60
        TotalTax:
          type: number
          description: Total tax across the invoice's line items.
          format: double
          example: 85.5
        Total:
          type: number
          description: 'Grand total: SubTotal - TotalDiscount + TotalTax.'
          format: double
          example: 1225.5
        AmountPaid:
          type: number
          description: >-
            Amount paid against this invoice so far. Computed live from recorded
            payments.
          format: double
          example: 500
        AmountDue:
          type: number
          description: >-
            Amount still owed: Total - AmountPaid. Never negative on the wire; a
            credit is reported as 0.
          format: double
          example: 725.5
        Reference:
          type: string
          description: Free-text reference on the invoice, or null when not set.
          nullable: true
          example: PO-4471
        ExternalId:
          type: string
          description: >-
            Identifier of this invoice in the connected external accounting
            system (Xero or QuickBooks), or null when not yet synced.
          nullable: true
        PaymentLink:
          type: string
          description: >-
            Hosted payment link for this invoice, or null when none has been
            generated.
          nullable: true
        InvoiceTemplateId:
          type: integer
          description: Invoice template used to render this invoice's PDF.
          format: int64
          nullable: true
        InvoiceEmailTemplateId:
          type: integer
          description: Email template used when this invoice is sent.
          format: int64
          nullable: true
        BrandingThemeId:
          type: string
          description: Branding theme applied in the connected accounting system.
          format: uuid
          nullable: true
        IsEmailSent:
          type: boolean
          description: Whether this invoice has been emailed to the client.
        EmailSentOn:
          type: string
          description: When this invoice was last emailed, in UTC, or null if never.
          format: date-time
          nullable: true
        CreatedOn:
          type: string
          description: When the invoice was created, in UTC.
          format: date-time
          nullable: true
        UpdatedOn:
          type: string
          description: >-
            When the invoice was last changed, in UTC. Null when it has never
            been changed.
          format: date-time
          nullable: true
      additionalProperties: false
      description: One invoice, in the shape `GET /v1/invoices` returns each list row in.
    PaginationDataContext:
      type: object
      properties:
        Pagination:
          $ref: '#/components/schemas/PaginatedResponse'
      additionalProperties: false
      description: "The `DataContext` of a cursor-paginated success response: carries the paging metadata\r\nfor the returned page."
    Error:
      type: object
      properties:
        Code:
          pattern: ^[0-9]{6}$
          type: string
          description: 6-digit MMTTNN error code. See the Public API error-code registry.
          example: '070101'
        Message:
          type: string
        PropertyName:
          type: string
          nullable: true
        ActionHint:
          type: string
          nullable: true
        DocUrl:
          type: string
          nullable: true
      additionalProperties: false
    ErrorDataContext:
      type: object
      properties:
        TraceId:
          type: string
          description: Request correlation id. Quote this when reporting a problem.
          nullable: true
      additionalProperties: false
      description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
    CodeModel:
      type: object
      properties:
        Id:
          type: integer
          description: >-
            Numeric identifier of the coded value (e.g. status, priority, type,
            or source id).
          format: int64
          example: 1
        Name:
          type: string
          description: Display name of the coded value.
      additionalProperties: false
      description: >-
        A coded value, such as a status, priority, type or source, as an id and
        a display name.
    PaginatedResponse:
      type: object
      properties:
        NextCursor:
          type: string
          nullable: true
        PreviousCursor:
          type: string
          nullable: true
        HasMore:
          type: boolean
        HasPrevious:
          type: boolean
        TotalCount:
          type: integer
          format: int32
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        Your Gorelo API key. See [Generate API key](/generate-api-key). If your
        data is hosted in Australia, click the base URL at the top of this page
        and select `https://api.aue.gorelo.io`.
      name: X-API-Key
      in: header

````

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