---
title: "List invoices"
method: GET
path: "/invoices"
tags: ["Invoices"]
---

# List invoices

`GET /invoices`

## Request

- Base URL: `https://api.togai.com`
- URL: `https://api.togai.com/invoices`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/togaihq/apis/togai-apis/docs/invoices/get.ts> (a function with typed inputs; its response is checked against the schema)

List invoices

## Query parameters

- `nextToken` string
- `status` string
- `owner_id` string
- `customer_id` string
- `pageSize` integer
- `start_time` integer
- `end_time` integer

## Response `200`

Success response

- ListInvoicesResponse: List invoices response
  - `data` InvoiceSummary[], required
    - `id` string, required: Identifier of invoice
    - `customerId` string
    - `ownerId` string
    - `pricePlanId` string
    - `status` 'DRAFT' | 'DUE' | 'PAID' | 'VOID' | 'UN_COLLECTIBLE' | 'REFUND_INITIATED' | 'REFUND_COMPLETED' | 'MERGED' | 'PARTIALLY_PAID', required: Status of the invoice
    - `finalizingStatus` 'FINALIZING' | 'FINALIZED'
    - `invoiceClass` 'INVOICE' | 'ORDER' | 'BILLABLE', required: Represents the class of entity( INVOICE/ORDER/BILLABLE)
    - `invoiceType` 'STANDARD' | 'AD_HOC' | 'CUSTOM' | 'COMPOSITE' | 'STANDARD_ADVANCED' | 'ADHOC_ADVANCED', required: Represents the type of entity(STANDARD/AD_HOC/COMPOSITE)
    - `startDate` string, date-time: Start date of the invoice
    - `endDate` string, date-time: End date of the invoice
    - `endDateInclusive` string, date-time: Inclusive end date of the invoice
    - `invoiceDate` string, date-time, required: Invoice date of the invoice
    - `dueDate` string, date-time: Due date of the invoice
    - `generatedAt` string, date-time
    - `updatedAt` string, date-time, required
    - `sequenceId` string: Sequence id of the invoice
    - `pdfUrl` string: Download URL of the pdf file corresponding to the invoice
    - `totalAmount` number, required
    - `paidAmount` number, required
    - `invoiceDetails` InvoiceDetails
      - `customer` object
        - `name` string, required
        - `primaryEmail` string, required
        - `billingAddress` string
        - `address` Address: billing address of the customer
          - `phoneNumber` string: Contact number
          - `line1` string: Address line 1 (eg. Street, PO Box, Company Name)
          - `line2` string: Address line 2 (eg. apartment, suite, unit or building)
          - `postalCode` string: ZIP or postal code
          - `city` string: City, district, suburb, town or village
          - `state` string: State, county, province or region
          - `country` string: Two letter country code [ISO-3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
      - `account` object
        - `name` string, required
        - `invoiceCurrency` string, required
        - `address` Address, required: billing address of the customer
          - `phoneNumber` string: Contact number
          - `line1` string: Address line 1 (eg. Street, PO Box, Company Name)
          - `line2` string: Address line 2 (eg. apartment, suite, unit or building)
          - `postalCode` string: ZIP or postal code
          - `city` string: City, district, suburb, town or village
          - `state` string: State, county, province or region
          - `country` string: Two letter country code [ISO-3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
        - `primaryEmail` string, required
      - `pricePlanName` string
      - `invoiceGroup` object
        - `id` string, required
        - `name` string, required
        - `email` string
        - `dailyInvoiceConsolidation` boolean, required
        - `invoiceCurrency` string, required
        - `address` Address, required: billing address of the customer
          - `phoneNumber` string: Contact number
          - `line1` string: Address line 1 (eg. Street, PO Box, Company Name)
          - `line2` string: Address line 2 (eg. apartment, suite, unit or building)
          - `postalCode` string: ZIP or postal code
          - `city` string: City, district, suburb, town or village
          - `state` string: State, county, province or region
          - `country` string: Two letter country code [ISO-3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
      - `organization` object
        - `businessName` string, required
        - `address` Address, required: billing address of the customer
          - `phoneNumber` string: Contact number
          - `line1` string: Address line 1 (eg. Street, PO Box, Company Name)
          - `line2` string: Address line 2 (eg. apartment, suite, unit or building)
          - `postalCode` string: ZIP or postal code
          - `city` string: City, district, suburb, town or village
          - `state` string: State, county, province or region
          - `country` string: Two letter country code [ISO-3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
        - `primaryEmail` string, required
        - `metadata` object
      - `logoUrl` string
    - `netTermDays` integer, required: Number of days from the invoice date after which an invoice is considered overdue.
  - `nextToken` string

## Other responses

- `400`: Bad request. Please check the response message for failure details.
- `401`: Credential is not valid. Please check the response message for failure details.
- `403`: Credential does not have access to this operation.
- `422`: Unable to process the query parameters provided. Please check our docs for the api limits - https://togai.io/docs/limits.
- `429`: Request throttled. Please check the response message on the failure details.
- `default`: Error response

## Changes

- **2024-07-11** `65e7e87bb244`: 2 warning
  - added the new `ADHOC_ADVANCED` enum value to the `data/items/invoiceType` response property for the response status `200`
  - added the new `STANDARD_ADVANCED` enum value to the `data/items/invoiceType` response property for the response status `200`
- **2024-04-18** `f22fc08442b7`: 1 info
  - added the required property `data/items/netTermDays` to the response with the `200` status
- **2024-03-26** `3ef670952b0b`: 1 info
  - added the optional property `data/items/finalizingStatus` to the response with the `200` status
- **2024-03-01** `6fb940b0dad9`: 6 warning, 3 info
  - removed the optional property `data/items/info` from the response with the `200` status
  - removed the optional property `data/items/metadata` from the response with the `200` status
  - removed the optional property `data/items/revenueInfo` from the response with the `200` status
  - removed the optional property `data/items/usageInfo` from the response with the `200` status
  - …5 more
- **2024-01-05** `ea9c4628bfdb`: 1 info
  - added the optional property `data/items/endDateInclusive` to the response with the `200` status

[Operation history](https://skmtc.dev/togaihq/apis/togai-apis/changes/invoices/get.md)

---

[API](https://skmtc.dev/togaihq/apis/togai-apis.md) - [All operations](https://skmtc.dev/togaihq/apis/togai-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/togaihq/apis/togai-apis/revisions/442f5d8f4aa0?raw)