---
title: "Invoice history"
method: GET
path: "/v2/billing/invoices"
tags: ["billing"]
---

# Invoice history

`GET /v2/billing/invoices`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/billing/invoices`
- Auth: HTTP bearer

Return a page of Stripe invoice history.

## Query parameters

- `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void', nullable
- `limit` integer
- `cursor` string, nullable

## Response `200`

Successful Response

- InvoicePage: One page of invoice history.
  - `invoices` BilledInvoice[], required: This page of invoices, newest first.
    - `id` string, required: Stripe invoice id (`in_…`).
    - `number` string, nullable, required: Human-facing invoice number; null while draft.
    - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void', required: Collection state: open = finalized and awaiting payment.
    - `created` string, date-time, required: When the invoice was created.
    - `due_date` string, date-time, nullable, required: Payment due date; null for charge-automatically invoices.
    - `paid_at` string, date-time, nullable, required: When payment landed; null until paid.
    - `currency` string, required: Upper-case ISO currency code.
    - `subtotal` string, decimal, required: Pre-tax subtotal.
    - `tax` string, decimal, nullable, required: Total tax; null when not yet computed.
    - `total` string, decimal, required: Total including tax.
    - `amount_due` string, decimal, required: What remains to collect.
    - `amount_paid` string, decimal, required: What has been collected.
    - `hosted_invoice_url` string, nullable, required: Stripe-hosted page to view (and pay) the invoice.
    - `pdf_url` string, nullable, required: Downloadable invoice PDF.
    - `lines` BilledInvoiceLine[], required: Invoice lines as billed.
      - `description` string, nullable, required: The line label as invoiced.
      - `quantity` string, decimal, nullable, required: Quantity, when the line carries one.
      - `amount` string, decimal, required: Line amount in the invoice currency; negative = credit.
  - `next_cursor` string, nullable, required: Pass as `?cursor=` for the next page; null when exhausted.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stuut/apis/stuut-api.md) - [All operations](https://skmtc.dev/stuut/apis/stuut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stuut/apis/stuut-api/revisions/ff0ad16a55ff?raw)