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

# Billing

> Read the invoices Venly has issued to your company, and download them as PDF.

[`GET /billing/invoices`](/api-reference/Finance-API/billing/list-invoices) lists the invoices Venly has
issued to your company. It needs the `view:billing` scope, which is separate from everything else
because the figures are commercially sensitive — ask Venly to grant it to the credential or dashboard
user that needs it. Invoices never show the **rates** behind a charge; for those,
[contact Venly](https://venlyfinance.com/contact).

```bash theme={null}
curl https://api-staging.venlyfinance.com/v1/billing/invoices \
  -H "Authorization: Bearer {access_token}"
```

```json Response (200) theme={null}
{
  "success": true,
  "result": {
    "content": [
      {
        "id": "7f68c0d4-4d55-4bd8-9b0e-1cfb0255c554",
        "invoiceNumber": "INV-042",
        "status": "SENT",
        "paymentStatus": "PAID",
        "currency": "EUR",
        "netTotal": "1250.00",
        "totalTax": "262.50",
        "grossTotal": "1512.50",
        "issueDate": "2026-09-01",
        "dueDate": "2026-09-15",
        "billingPeriodStart": "2026-08-01",
        "billingPeriodEnd": "2026-08-31",
        "sequenceUrl": "https://billing.example.com/invoices/7f68c0d4-4d55-4bd8-9b0e-1cfb0255c554",
        "createdAt": "2026-09-01T06:00:00Z"
      }
    ],
    "pagination": { "size": 100, "hasNextPage": false, "hasPreviousPage": false }
  }
}
```

Invoices are read live from our billing system — Finance stores none. Only **issued** invoices
(`status: SENT`) are visible; drafts and voided invoices are not. `paymentStatus` is the separate
collection status: `UNPAID`, `PARTIALLY_PAID`, `PAID` or `UNCOLLECTIBLE`. `sequenceUrl` is Venly's internal
reference to the invoice, not a page you can open. To read your invoices, open the billing portal at
`billingUrl` on [your company profile](/api-reference/Finance-API/company/get-your-company-profile), or
[download the PDF](/api-reference/Finance-API/billing/download-an-invoice-pdf).

### Two things that differ from other list endpoints

1. **Cursor pagination.** There is no `page`/`size` envelope. Send `pagination.nextPageCursor` or
   `previousPageCursor` back exactly as received; never construct one. A stale cursor is
   `400 invalid-cursor` — restart from the first page.
2. **`422 billing-not-configured` until Venly links your company** to a billing customer. Once linked,
   a company with no invoices yet gets an empty `content`.

### The PDF

[`GET /billing/invoices/{invoiceId}/download`](/api-reference/Finance-API/billing/download-an-invoice-pdf)
returns **raw PDF bytes** — not the JSON envelope — with a `Content-Disposition` filename derived from
the invoice number. Errors still arrive as JSON.

A `404` always means the invoice is not yours to read. An invoice you *can* read whose PDF cannot be
produced is `500 billing-provider-error`, so a rendering fault is never mistaken for a wrong id.

## Errors

| HTTP | `code` | Meaning |
| - | - | - |
| `400` | `invalid-cursor` | The cursor is stale or malformed; restart from the first page |
| `403` | `forbidden` | The token lacks `view:billing` |
| `404` | `invoice-not-found` | Unknown, foreign, unsent or voided invoice |
| `422` | `billing-not-configured` | Your company is not linked to a billing customer yet |
| `500` | `billing-provider-error` | The billing system rejected the request or could not render the PDF |
| `503` | `billing-provider-unavailable` | The billing system was unreachable. Retry |

## Next steps

<CardGroup cols={2}>
  <Card title="List invoices" icon="file-invoice" href="/api-reference/Finance-API/billing/list-invoices">
    The endpoint reference, with every field.
  </Card>

  <Card title="Your company profile" icon="building" href="/api-reference/Finance-API/company/get-your-company-profile">
    Where `billingUrl` — your billing portal — lives.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.