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

# List Invoices

> Returns invoice headers ordered by `period_start` descending. `finality`
distinguishes a running estimate from a final invoice.



## OpenAPI

````yaml /api-reference/customer-api.v1.openapi.json get /v1/admin/billing/invoices
openapi: 3.1.0
info:
  title: Mount Thor Customer API
  version: v1
servers:
  - description: Mount Thor customer API edge
    url: https://api.mountthor.com
security: []
paths:
  /v1/admin/billing/invoices:
    get:
      tags:
        - billing
      summary: List Invoices
      description: |-
        Returns invoice headers ordered by `period_start` descending. `finality`
        distinguishes a running estimate from a final invoice.
      operationId: list_customer_billing_invoices
      parameters:
        - description: >-
            Optional status filter: `draft`, `open`, `finalized`, `paid`,
            `void`, or `uncollectible`.
          in: query
          name: status
          required: false
          schema:
            type: string
        - description: Optional inclusive lower bound on `period_start` (YYYY-MM-DD).
          in: query
          name: period_after
          required: false
          schema:
            type: string
        - description: Page size, clamped to [1, 200]; default 50.
          in: query
          name: limit
          required: false
          schema:
            format: int64
            type: integer
        - description: Result offset for pagination; default 0.
          in: query
          name: offset
          required: false
          schema:
            format: int64
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBillingInvoicesListResponse'
          description: Success
        '400':
          description: Invalid status filter or period_after format
        '401':
          description: Missing or invalid bearer credential
        '403':
          description: >-
            Credential is missing billing:read scope, or the human session is
            neither an Administrator nor a billing-owner for this customer
        '429':
          content:
            text/plain:
              schema:
                type: string
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds before retry.
              schema:
                minimum: 1
                type: integer
      security:
        - api_key_bearer:
            - billing:read
components:
  schemas:
    CustomerBillingInvoicesListResponse:
      additionalProperties: false
      description: Customer invoice list response.
      properties:
        customer_id:
          description: Stable UUID for the customer account.
          type: string
        invoices:
          description: |-
            Invoices ordered by `period_start` descending (nulls last)
            then by `created_at` descending so the most recent period is
            first.
          items:
            $ref: '#/components/schemas/InvoiceMetadata'
          type: array
        total_count:
          description: |-
            Total number of invoices matching the filter (independent of
            `limit`/`offset`) so clients can implement pagination
            indicators.
          format: int64
          type: integer
      required:
        - customer_id
        - invoices
        - total_count
      type: object
    InvoiceMetadata:
      additionalProperties: false
      description: |-
        Header metadata for a single invoice, in a list response or as the
        header of a detail response. Invoices come from Mount Thor's billing
        provider: a draft invoice tracks the running period and is finalized
        as that period closes — see `status` and `finality`. Line-item detail
        and payment live on the provider-hosted invoice, so this surface
        carries headers only.
      properties:
        created_at:
          description: When Mount Thor first recorded this invoice.
          type: string
        credits_applied_cents:
          description: >-
            Credits and prepaid commits applied to rated usage. Null under the
            same

            incomplete-line-item condition as `gross_usage_cents`.
          format: int64
          type:
            - integer
            - 'null'
        currency:
          description: ISO 4217 currency code.
          example: USD
          type: string
        customer_id:
          description: Stable UUID for the customer account.
          type: string
        finality:
          description: |-
            How settled the money figure is: `estimate` (running period,
            updates at close), `pending_close`, `final` (authoritative),
            or `corrected` (voided/adjusted). Clients MUST NOT render an
            `estimate`/`pending_close` total as official invoice state.
          example: final
          type: string
        gross_usage_cents:
          description: |-
            Rated usage before credits/commits. Null when the provider has not
            yet reported line items for this invoice.
          format: int64
          type:
            - integer
            - 'null'
        hosted_invoice_url:
          description: |-
            Provider-hosted invoice page; line-item detail and payment live
            there.
          type:
            - string
            - 'null'
        invoice_id:
          description: Stable Mount Thor UUID for the invoice.
          example: 00000000-0000-0000-0000-000000000000
          type: string
        invoice_pdf_url:
          description: Provider-hosted invoice PDF.
          type:
            - string
            - 'null'
        paid_at:
          description: When the provider reported the invoice paid.
          type:
            - string
            - 'null'
        period_end:
          description: End of the billed period, when the provider reported one.
          example: '2026-08-01'
          type:
            - string
            - 'null'
        period_start:
          description: |-
            Inclusive start of the billed period, when the provider
            reported one.
          example: '2026-07-01'
          type:
            - string
            - 'null'
        status:
          description: |-
            Provider invoice/payment state: one of `draft`, `open`,
            `finalized`, `paid`, `void`, `uncollectible`.
          example: open
          type: string
        total_cents:
          description: >-
            Net amount due in cents after credits and prepaid commits, as last

            reported by the provider. Retains the historical `total_cents` wire
            name.
          format: int64
          type: integer
      required:
        - invoice_id
        - customer_id
        - status
        - finality
        - total_cents
        - currency
        - created_at
      type: object
  securitySchemes:
    api_key_bearer:
      bearerFormat: mthr_live_*
      description: Bearer scheme name used by typed customer admin operations.
      scheme: bearer
      type: http

````