---
title: "Your invoices, newest first"
method: GET
path: "/api/v1/invoices"
tags: ["invoices"]
---

# Your invoices, newest first

`GET /api/v1/invoices`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/v1/invoices`
- Auth: HTTP bearer

Read from Orgo’s record of your invoices, so a new invoice is here as soon as it is made. Statuses and amounts follow Stripe: they are updated on each of Stripe’s invoice events and whenever you read, send or void one, so a payment can take a few seconds to show here; GET /api/v1/invoices/{id} reads Stripe at once. Pass `next_cursor` back as `cursor` for the next page, with the same filters.

## Query parameters

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

## Response `200`

A page of invoices.

- InvoiceList
  - `invoices` Invoice[], required
    - `id` string, required
    - `status` 'draft' | 'open' | 'paid' | 'void' | 'uncollectible', required
    - `amount` integer, required: Total, in cents.
    - `amount_paid` integer
    - `amount_remaining` integer
    - `currency` string, required
    - `url` string, nullable, required: Stripe’s hosted invoice page, where the customer pays.
    - `pdf_url` string, nullable
    - `number` string, nullable
    - `description` string, nullable
    - `customer` object
      - `email` string, nullable
      - `phone` string, nullable
      - `name` string, nullable
    - `line_items` object[]
      - `description` string, nullable
      - `quantity` integer
      - `unit_amount` integer, nullable
      - `amount` integer
    - `due_date` string, date-time, nullable
    - `created` string, date-time, required
    - `paid_at` string, date-time, nullable
    - `voided_at` string, date-time, nullable
    - `last_sent_at` string, date-time, nullable
    - `orgo_fee` integer: Orgo’s fee in cents: Stripe’s card and Invoicing fees.
    - `payout` integer: What reaches your bank when it is paid, in cents.
    - `workspace_id` string, uuid, nullable
    - `metadata` object
  - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null on the last.

## Other responses

- `400`: Bad status, workspace_id or cursor.
- `401`: Unauthenticated.
- `403`: Invoicing is off for this account, or a workspace-scoped key.
- `429`: Over one of the account's rate limits (rate_limited): `limit` names it, `retry_after` and Retry-After say how many seconds to wait. Limits are per account (the workspace owner when the request acts on a computer or a workspace) and set by its plan (x-rate-limits).
- `503`: Invoicing is not available yet (invoicing_unavailable).

## Changes

- **2026-11-01** `60e768a2bb9d`: 3 info
  - added the optional property `docs_url` to the response with the `400` status
  - added the optional property `next` to the response with the `400` status
  - added the optional property `retryable` to the response with the `400` status
- **2026-10-30** `afb6f0ee1aac`: 1 info
  - added the non-success response with the status `429`
- **2026-10-09** `41babeff7892`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/v1/invoices/get.md)

---

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