# listInvoices

`GET /apis/cra.diagrid.io/v1beta1/billing/invoices`

List the organization's billing invoices (read live from Stripe), newest-first with cursor pagination.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Maximum number of invoices to return per page. Default: `20`. |
| `startingAfter` | string | No | Cursor for pagination: a Stripe invoice id (in_...). Returns the page of invoices immediately after this id. |

## Responses

### 200 — [OK](https://jsonapi.org/format/#fetching-resources-responses-200)

`application/json`

A page of the organization's billing invoices, ordered newest-first.

- `invoices` (object[]) — The invoices in this page, ordered newest-first (Stripe default).
  - `id` (string) — The Stripe invoice id (in_...).
  - `number` (string) — Human-facing invoice number; may be empty for drafts.
  - `created` (string) — RFC3339 timestamp when the invoice was created.
  - `periodStart` (string) — RFC3339 timestamp for the start of the billing period.
  - `periodEnd` (string) — RFC3339 timestamp for the end of the billing period.
  - `amountDue` (integer) — Amount due, in minor units (cents).
  - `amountPaid` (integer) — Amount paid, in minor units (cents).
  - `amountRemaining` (integer) — Amount remaining, in minor units (cents).
  - `currency` (string) — ISO currency code, e.g. "usd".
  - `status` (string) — The invoice's current status. One of: `draft`, `open`, `paid`, `uncollectible`, `void`.
  - `hostedInvoiceUrl` (string) — Stripe-hosted invoice URL; empty if absent.
  - `invoicePdf` (string) — URL to the invoice PDF; empty if absent.
- `hasMore` (boolean) — Whether more invoices are available beyond this page.
- `nextStartingAfter` (string) — Nullable. The invoice id to pass as startingAfter for the next page; null when hasMore is false.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

`application/vnd.api+json`

JSONAPI.org specification error response wrapper for UI.

- `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.
  - `code` (string) — Required. This is the same as the HTTP status of the response.
  - `message` (string) — Required. A short description of the error.
  - `status` (object) — Required. A status code that indicates the error type.
  - `details` (object) — Additional details about the errors.
    - `@type` (string) — The type of error.
    - `reason` (string) — A reason for the error.
    - `domain` (string) — The domain in which the error occurred.
    - `metadata` (object) — Additional metadata about the error.
- `meta` (object<string, object>) — Link members related to the primary data.
  - One of:
    - **string (uri-reference)** — A string containing the link's URL.
    - **object**
      - `href` (string (uri-reference)) — Required. A string containing the link's URL.
      - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.
- `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.