---
title: "POST /v1/invoices.list"
method: POST
path: "/v1/invoices.list"
tags: ["invoices"]
---

# POST /v1/invoices.list

`POST /v1/invoices.list`

Lists invoices with cursor pagination and optional filters (customer, entity, status, processor). Pass `start_cursor: ""` (or omit) for the first page; use `next_cursor` from a prior response for subsequent pages.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `start_cursor` string — Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.
  - `limit` integer — Number of items to return. Default 50, hard ceiling 5000.
  - `customer_id` string — Filter invoices to a single customer by ID.
  - `entity_id` string — Filter invoices to a single entity by ID. Must be provided together with customer_id, since entity IDs are only unique per customer.
  - `status` string[] — Filter by invoice status (draft, open, paid, void, uncollectible).
  - `processor_types` string[] — Filter by billing processor (stripe, revenuecat). Invoices recorded before processor tracking count as stripe.

## Response `200`

OK

- object
  - `list` object[], required — Items for current page.
    - `plan_ids` string[], required — Array of plan IDs included in this invoice
    - `stripe_id` string, required — The Stripe invoice ID
    - `processor_type` 'stripe' | 'revenuecat' — The billing processor that owns this invoice.
    - `status` string, required — The status of the invoice
    - `total` number, required — The total amount of the invoice
    - `currency` string, required — The currency code for the invoice
    - `created_at` number, required — Timestamp when the invoice was created
    - `hosted_invoice_url` string, nullable — URL to the Stripe-hosted invoice page
    - `id` string, required — The Autumn invoice ID
    - `customer_id` string, nullable, required — The ID of the customer this invoice belongs to. Null for customers created without an ID.
    - `entity_id` string, nullable, required — The ID of the entity this invoice belongs to, if entity-scoped
    - `amount_paid` number, nullable, required — The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
    - `refunded_amount` number, required — The total amount refunded on the invoice
  - `next_cursor` string, nullable, required — Opaque cursor for the next page. Null when there are no more results.

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/versions/29536933c0dc/schema)